feat(application): add activity tracker pattern

Adds the Activity Tracker pattern with fluent and source-generated factory paths, TinyBDD coverage, DI-ready dashboard examples, docs, catalog coverage, and measured benchmarks.

Author: JerrettDavis

README.md

@@ -450,7 +450,7 @@ PatternKit currently tracks 92 production-readiness patterns. Each catalog patte
 
 | Category | Count | Patterns |
 | --- | ---: | --- |
-| Application Architecture | 15 | Anti-Corruption Layer, Audit Log, CQRS, Data Mapper, Domain Event, Event Sourcing, Feature Toggle, Identity Map, Materialized View, Repository, Service Layer, Specification, Table Data Gateway, Transaction Script, Unit of Work |
+| Application Architecture | 16 | Activity Tracker, Anti-Corruption Layer, Audit Log, CQRS, Data Mapper, Domain Event, Event Sourcing, Feature Toggle, Identity Map, Materialized View, Repository, Service Layer, Specification, Table Data Gateway, Transaction Script, Unit of Work |
 | 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 |
@@ -468,6 +468,8 @@ BenchmarkDotNet guidance is documented in [docs/guides/benchmarks.md](docs/guide
 | Abstract Factory | Execution | 750.189 ns | 6,200 B | 735.733 ns | 6,200 B | Same allocation; generated was slightly faster for login widget creation. |
 | Adapter | Construction | 34.668 ns | 320 B | 3.607 ns | 24 B | Generated adapter construction was materially faster and allocated less. |
 | 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. |
 | Aggregator | Construction | 14.562 ns | 168 B | 15.235 ns | 168 B | Same allocation; fluent was slightly faster in this microbenchmark. |
 | Aggregator | Execution | 188.000 ns | 1,088 B | 200.564 ns | 1,088 B | Same allocation; fluent was faster for order line aggregation. |
 | Ambassador | Construction | 55.42 ns | 448 B | 48.03 ns | 360 B | Generated reduced construction time and allocation in this microbenchmark. |

benchmarks/PatternKit.Benchmarks/Application/ActivityTrackerBenchmarks.cs

@@ -0,0 +1,31 @@
+using BenchmarkDotNet.Attributes;
+using PatternKit.Application.ActivityTracking;
+using PatternKit.Examples.ActivityTrackingDemo;
+
+namespace PatternKit.Benchmarks.Application;
+
+[BenchmarkCategory("ApplicationArchitecture", "ActivityTracker")]
+public class ActivityTrackerBenchmarks
+{
+    private static readonly DashboardLoadRequest Request = new("REQ-100", ["orders", "inventory", "pricing"]);
+
+    [Benchmark(Baseline = true, Description = "Fluent: create activity tracker")]
+    [BenchmarkCategory("Fluent", "Construction")]
+    public ActivityTracker Fluent_CreateActivityTracker()
+        => DashboardActivityTrackers.CreateFluent();
+
+    [Benchmark(Description = "Generated: create activity tracker")]
+    [BenchmarkCategory("Generated", "Construction")]
+    public ActivityTracker Generated_CreateActivityTracker()
+        => GeneratedDashboardActivityTracker.CreateGenerated();
+
+    [Benchmark(Description = "Fluent: track dashboard loading")]
+    [BenchmarkCategory("Fluent", "Execution")]
+    public DashboardLoadSummary Fluent_TrackDashboardLoading()
+        => DashboardActivityTrackerDemoRunner.RunFluent(Request);
+
+    [Benchmark(Description = "Generated: track dashboard loading")]
+    [BenchmarkCategory("Generated", "Execution")]
+    public DashboardLoadSummary Generated_TrackDashboardLoading()
+        => DashboardActivityTrackerDemoRunner.RunGeneratedStatic(Request);
+}

docs/examples/dashboard-activity-tracker.md

@@ -0,0 +1,19 @@
+# Dashboard Activity Tracker Example
+
+The dashboard activity tracker example shows a loading-indicator gate composed through standard dependency injection:
+
+- fluent `DashboardActivityTrackers.CreateFluent()` construction;
+- source-generated `GeneratedDashboardActivityTracker.CreateGenerated()` construction;
+- `AddDashboardActivityTrackerDemo()` for `IServiceCollection` integration;
+- TinyBDD coverage for fluent behavior, generated parity, direct DI registration, and aggregate `AddPatternKitExamples()` import.
+
+```csharp
+var services = new ServiceCollection();
+services.AddDashboardActivityTrackerDemo();
+
+using var provider = services.BuildServiceProvider(validateScopes: true);
+var runner = provider.GetRequiredService<DashboardActivityTrackerDemoRunner>();
+var summary = runner.RunGenerated(new DashboardLoadRequest("REQ-100", ["orders", "inventory"]));
+```
+
+The summary reports whether the loading indicator should be visible, how many widget loads are active, and which widgets currently block dependent UI state.

docs/examples/toc.yml

@@ -4,6 +4,9 @@
 - name: Production-Ready Example Integrations
   href: production-ready-integrations.md
 
+- name: Dashboard Activity Tracker
+  href: dashboard-activity-tracker.md
+
 - name: Auth & Logging with `ActionChain<HttpRequest>`
   href: auth-logging-chain.md
 

docs/generators/activity-tracker.md

@@ -0,0 +1,22 @@
+# Activity Tracker Generator
+
+`[GenerateActivityTracker]` emits a named `ActivityTracker` factory for applications that want tracker gates declared at compile time.
+
+```csharp
+[GenerateActivityTracker(FactoryMethodName = "CreateGenerated", TrackerName = "dashboard-loading")]
+public static partial class GeneratedDashboardActivityTracker;
+```
+
+The generated factory returns the normal runtime tracker:
+
+```csharp
+var tracker = GeneratedDashboardActivityTracker.CreateGenerated();
+using var lease = tracker.Track("inventory", "REQ-100");
+```
+
+Diagnostics:
+
+| ID | Meaning |
+| --- | --- |
+| `PKAT001` | The host type must be partial. |
+| `PKAT002` | `FactoryMethodName` and `TrackerName` must be non-empty. |

docs/generators/index.md

@@ -61,6 +61,7 @@ PatternKit includes a Roslyn incremental generator package (`PatternKit.Generato
 | [**Specification**](specification.md) | Named business-rule registries | `[GenerateSpecificationRegistry]` |
 | [**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]` |
 | [**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/toc.yml

@@ -10,6 +10,9 @@
 - name: Anti-Corruption Layer
   href: anti-corruption-layer.md
 
+- name: Activity Tracker
+  href: activity-tracker.md
+
 - name: Audit Log
   href: audit-log.md
 

docs/guides/benchmark-results.md

@@ -15,6 +15,8 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 | Abstract Factory | Execution | 750.189 ns | 6,200 B | 735.733 ns | 6,200 B | Same allocation; generated was slightly faster for login widget creation. |
 | Adapter | Construction | 34.668 ns | 320 B | 3.607 ns | 24 B | Generated adapter construction was materially faster and allocated less. |
 | 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. |
 | Aggregator | Construction | 14.562 ns | 168 B | 15.235 ns | 168 B | Same allocation; fluent was slightly faster in this microbenchmark. |
 | Aggregator | Execution | 188.000 ns | 1,088 B | 200.564 ns | 1,088 B | Same allocation; fluent was faster for order line aggregation. |
 | Ambassador | Construction | 55.42 ns | 448 B | 48.03 ns | 360 B | Generated reduced construction time and allocation in this microbenchmark. |
@@ -204,25 +206,26 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 
 ## Coverage Matrix Summary
 
-The coverage matrix currently publishes 93 catalog patterns and 372 pattern route results. Each pattern has four BenchmarkDotNet routes: fluent construction, fluent execution, source-generated construction, and source-generated execution.
+The coverage matrix currently publishes 94 catalog patterns and 376 pattern route results. Each pattern has four BenchmarkDotNet routes: fluent construction, fluent execution, source-generated construction, and source-generated execution.
 
 | Category | Patterns | Published route results |
 | --- | ---: | ---: |
-| Application Architecture | 15 | 60 |
+| Application Architecture | 16 | 64 |
 | Behavioral | 11 | 44 |
 | Cloud Architecture | 17 | 68 |
 | Creational | 5 | 20 |
 | Enterprise Integration | 34 | 136 |
 | Messaging Reliability | 3 | 12 |
 | Structural | 7 | 28 |
 
-The generator matrix currently publishes 89 generator source route results.
+The generator matrix currently publishes 90 generator source route results.
 
 ## Pattern Matrix Results
 
-| Category | Pattern | Fluent construction | Fluent execution | Generated construction | Generated execution |
-| --- | --- | --- | --- | --- | --- |
-| Application Architecture | Anti-Corruption Layer | Covered | Covered | Covered | Covered |
+| Category | Pattern | Fluent construction | Fluent execution | Generated construction | Generated execution |
+| --- | --- | --- | --- | --- | --- |
+| Application Architecture | Activity Tracker | Covered | Covered | Covered | Covered |
+| Application Architecture | Anti-Corruption Layer | Covered | Covered | Covered | Covered |
 | Application Architecture | Audit Log | Covered | Covered | Covered | Covered |
 | Application Architecture | CQRS | Covered | Covered | Covered | Covered |
 | Application Architecture | Data Mapper | Covered | Covered | Covered | Covered |
@@ -318,9 +321,10 @@ The generator matrix currently publishes 89 generator source route results.
 
 ## Generator Matrix Results
 
-| Generator | Source | Matrix result |
-| --- | --- | --- |
-| AdapterGenerator | `src/PatternKit.Generators/Adapter/AdapterGenerator.cs` | Covered |
+| Generator | Source | Matrix result |
+| --- | --- | --- |
+| ActivityTrackerGenerator | `src/PatternKit.Generators/ActivityTracking/ActivityTrackerGenerator.cs` | Covered |
+| AdapterGenerator | `src/PatternKit.Generators/Adapter/AdapterGenerator.cs` | Covered |
 | AmbassadorGenerator | `src/PatternKit.Generators/Ambassador/AmbassadorGenerator.cs` | Covered |
 | AntiCorruptionLayerGenerator | `src/PatternKit.Generators/AntiCorruption/AntiCorruptionLayerGenerator.cs` | Covered |
 | AuditLogGenerator | `src/PatternKit.Generators/AuditLog/AuditLogGenerator.cs` | Covered |

docs/guides/pattern-coverage.md

@@ -113,6 +113,7 @@ The source of truth is `PatternKitPatternCatalog` in `src/PatternKit.Examples/Pr
 | Application Architecture | Audit Log | `IAuditLog<TEntry,TKey>` and `InMemoryAuditLog<TEntry,TKey>` | Audit Log generator |
 | 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 |
 
 ## Research Baselines
 

docs/patterns/application/activity-tracker.md

@@ -0,0 +1,25 @@
+# Activity Tracker
+
+`ActivityTracker` models tracker-based gating for active work. A caller acquires an `ActivityLease` when work begins, and releases it by disposing the lease or completing the activity id. Dependent state is based only on whether any activities exist.
+
+```csharp
+var tracker = ActivityTracker.Create("dashboard-loading").Build();
+
+using var loadOrders = tracker.Track("orders", correlationId: "REQ-100");
+
+if (tracker.IsBlocked)
+{
+    // Show the loading indicator or hold dependent work.
+}
+```
+
+Use it for loading wheels, import gates, page readiness, background refresh coordination, and other workflows where work can enter or leave independently and the block state is `ActiveCount > 0`.
+
+The source-generated path uses `[GenerateActivityTracker]` to produce a named tracker factory:
+
+```csharp
+[GenerateActivityTracker(FactoryMethodName = "CreateGenerated", TrackerName = "dashboard-loading")]
+public static partial class GeneratedDashboardActivityTracker;
+```
+
+`DashboardActivityTrackerDemo` shows a production-oriented `IServiceCollection` registration that drives dashboard loading visibility from tracked widget loads. Import it with `AddDashboardActivityTrackerDemo()` or the aggregate `AddPatternKitExamples()` registration.