feat: add context map pattern slice

README.md

@@ -473,11 +473,11 @@ var cachedRemoteProxy = Proxy<int, string>.Create(id => remoteProxy.Execute(id))
 ---
 
 ## Patterns Table
-PatternKit currently tracks 105 production-readiness patterns. Each catalog pattern is represented in tests, documentation, real-world examples, IoC integration, and the BenchmarkDotNet coverage matrix.
+PatternKit currently tracks 106 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 | 20 | Activity Tracker, Aggregate Root, Anti-Corruption Layer, Audit Log, Bounded Context, CQRS, Data Mapper, Domain Event, Domain Service, Event Sourcing, Feature Toggle, Identity Map, Materialized View, Repository, Service Layer, Specification, Table Data Gateway, Transaction Script, Unit of Work, Value Object |
+| Application Architecture | 21 | 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, Materialized View, Repository, Service Layer, Specification, Table Data Gateway, 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 |
 | Creational | 5 | Abstract Factory, Builder, Factory Method, Prototype, Singleton |
@@ -563,6 +563,8 @@ BenchmarkDotNet guidance is documented in [docs/guides/benchmarks.md](docs/guide
 | Domain Event | Execution | 367.2 ns | 1.77 KB | 346.4 ns | 1.55 KB | Generated reduced execution time and allocation for the order-placed dispatch workflow. |
 | Bounded Context | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Bounded Context | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Context Map | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Context Map | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Domain Service | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Domain Service | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Event-Carried State Transfer | Construction | 7.552 ns | 48 B | 6.751 ns | 48 B | Same allocation; generated was slightly faster in this microbenchmark. |

benchmarks/PatternKit.Benchmarks/Application/ContextMapBenchmarks.cs

@@ -0,0 +1,33 @@
+using BenchmarkDotNet.Attributes;
+using PatternKit.Application.ContextMaps;
+using PatternKit.Examples.ContextMapDemo;
+
+namespace PatternKit.Benchmarks.Application;
+
+[BenchmarkCategory("ApplicationArchitecture", "ContextMap")]
+public class ContextMapBenchmarks
+{
+    private readonly ContextMapDescriptor _fluent = CommerceContextMapDemo.CreateFluentMap();
+
+    private readonly ContextMapDescriptor _generated = CommerceContextMapDemo.CreateGeneratedMap();
+
+    [Benchmark(Baseline = true, Description = "Fluent: create context map descriptor")]
+    [BenchmarkCategory("Fluent", "Construction")]
+    public ContextMapDescriptor Fluent_CreateMap()
+        => CommerceContextMapDemo.CreateFluentMap();
+
+    [Benchmark(Description = "Generated: create context map descriptor")]
+    [BenchmarkCategory("Generated", "Construction")]
+    public ContextMapDescriptor Generated_CreateMap()
+        => CommerceContextMapDemo.CreateGeneratedMap();
+
+    [Benchmark(Description = "Fluent: inspect context map relationships")]
+    [BenchmarkCategory("Fluent", "Execution")]
+    public int Fluent_InspectRelationships()
+        => _fluent.Relationships.Count(static relationship => relationship.Kind == ContextRelationshipKind.PublishedLanguage);
+
+    [Benchmark(Description = "Generated: inspect context map relationships")]
+    [BenchmarkCategory("Generated", "Execution")]
+    public int Generated_InspectRelationships()
+        => _generated.Relationships.Count(static relationship => relationship.Kind == ContextRelationshipKind.PublishedLanguage);
+}

docs/examples/commerce-context-map-pattern.md

@@ -0,0 +1,20 @@
+# Commerce Context Map Pattern
+
+The commerce context map example shows how Catalog, Fulfillment, and Billing integrate without hiding the ownership boundary.
+
+The example exposes:
+
+- a fluent `ContextMapDescriptor`
+- a generated descriptor from `GeneratedCommerceContextMap`
+- a catalog-to-fulfillment translator
+- `AddCommerceContextMapDemo()` for `IServiceCollection`
+
+```csharp
+var services = new ServiceCollection()
+    .AddCommerceContextMapDemo();
+
+using var provider = services.BuildServiceProvider();
+var summary = provider.GetRequiredService<CommerceContextMapReporter>().Summarize();
+```
+
+The generated map is useful for architecture tests, operational diagnostics, and documentation pipelines that need to inspect integration relationships.

docs/examples/toc.yml

@@ -306,3 +306,6 @@
 
 - name: Fulfillment Bounded Context Pattern
   href: fulfillment-bounded-context-pattern.md
+
+- name: Commerce Context Map Pattern
+  href: commerce-context-map-pattern.md

docs/generators/context-map.md

@@ -0,0 +1,17 @@
+# Context Map Generator
+
+`ContextMapDescriptorGenerator` emits a `ContextMapDescriptor` factory from relationship attributes on a partial class or struct.
+
+```csharp
+[GenerateContextMapDescriptor("Commerce", FactoryMethodName = "Build")]
+[ContextMapRelationship("Catalog", "Fulfillment", ContextMapRelationshipKind.PublishedLanguage, "ProductFeed")]
+public static partial class CommerceMap;
+```
+
+Diagnostics:
+
+| Id | Meaning |
+| --- | --- |
+| `PKCMAP001` | The host type must be partial. |
+| `PKCMAP002` | At least one relationship is required. |
+| `PKCMAP003` | Relationship registrations must be unique. |

docs/generators/toc.yml

@@ -252,6 +252,9 @@
 - name: Bounded Context
   href: bounded-context.md
 
+- name: Context Map
+  href: context-map.md
+
 - name: State Machine
   href: state-machine.md
 

docs/guides/benchmark-results.md

@@ -83,6 +83,8 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 | Domain Event | Execution | 367.2 ns | 1.77 KB | 346.4 ns | 1.55 KB | Generated reduced execution time and allocation for the order-placed dispatch workflow. |
 | Bounded Context | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Bounded Context | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Context Map | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Context Map | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Domain Service | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Domain Service | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Event-Carried State Transfer | Construction | 7.552 ns | 48 B | 6.751 ns | 48 B | Same allocation; generated was slightly faster in this microbenchmark. |
@@ -228,19 +230,19 @@ The latest measured timings below were captured on Windows 11, Intel Core i9-149
 
 ## Coverage Matrix Summary
 
-The coverage matrix currently publishes 105 catalog patterns and 420 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 106 catalog patterns and 424 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 | 20 | 80 |
+| Application Architecture | 21 | 84 |
 | Behavioral | 11 | 44 |
 | Cloud Architecture | 17 | 68 |
 | Creational | 5 | 20 |
 | Enterprise Integration | 41 | 164 |
 | Messaging Reliability | 3 | 12 |
 | Structural | 7 | 28 |
 
-The generator matrix currently publishes 100 generator source route results.
+The generator matrix currently publishes 101 generator source route results.
 
 ## Hosting Integration Matrix Results
 
@@ -265,6 +267,7 @@ The generator matrix currently publishes 100 generator source route results.
 | Application Architecture | Anti-Corruption Layer | Covered | Covered | Covered | Covered |
 | Application Architecture | Audit Log | Covered | Covered | Covered | Covered |
 | Application Architecture | Bounded Context | Covered | Covered | Covered | Covered |
+| Application Architecture | Context Map | Covered | Covered | Covered | Covered |
 | Application Architecture | CQRS | Covered | Covered | Covered | Covered |
 | Application Architecture | Data Mapper | Covered | Covered | Covered | Covered |
 | Application Architecture | Domain Event | Covered | Covered | Covered | Covered |
@@ -391,6 +394,7 @@ The generator matrix currently publishes 100 generator source route results.
 | DecoratorGenerator | `src/PatternKit.Generators/DecoratorGenerator.cs` | Covered |
 | DomainEventDispatcherGenerator | `src/PatternKit.Generators/DomainEvents/DomainEventDispatcherGenerator.cs` | Covered |
 | BoundedContextDescriptorGenerator | `src/PatternKit.Generators/BoundedContexts/BoundedContextDescriptorGenerator.cs` | Covered |
+| ContextMapDescriptorGenerator | `src/PatternKit.Generators/ContextMaps/ContextMapDescriptorGenerator.cs` | Covered |
 | DomainServiceRegistryGenerator | `src/PatternKit.Generators/DomainServices/DomainServiceRegistryGenerator.cs` | Covered |
 | EventCarriedStateTransferGenerator | `src/PatternKit.Generators/EventCarriedStateTransfer/EventCarriedStateTransferGenerator.cs` | Covered |
 | EventNotificationGenerator | `src/PatternKit.Generators/EventNotification/EventNotificationGenerator.cs` | Covered |

docs/guides/benchmarks.md

@@ -98,6 +98,8 @@ The following numbers were captured on Windows 11, Intel Core i9-14900K, .NET SD
 | Domain Event | Execution | 367.2 ns | 1.77 KB | 346.4 ns | 1.55 KB | Generated reduced execution time and allocation for the order-placed dispatch workflow. |
 | Bounded Context | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Bounded Context | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Context Map | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
+| Context Map | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Domain Service | Construction | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Domain Service | Execution | Pending | Pending | Pending | Pending | Covered by the BenchmarkDotNet matrix; publish measured values after the next benchmark refresh. |
 | Event-Carried State Transfer | Construction | 7.552 ns | 48 B | 6.751 ns | 48 B | Same allocation; generated was slightly faster in this microbenchmark. |

docs/guides/pattern-coverage.md

@@ -117,6 +117,7 @@ The source of truth is `PatternKitPatternCatalog` in `src/PatternKit.Examples/Pr
 | Application Architecture | Domain Event | `IDomainEvent` and `DomainEventDispatcher<TEventBase>` | Domain Event generator |
 | Application Architecture | Domain Service | `DomainServiceOperation<TRequest,TResponse>` and named registries | Domain Service generator |
 | Application Architecture | Bounded Context | `BoundedContextDescriptor` capabilities and adapters | Bounded Context generator |
+| Application Architecture | Context Map | `ContextMapDescriptor` relationships and contracts | Context Map generator |
 | Application Architecture | Table Data Gateway | `ITableDataGateway<TRow,TKey>` and `InMemoryTableDataGateway<TRow,TKey>` | Table Data Gateway generator |
 | Application Architecture | Event Sourcing | `IEventStore<TEvent,TStreamId>` and `InMemoryEventStore<TEvent,TStreamId>` | Event Sourcing generator |
 | Application Architecture | Feature Toggle | `IFeatureToggleSet<TContext>` and `FeatureToggleSet<TContext>` | Feature Toggle generator |

docs/index.md

@@ -66,11 +66,11 @@ if (parser.Execute("123", out var value))
 
 ## 📚 Available Patterns
 
-PatternKit covers 105 production-readiness patterns with fluent APIs, source-generated routes where applicable, IoC integration examples, TinyBDD coverage, and BenchmarkDotNet coverage-matrix validation:
+PatternKit covers 106 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 | 20 | Activity Tracker, Aggregate Root, Anti-Corruption Layer, Audit Log, Bounded Context, CQRS, Data Mapper, Domain Event, Domain Service, Event Sourcing, Feature Toggle, Identity Map, Materialized View, Repository, Service Layer, Specification, Table Data Gateway, Transaction Script, Unit of Work, Value Object |
+| Application Architecture | 21 | 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, Materialized View, Repository, Service Layer, Specification, Table Data Gateway, 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 |
 | Creational | 5 | Abstract Factory, Builder, Factory Method, Prototype, Singleton |

docs/patterns/application/context-map.md

@@ -0,0 +1,23 @@
+# Context Map
+
+Context Map documents how bounded contexts relate to each other. It captures upstream/downstream direction, the relationship style, and the contract used between contexts.
+
+Use the fluent path when the map is assembled from configuration or architecture metadata:
+
+```csharp
+var map = ContextMapDescriptor.Create("Commerce")
+    .AddRelationship("Catalog", "Fulfillment", ContextRelationshipKind.PublishedLanguage, "ProductFeed")
+    .AddRelationship("Fulfillment", "Billing", ContextRelationshipKind.CustomerSupplier, "ShipmentBilling")
+    .Build();
+```
+
+Use the generated path when the map is stable and should be reviewed in source:
+
+```csharp
+[GenerateContextMapDescriptor("Commerce")]
+[ContextMapRelationship("Catalog", "Fulfillment", ContextMapRelationshipKind.PublishedLanguage, "ProductFeed")]
+[ContextMapRelationship("Fulfillment", "Billing", ContextMapRelationshipKind.CustomerSupplier, "ShipmentBilling")]
+public static partial class CommerceMap;
+```
+
+Register the generated descriptor in DI so services, health checks, documentation tools, or architecture tests can inspect context relationships at runtime.

docs/patterns/toc.yml

@@ -435,6 +435,8 @@
           href: application/domain-service.md
         - name: Bounded Context
           href: application/bounded-context.md
+        - name: Context Map
+          href: application/context-map.md
         - name: Table Data Gateway
           href: application/table-data-gateway.md
         - name: Event Sourcing