feat: add snapshot checkpoint management pattern (#459)

Author: JerrettDavis

README.md

@@ -473,11 +473,11 @@ var cachedRemoteProxy = Proxy<int, string>.Create(id => remoteProxy.Execute(id))
 ---
 
 ## Patterns Table
-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.
+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.
 
 | Category | Count | Patterns |
 | --- | ---: | --- |
-| 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 |
+| 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 |
 | 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 |
@@ -501,6 +501,8 @@ BenchmarkDotNet guidance is documented in [docs/guides/benchmarks.md](docs/guide
 | 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. |
+| 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. |
 | 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/SnapshotCheckpointManagementBenchmarks.cs

@@ -0,0 +1,29 @@
+using BenchmarkDotNet.Attributes;
+using PatternKit.Application.SnapshotCheckpoints;
+using PatternKit.Examples.SnapshotCheckpointDemo;
+
+namespace PatternKit.Benchmarks.Application;
+
+[BenchmarkCategory("ApplicationArchitecture", "SnapshotCheckpointManagement")]
+public class SnapshotCheckpointManagementBenchmarks
+{
+    [Benchmark(Baseline = true, Description = "Fluent: create snapshot checkpoint manager")]
+    [BenchmarkCategory("Fluent", "Construction")]
+    public SnapshotCheckpointManager<string, OrderReplaySnapshot> Fluent_CreateSnapshotCheckpointManager()
+        => OrderReplaySnapshotCheckpointPolicies.CreateFluentManager();
+
+    [Benchmark(Description = "Generated: create snapshot checkpoint manager")]
+    [BenchmarkCategory("Generated", "Construction")]
+    public SnapshotCheckpointManager<string, OrderReplaySnapshot> Generated_CreateSnapshotCheckpointManager()
+        => GeneratedOrderReplayCheckpoints.CreateManager();
+
+    [Benchmark(Description = "Fluent: replay order with snapshot checkpoint")]
+    [BenchmarkCategory("Fluent", "Execution")]
+    public OrderReplaySummary Fluent_ReplayOrderWithSnapshotCheckpoint()
+        => OrderReplaySnapshotCheckpointDemo.RunFluentAsync().AsTask().GetAwaiter().GetResult();
+
+    [Benchmark(Description = "Generated: replay order with snapshot checkpoint")]
+    [BenchmarkCategory("Generated", "Execution")]
+    public OrderReplaySummary Generated_ReplayOrderWithSnapshotCheckpoint()
+        => OrderReplaySnapshotCheckpointDemo.RunGeneratedAsync().AsTask().GetAwaiter().GetResult();
+}

docs/examples/index.md

@@ -19,6 +19,7 @@ Welcome! This section collects small, focused demos that show **how to compose b
 * **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.
+* **Snapshot / checkpoint management** for resumable event stream replay and projection rebuilds.
 
 ## Demos in this section
 
@@ -43,6 +44,9 @@ Welcome! This section collects small, focused demos that show **how to compose b
 * **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).
 
+* **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).
+
 * **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-replay-snapshot-checkpoint.md

@@ -0,0 +1,23 @@
+# Order Replay Snapshot Checkpoint Management
+
+This example models an event-sourced order replay service that stores compact checkpoints after rebuilding order state. A replay can resume from a usable checkpoint and only apply later events.
+
+The fluent path builds the checkpoint manager directly:
+
+```csharp
+var manager = OrderReplaySnapshotCheckpointPolicies.CreateFluentManager();
+```
+
+The generated path uses a source-generated factory:
+
+```csharp
+var manager = GeneratedOrderReplayCheckpoints.CreateManager();
+```
+
+The example is importable through standard dependency injection:
+
+```csharp
+services.AddOrderReplaySnapshotCheckpointDemo();
+```
+
+`OrderReplayService` composes an `IEventStore<OrderReplayEvent, string>` with `SnapshotCheckpointManager<string, OrderReplaySnapshot>`. Production applications can replace the in-memory event store with their own storage while keeping the checkpoint manager construction, stale checkpoint handling, and replay tests intact.

docs/examples/toc.yml

@@ -16,6 +16,9 @@
 - name: Fulfillment Workflow Orchestration
   href: fulfillment-workflow-orchestration.md
 
+- name: Order Replay Snapshot Checkpoint Management
+  href: order-replay-snapshot-checkpoint.md
+
 - name: Auth & Logging with `ActionChain<HttpRequest>`
   href: auth-logging-chain.md
 

docs/generators/index.md

@@ -64,6 +64,7 @@ PatternKit includes a Roslyn incremental generator package (`PatternKit.Generato
 | [**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]` |
+| [**Snapshot / Checkpoint Management**](snapshot-checkpoint-management.md) | Replay checkpoint manager factories for resumable processors | `[GenerateSnapshotCheckpointManager]` |
 | [**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/snapshot-checkpoint-management.md

@@ -0,0 +1,28 @@
+# Snapshot / Checkpoint Management Generator
+
+The Snapshot / Checkpoint Management generator creates a strongly typed factory for a `SnapshotCheckpointManager<TKey, TSnapshot>` from a partial host type.
+
+```csharp
+using PatternKit.Generators.SnapshotCheckpoints;
+
+[GenerateSnapshotCheckpointManager(
+    typeof(string),
+    typeof(OrderReplaySnapshot),
+    FactoryMethodName = "CreateManager",
+    ManagerName = "order-replay-checkpoints")]
+public static partial class GeneratedOrderReplayCheckpoints;
+```
+
+Generated output:
+
+```csharp
+SnapshotCheckpointManager<string, OrderReplaySnapshot> manager =
+    GeneratedOrderReplayCheckpoints.CreateManager();
+```
+
+Use the fluent manager when runtime configuration needs a custom comparer, clock, or stale write policy. Use the generated factory when a module wants a discoverable, allocation-light construction path with the manager name and types fixed at compile time.
+
+## Diagnostics
+
+- `PKSCP001`: the snapshot checkpoint manager host type must be partial.
+- `PKSCP002`: `FactoryMethodName` and `ManagerName` must be non-empty.

docs/generators/toc.yml

@@ -276,6 +276,9 @@
 - name: Timeout Manager
   href: timeout-manager.md
 
+- name: Snapshot / Checkpoint Management
+  href: snapshot-checkpoint-management.md
+
 - name: Strategy
   href: strategy.md
 

docs/guides/benchmark-results.md

@@ -21,6 +21,8 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 | 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. |
+| 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. |
 | 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. |
@@ -244,19 +246,19 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 
 ## Coverage Matrix Summary
 
-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.
+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.
 
 | Category | Patterns | Published route results |
 | --- | ---: | ---: |
-| Application Architecture | 24 | 96 |
+| Application Architecture | 25 | 100 |
 | 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 106 generator source route results.
+The generator matrix currently publishes 107 generator source route results.
 
 ## Hosting Integration Matrix Results
 
@@ -279,6 +281,7 @@ The generator matrix currently publishes 106 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 | Snapshot / Checkpoint Management | 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 |
@@ -396,6 +399,7 @@ The generator matrix currently publishes 106 generator source route results.
 | TimeoutManagerGenerator | `src/PatternKit.Generators/Timeouts/TimeoutManagerGenerator.cs` | Covered |
 | ManualTaskGateGenerator | `src/PatternKit.Generators/ManualTaskGates/ManualTaskGateGenerator.cs` | Covered |
 | WorkflowOrchestrationGenerator | `src/PatternKit.Generators/WorkflowOrchestration/WorkflowOrchestrationGenerator.cs` | Covered |
+| SnapshotCheckpointManagerGenerator | `src/PatternKit.Generators/SnapshotCheckpoints/SnapshotCheckpointManagerGenerator.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

@@ -38,6 +38,8 @@ The following numbers were captured on Windows 11, Intel Core i9-14900K, .NET SD
 | 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. |
+| 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. |
 | 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. |