feat: add eventual consistency monitor pattern

README.md

@@ -473,11 +473,11 @@ var cachedRemoteProxy = Proxy<int, string>.Create(id => remoteProxy.Execute(id))
 ---
 
 ## Patterns Table
-PatternKit currently tracks 113 production-readiness patterns. Each catalog pattern is represented in tests, documentation, real-world examples, IoC integration, and the BenchmarkDotNet coverage matrix.
+PatternKit currently tracks 114 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 | 25 | 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, Snapshot / Checkpoint Management, Specification, Table Data Gateway, Timeout Manager, Transaction Script, Unit of Work, Value Object, Workflow Orchestration |
+| Application Architecture | 26 | Activity Tracker, Aggregate Root, Anti-Corruption Layer, Audit Log, Bounded Context, Context Map, CQRS, Data Mapper, Domain Event, Domain Service, Event Sourcing, Eventual Consistency Monitor, Feature Toggle, Identity Map, Manual Task Gate, Materialized View, Repository, Service Layer, Snapshot / Checkpoint Management, 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 |
@@ -503,6 +503,8 @@ BenchmarkDotNet guidance is documented in [docs/guides/benchmarks.md](docs/guide
 | Workflow Orchestration | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Snapshot / Checkpoint Management | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Snapshot / Checkpoint Management | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Eventual Consistency Monitor | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Eventual Consistency Monitor | 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/EventualConsistencyMonitorBenchmarks.cs

@@ -0,0 +1,29 @@
+using BenchmarkDotNet.Attributes;
+using PatternKit.Application.EventualConsistency;
+using PatternKit.Examples.EventualConsistencyDemo;
+
+namespace PatternKit.Benchmarks.Application;
+
+[BenchmarkCategory("ApplicationArchitecture", "EventualConsistencyMonitor")]
+public class EventualConsistencyMonitorBenchmarks
+{
+    [Benchmark(Baseline = true, Description = "Fluent: create eventual consistency monitor")]
+    [BenchmarkCategory("Fluent", "Construction")]
+    public EventualConsistencyMonitor<string> Fluent_CreateEventualConsistencyMonitor()
+        => OrderProjectionConsistencyPolicies.CreateFluentMonitor();
+
+    [Benchmark(Description = "Generated: create eventual consistency monitor")]
+    [BenchmarkCategory("Generated", "Construction")]
+    public EventualConsistencyMonitor<string> Generated_CreateEventualConsistencyMonitor()
+        => GeneratedOrderProjectionConsistencyMonitor.CreateMonitor();
+
+    [Benchmark(Description = "Fluent: record order projection consistency")]
+    [BenchmarkCategory("Fluent", "Execution")]
+    public OrderProjectionConsistencySummary Fluent_RecordOrderProjectionConsistency()
+        => OrderProjectionConsistencyDemo.RunFluent();
+
+    [Benchmark(Description = "Generated: record order projection consistency")]
+    [BenchmarkCategory("Generated", "Execution")]
+    public OrderProjectionConsistencySummary Generated_RecordOrderProjectionConsistency()
+        => OrderProjectionConsistencyDemo.RunGenerated();
+}

docs/examples/index.md

@@ -20,6 +20,7 @@ Welcome! This section collects small, focused demos that show **how to compose b
 * **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.
 * **Snapshot / checkpoint management** for resumable event stream replay and projection rebuilds.
+* **Eventual consistency monitoring** for projection and integration lag visibility.
 
 ## Demos in this section
 
@@ -47,6 +48,9 @@ Welcome! This section collects small, focused demos that show **how to compose b
 * **Order Replay Snapshot Checkpoint Management**
   A Generic Host importable replay service with fluent and source-generated checkpoint manager routes for event-sourced order rebuilds. See [Order Replay Snapshot Checkpoint Management](order-replay-snapshot-checkpoint.md).
 
+* **Order Projection Eventual Consistency Monitor**
+  A Generic Host importable monitor with fluent and source-generated routes for source/target watermark convergence. See [Order Projection Eventual Consistency Monitor](order-projection-eventual-consistency-monitor.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/order-projection-eventual-consistency-monitor.md

@@ -0,0 +1,23 @@
+# Order Projection Eventual Consistency Monitor
+
+This example models an order projection monitor that compares the event stream source watermark with the projection target watermark. It reports lagging projections until the target catches up within the configured threshold.
+
+The fluent path builds the monitor directly:
+
+```csharp
+var monitor = OrderProjectionConsistencyPolicies.CreateFluentMonitor();
+```
+
+The generated path uses a source-generated factory:
+
+```csharp
+var monitor = GeneratedOrderProjectionConsistencyMonitor.CreateMonitor();
+```
+
+The example is importable through standard dependency injection:
+
+```csharp
+services.AddOrderProjectionConsistencyDemo();
+```
+
+`OrderProjectionConsistencyService` records source and target progress for an order projection. Production applications can feed it from event-store positions, outbox delivery offsets, replica checkpoints, or projection table versions.

docs/examples/toc.yml

@@ -19,6 +19,9 @@
 - name: Order Replay Snapshot Checkpoint Management
   href: order-replay-snapshot-checkpoint.md
 
+- name: Order Projection Eventual Consistency Monitor
+  href: order-projection-eventual-consistency-monitor.md
+
 - name: Auth & Logging with `ActionChain<HttpRequest>`
   href: auth-logging-chain.md
 

docs/generators/eventual-consistency-monitor.md

@@ -0,0 +1,28 @@
+# Eventual Consistency Monitor Generator
+
+The Eventual Consistency Monitor generator creates a strongly typed factory for `EventualConsistencyMonitor<TKey>` from a partial host type.
+
+```csharp
+using PatternKit.Generators.EventualConsistency;
+
+[GenerateEventualConsistencyMonitor(
+    typeof(string),
+    FactoryMethodName = "CreateMonitor",
+    MonitorName = "order-projection-consistency",
+    MaxAllowedLag = 1)]
+public static partial class GeneratedOrderProjectionConsistencyMonitor;
+```
+
+Generated output:
+
+```csharp
+EventualConsistencyMonitor<string> monitor =
+    GeneratedOrderProjectionConsistencyMonitor.CreateMonitor();
+```
+
+Use the fluent path when runtime configuration owns the lag threshold, comparer, or clock. Use the generated path when a module wants a compile-time construction surface with stable monitor naming and threshold settings.
+
+## Diagnostics
+
+- `PKECM001`: the eventual consistency monitor host type must be partial.
+- `PKECM002`: `FactoryMethodName` and `MonitorName` must be non-empty and `MaxAllowedLag` must be non-negative.

docs/generators/index.md

@@ -65,6 +65,7 @@ PatternKit includes a Roslyn incremental generator package (`PatternKit.Generato
 | [**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]` |
 | [**Snapshot / Checkpoint Management**](snapshot-checkpoint-management.md) | Replay checkpoint manager factories for resumable processors | `[GenerateSnapshotCheckpointManager]` |
+| [**Eventual Consistency Monitor**](eventual-consistency-monitor.md) | Watermark lag monitor factories for projection convergence | `[GenerateEventualConsistencyMonitor]` |
 | [**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

@@ -279,6 +279,9 @@
 - name: Snapshot / Checkpoint Management
   href: snapshot-checkpoint-management.md
 
+- name: Eventual Consistency Monitor
+  href: eventual-consistency-monitor.md
+
 - name: Strategy
   href: strategy.md
 

docs/guides/benchmark-results.md

@@ -23,6 +23,8 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 | Workflow Orchestration | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Snapshot / Checkpoint Management | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Snapshot / Checkpoint Management | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Eventual Consistency Monitor | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Eventual Consistency Monitor | 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. |
@@ -246,19 +248,19 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 
 ## Coverage Matrix Summary
 
-The coverage matrix currently publishes 113 catalog patterns and 452 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 114 catalog patterns and 456 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 | 25 | 100 |
+| Application Architecture | 26 | 104 |
 | 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 107 generator source route results.
+The generator matrix currently publishes 108 generator source route results.
 
 ## Hosting Integration Matrix Results
 
@@ -282,6 +284,7 @@ The generator matrix currently publishes 107 generator source route results.
 | Application Architecture | Manual Task Gate | Covered | Covered | Covered | Covered |
 | Application Architecture | Workflow Orchestration | Covered | Covered | Covered | Covered |
 | Application Architecture | Snapshot / Checkpoint Management | Covered | Covered | Covered | Covered |
+| Application Architecture | Eventual Consistency Monitor | 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 |
@@ -400,6 +403,7 @@ The generator matrix currently publishes 107 generator source route results.
 | ManualTaskGateGenerator | `src/PatternKit.Generators/ManualTaskGates/ManualTaskGateGenerator.cs` | Covered |
 | WorkflowOrchestrationGenerator | `src/PatternKit.Generators/WorkflowOrchestration/WorkflowOrchestrationGenerator.cs` | Covered |
 | SnapshotCheckpointManagerGenerator | `src/PatternKit.Generators/SnapshotCheckpoints/SnapshotCheckpointManagerGenerator.cs` | Covered |
+| EventualConsistencyMonitorGenerator | `src/PatternKit.Generators/EventualConsistency/EventualConsistencyMonitorGenerator.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

@@ -40,6 +40,8 @@ The following numbers were captured on Windows 11, Intel Core i9-14900K, .NET SD
 | Workflow Orchestration | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Snapshot / Checkpoint Management | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Snapshot / Checkpoint Management | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Eventual Consistency Monitor | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Eventual Consistency Monitor | 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. |

docs/guides/pattern-coverage.md

@@ -131,6 +131,7 @@ The source of truth is `PatternKitPatternCatalog` in `src/PatternKit.Examples/Pr
 | Application Architecture | Manual Task Gate | `ManualTaskGate<TKey>` | Manual Task Gate generator |
 | Application Architecture | Workflow Orchestration | `WorkflowOrchestrator<TContext>` | Workflow Orchestration generator |
 | Application Architecture | Snapshot / Checkpoint Management | `SnapshotCheckpointManager<TKey, TSnapshot>` | Snapshot / Checkpoint Management generator |
+| Application Architecture | Eventual Consistency Monitor | `EventualConsistencyMonitor<TKey>` | Eventual Consistency Monitor generator |
 | Application Architecture | Timeout Manager | `TimeoutManager<TKey>` | Timeout Manager generator |
 
 ## Research Baselines

docs/index.md

@@ -66,11 +66,11 @@ if (parser.Execute("123", out var value))
 
 ## 📚 Available Patterns
 
-PatternKit covers 113 production-readiness patterns with fluent APIs, source-generated routes where applicable, IoC integration examples, TinyBDD coverage, and BenchmarkDotNet coverage-matrix validation:
+PatternKit covers 114 production-readiness patterns with fluent APIs, source-generated routes where applicable, IoC integration examples, TinyBDD coverage, and BenchmarkDotNet coverage-matrix validation:
 
 | Category | Count | Patterns |
 | --- | ---: | --- |
-| Application Architecture | 25 | 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, Snapshot / Checkpoint Management, Specification, Table Data Gateway, Timeout Manager, Transaction Script, Unit of Work, Value Object, Workflow Orchestration |
+| Application Architecture | 26 | Activity Tracker, Aggregate Root, Anti-Corruption Layer, Audit Log, Bounded Context, Context Map, CQRS, Data Mapper, Domain Event, Domain Service, Event Sourcing, Eventual Consistency Monitor, Feature Toggle, Identity Map, Manual Task Gate, Materialized View, Repository, Service Layer, Snapshot / Checkpoint Management, 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 |