@opengroundplan/core 0.1.1

package/templates/architectures/cqrs/files/tests/ArchitectureTests/CqrsBoundaryTests.cs

@@ -0,0 +1,104 @@
+using System.Reflection;
+using Xunit;
+
+namespace {{ solutionName | dot }}.ArchitectureTests;
+
+// The command/query split at assembly granularity — in .NET a side of the split is a project.
+public sealed class CqrsBoundaryTests
+{
+    private const string Domain = "Domain";
+    private const string Commands = "Commands";
+    private const string Queries = "Queries";
+
+    // Scopes the suffix match to this solution, so a NuGet package ending in ".Queries" is ignored.
+    private const string SolutionPrefix = "{{ solutionName | dot }}.";
+
+    [Fact]
+    public void Query_side_never_reaches_the_command_side()
+    {
+        // The one rule. A query handler that loads an aggregate has re-merged the two models.
+        var assembly = global::{{ solutionName | dot }}.{{ contextName | pascal }}.Queries.AssemblyMarker.Assembly;
+        AssertNoAssemblyReference(assembly, [Domain, Commands]);
+        AssertNoProjectReference(Queries, [Domain, Commands]);
+    }
+
+    [Fact]
+    public void Command_side_goes_through_the_domain_model()
+    {
+        // Without this the command path is just another CRUD path wearing the vocabulary.
+        var contents = File.ReadAllText(ProjectFile(Commands));
+        Assert.Contains($".{Domain}.csproj", contents, StringComparison.Ordinal);
+    }
+
+    [Fact]
+    public void Command_side_never_reads_from_a_projection()
+    {
+        // Read models are stale by construction; a decision made from one is made on stale data.
+        AssertNoAssemblyReference(global::{{ solutionName | dot }}.{{ contextName | pascal }}.Commands.AssemblyMarker.Assembly, [Queries]);
+        AssertNoProjectReference(Commands, [Queries]);
+    }
+
+    [Fact]
+    public void Write_model_depends_on_neither_side()
+    {
+        var assembly = global::{{ solutionName | dot }}.{{ contextName | pascal }}.Domain.AssemblyMarker.Assembly;
+        AssertNoAssemblyReference(assembly, [Commands, Queries]);
+        AssertNoProjectReference(Domain, [Commands, Queries]);
+    }
+
+    private static void AssertNoAssemblyReference(Assembly assembly, string[] forbiddenSides)
+    {
+        var violations = assembly
+            .GetReferencedAssemblies()
+            .Select(reference => reference.Name ?? string.Empty)
+            .Where(name => forbiddenSides.Any(side => IsSide(name, side)))
+            .ToArray();
+
+        Assert.True(
+            violations.Length == 0,
+            $"{assembly.GetName().Name} references: {string.Join(", ", violations)}");
+    }
+
+    // Assembly metadata lists only references the compiler saw used, so an unused-but-declared
+    // ProjectReference would slip past the check above. The csproj closes that gap.
+    private static void AssertNoProjectReference(string side, string[] forbiddenSides)
+    {
+        var file = ProjectFile(side);
+        var contents = File.ReadAllText(file);
+
+        var violations = forbiddenSides
+            .Where(other => contents.Contains($".{other}.csproj", StringComparison.Ordinal))
+            .ToArray();
+
+        Assert.True(
+            violations.Length == 0,
+            $"{Path.GetFileName(file)} declares a ProjectReference to: {string.Join(", ", violations)}");
+    }
+
+    private static bool IsSide(string assemblyName, string side) =>
+        assemblyName.StartsWith(SolutionPrefix, StringComparison.Ordinal)
+        && assemblyName.EndsWith($".{side}", StringComparison.Ordinal);
+
+    private static string ProjectFile(string side)
+    {
+        var source = Path.Combine(RepositoryRoot(), "src");
+        var matches = Directory.GetFiles(source, $"*.{side}.csproj", SearchOption.AllDirectories);
+
+        Assert.True(matches.Length == 1, $"expected one *.{side}.csproj under {source}, found {matches.Length}");
+        return matches[0];
+    }
+
+    // Walk up from the test binary to the directory holding src/, so no path is baked in.
+    private static string RepositoryRoot()
+    {
+        for (var directory = new DirectoryInfo(AppContext.BaseDirectory); directory is not null; directory = directory.Parent)
+        {
+            if (Directory.Exists(Path.Combine(directory.FullName, "src")))
+            {
+                return directory.FullName;
+            }
+        }
+
+        throw new DirectoryNotFoundException($"No ancestor of {AppContext.BaseDirectory} contains a src/ directory.");
+    }
+}

package/templates/architectures/event-driven/blueprint.yaml

@@ -0,0 +1,163 @@
+id: event-driven
+kind: architecture
+name: Event-Driven Architecture
+description: >-
+  Folder overlay for publish/subscribe: an event catalog of versioned schemas at the bottom of
+  the dependency graph, a broker port with a swappable adapter behind it, publishers and
+  handlers that know only those two, and a boundary check per stack that fails when one handler
+  imports another.
+
+tags:
+  - event-driven
+  - pub-sub
+  - events
+  - broker
+  - boundaries
+  - netarchtest
+  - import-linter
+
+requires: []
+conflicts: []
+provides:
+  - event-catalog
+  - broker-abstraction
+  - boundary-enforcement
+
+# An overlay is chosen through the architecture question, never listed as a supported target.
+supportsArchitectures: []
+
+variables:
+  # The catalog is organized by bounded context, so the seed event needs one to live in.
+  - name: eventDomain
+    prompt: Bounded context the first event belongs to (e.g. "orders")
+    type: string
+    default: orders
+    required: true
+
+  - name: firstEvent
+    prompt: First event in the catalog, named as a past-tense fact (e.g. "order-placed")
+    type: string
+    default: order-placed
+    required: true
+
+  - name: firstHandler
+    prompt: First subscriber of that event
+    type: string
+    default: send-confirmation
+    required: true
+
+  # Two subscribers, not one: fan-out with a single consumer is not fan-out, and an
+  # "independent handlers" check with one handler passes by comparing nothing.
+  - name: secondHandler
+    prompt: Second subscriber of the same event
+    type: string
+    default: update-inventory
+    required: true
+
+  # Package versions are template inputs, not literals in the generated csproj — bumping them
+  # must be one edit, not a sweep across every project.
+  - name: dotnetExtensionsVersion
+    prompt: Microsoft.Extensions.* package version
+    type: string
+    default: '10.0.10'
+    when: "stack == 'dotnet'"
+
+  - name: netArchTestVersion
+    prompt: NetArchTest.eNhancedEdition version (enforces the handler boundaries in tests)
+    type: string
+    default: '1.4.5'
+    when: "stack == 'dotnet'"
+
+files:
+  # ── dotnet ──────────────────────────────────────────────────────────────────
+  # Folder names are deliberately untokenized so postApply can name the projects — postApply
+  # strings are never rendered. The assemblies still carry the solution namespace via
+  # AssemblyName/RootNamespace inside each csproj.
+  - from: files/docs/architecture/event-driven.dotnet.md
+    to: .
+    when: "stack == 'dotnet'"
+  - from: files/src/EventCatalog/**
+    to: .
+    when: "stack == 'dotnet'"
+  - from: files/src/Messaging/**
+    to: .
+    when: "stack == 'dotnet'"
+  - from: files/src/EventPublishers/**
+    to: .
+    when: "stack == 'dotnet'"
+  - from: files/src/EventHandlers/**
+    to: .
+    when: "stack == 'dotnet'"
+  # Boundary rules that live only in prose get violated; this fails `dotnet test` instead.
+  - from: files/tests/EventArchitectureTests/**
+    to: .
+    when: "stack == 'dotnet'"
+
+  # ── typescript / node ───────────────────────────────────────────────────────
+  # One layout serves both: the catalog, broker and handler roots are the same whether the base
+  # is Next.js, Vite, Hono or Nest.
+  - from: files/docs/architecture/event-driven.node.md
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/events/**
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/broker/**
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/publishers/**
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/handlers/**
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/src/bootstrap/**
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+  - from: files/scripts/check-event-boundaries.mjs
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  - from: files/docs/architecture/event-driven.python.md
+    to: .
+    when: "stack == 'python'"
+  - from: files/src/__solutionName.snake__/**
+    to: .
+    when: "stack == 'python'"
+  - from: files/.importlinter
+    to: .
+    when: "stack == 'python'"
+  # import-linter needs each handler listed by hand; this one discovers them by walking the tree.
+  - from: files/tests/architecture/test_event_boundaries.py
+    to: .
+    when: "stack == 'python'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+  # Central package management: versions live in Directory.Packages.props and projects
+  # reference without one. A bare Version= on a PackageReference fails restore (NU1008).
+  - from: files/Directory.Packages.props
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply:
+  # New projects are invisible to `dotnet build` and `dotnet test` until the solution knows them,
+  # and an unbuilt fitness test enforces nothing.
+
+  # Contract file is useless without the linter that reads it.
+  - run: uv add --dev "import-linter==2.13"
+    when: "stack == 'python'"
+    optional: true
+
+  # Manifest-only, matching the other blueprints: no install runs here.
+  - run: npm pkg set "scripts.check:events"="node scripts/check-event-boundaries.mjs"
+    when: "stack == 'typescript' || stack == 'node'"
+    optional: true

package/templates/architectures/event-driven/files/.importlinter

@@ -0,0 +1,43 @@
+# import-linter contracts — the standard-tool half of the boundary enforcement.
+# `lint-imports` fails the build; wire it into CI next to pytest and ruff.
+# Handlers must be listed here as you add them; tests/architecture/test_event_boundaries.py
+# discovers them by walking the tree and needs no upkeep. Ship both.
+[importlinter]
+root_package = {{ solutionName | snake }}
+
+[importlinter:contract:catalog-is-the-bottom]
+name = The event catalog imports nothing above it
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.events
+forbidden_modules =
+    {{ solutionName | snake }}.broker
+    {{ solutionName | snake }}.handlers
+    {{ solutionName | snake }}.publishers
+
+# The one rule that matters most. Independence forbids imports in BOTH directions.
+[importlinter:contract:handlers-are-independent]
+name = Handlers do not import one another
+type = independence
+modules =
+    {{ solutionName | snake }}.handlers.{{ firstHandler | snake }}
+    {{ solutionName | snake }}.handlers.{{ secondHandler | snake }}
+
+[importlinter:contract:publishers-and-handlers-never-meet]
+name = Publishers and handlers do not import each other
+type = independence
+modules =
+    {{ solutionName | snake }}.handlers
+    {{ solutionName | snake }}.publishers
+
+[importlinter:contract:broker-adapters-are-private]
+name = Only the broker package names a concrete adapter
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.handlers
+    {{ solutionName | snake }}.publishers
+forbidden_modules =
+    {{ solutionName | snake }}.broker.adapters
+# Direct imports only. Every importer of `broker` reaches an adapter transitively through
+# create_broker() — that chain is the sanctioned path, and forbidding it would ban the port too.
+allow_indirect_imports = true

package/templates/architectures/event-driven/files/Directory.Packages.props

@@ -0,0 +1,11 @@
+<Project>
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="{{ dotnetExtensionsVersion }}" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="{{ dotnetExtensionsVersion }}" />
+    <PackageVersion Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="{{ dotnetExtensionsVersion }}" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.8.1" />
+    <PackageVersion Include="NetArchTest.eNhancedEdition" Version="{{ netArchTestVersion }}" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
+    <PackageVersion Include="xunit.v3" Version="3.2.2" />
+  </ItemGroup>
+</Project>

package/templates/architectures/event-driven/files/__solutionName.dot__.slnx

@@ -0,0 +1,11 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/EventCatalog/EventCatalog.csproj" />
+    <Project Path="src/EventHandlers/EventHandlers.csproj" />
+    <Project Path="src/EventPublishers/EventPublishers.csproj" />
+    <Project Path="src/Messaging/Messaging.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/EventArchitectureTests/EventArchitectureTests.csproj" />
+  </Folder>
+</Solution>

package/templates/architectures/event-driven/files/docs/architecture/event-driven.dotnet.md

@@ -0,0 +1,117 @@
+# Architecture — Event-Driven
+
+Producers emit events to a broker; consumers react independently, and no producer knows a
+consumer exists. What keeps that true is a **failing test**, not a wiki page.
+
+## The one rule that matters
+
+> **Handlers may not reference each other. Events cross boundaries, code does not.**
+>
+> `dotnet test` fails the moment one handler namespace depends on another — or on a publisher,
+> or on a concrete broker adapter instead of the port.
+
+The moment `{{ firstHandler | pascal }}Handler` reaches into `{{ secondHandler | pascal }}Handler` you have a distributed
+monolith: all the eventual consistency and none of the decoupling you paid for. If a handler
+needs something to happen after it runs, it **publishes an event**.
+
+## Layout
+
+```
+src/
+  EventCatalog/                  # the catalog — no ProjectReference at all, by design
+    EventEnvelope.cs             #   Id, Type, OccurredAt, CorrelationId, Payload
+    EventContract.cs             #   EventContract<T> — Name + Version + Parse
+    EventRegistry.cs             #   every published event, by wire type
+    {{ eventDomain | pascal }}/
+      {{ firstEvent | pascal }}V1.cs
+  Messaging/                     # the broker abstraction
+    IEventPublisher.cs           #   what a publisher sees
+    IEventSubscriber.cs          #   what a handler sees
+    BrokerOptions.cs             #   every tunable, one typed default, bound from configuration
+    MessagingRegistration.cs     #   AddEventBroker() — the ONLY place a concrete broker is named
+    Adapters/
+      InMemoryEventBroker.cs     #   default; not durable — swap before you depend on delivery
+  EventPublishers/
+    {{ eventDomain | pascal }}/{{ eventDomain | pascal }}Publisher.cs
+  EventHandlers/                 # one namespace per handler; siblings never reference one another
+    {{ firstHandler | pascal }}/
+    {{ secondHandler | pascal }}/
+tests/
+  EventArchitectureTests/        # the fitness functions
+```
+
+Assembly names carry the solution namespace (`{{ solutionName | dot }}.EventCatalog` and friends);
+the folders stay plain so they can be joined to the solution without guessing your project name.
+
+Two handlers ship on purpose. Fan-out with one subscriber is not fan-out, and a pairwise
+independence rule over one handler passes by comparing nothing.
+
+## Wiring it up
+
+The overlay does not touch your API project. Add this yourself, once:
+
+```bash
+dotnet add src/{{ solutionName | dot }}.Api reference src/Messaging src/EventHandlers src/EventPublishers
+```
+
+then in `Program.cs`:
+
+```csharp
+builder.Services.AddEventBroker(builder.Configuration);
+```
+
+and resolve each handler at startup to call `RegisterAsync(subscriber)` — subscribe before
+anything publishes, or the first fan-out has nobody listening. The architecture tests run
+regardless of whether the API references these projects, so the boundaries are guarded from the
+first commit.
+
+## Versioned events
+
+`{{ eventDomain | kebab }}.{{ firstEvent | kebab }}.v1` is the wire name, and it is append-only forever. A breaking change is
+`{{ firstEvent | pascal }}V2.cs` beside V1 with both in `EventRegistry`; v1 subscribers keep working until they
+migrate. Editing a shipped version is how you break a consumer you have never met.
+
+Handlers call `Parse()` at the edge because the wire is untyped however careful the publisher was.
+
+## Configuration
+
+Bound from the `EventBroker` configuration section into `BrokerOptions`, one typed default each —
+no call site names a host or a topic:
+
+| Setting | Default |
+|---|---|
+| `EventBroker:Driver` | `in-memory` |
+| `EventBroker:Url` | *(empty)* |
+| `EventBroker:TopicPrefix` | `{{ solutionName | kebab }}` |
+| `EventBroker:ConsumerGroup` | `{{ solutionName | kebab }}` |
+| `EventBroker:MaxDeliveryAttempts` | `5` |
+| `EventBroker:DeadLetterSuffix` | `.dlq` |
+
+## Enforcement
+
+`dotnet test` runs `tests/EventArchitectureTests` (NetArchTest):
+
+- `No_handler_depends_on_another_handler` — the headline rule, pairwise across every handler
+  namespace found by walking the assembly, so a new handler needs no upkeep here,
+- `At_least_two_handlers_are_discovered` — guards against the rule above passing vacuously,
+- `Handlers_do_not_depend_on_publishers` / `Publishers_do_not_depend_on_handlers`,
+- `The_event_catalog_is_the_bottom_of_the_graph`,
+- `Only_messaging_names_a_concrete_broker_adapter`.
+
+For a real broker, MassTransit, NServiceBus, Rebus, Wolverine and Azure Service Bus / Event Hubs
+all fit behind `IEventBroker` — add the adapter under `Messaging/Adapters/` and a branch in
+`MessagingRegistration.CreateBroker`. Nothing above the port changes.
+
+## What is NOT enforced mechanically
+
+- **Idempotent handlers.** At-least-once delivery means every handler runs twice eventually. No
+  fitness test can prove yours tolerates it; key the work on `(SubjectId, CorrelationId)`.
+- **Correlation IDs propagated.** The envelope carries one, but nothing forces a handler to pass
+  it into the events it emits. Without it you have no substitute for the call stack you gave up.
+- **Ordering and replay.** The in-memory adapter has neither. Late subscribers and reprocessing
+  after a bug fix need a durable log, not a pub/sub broker — decide before you build on it.
+
+Sources: [Azure — Event-Driven Architecture Style](https://learn.microsoft.com/en-us/azure/architecture/guide/architecture-styles/event-driven) ·
+[Azure — Publisher/Subscriber pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/publisher-subscriber) ·
+[Fowler — What do you mean by "Event-Driven"?](https://martinfowler.com/articles/201701-event-driven.html) ·
+Richards & Ford, *Fundamentals of Software Architecture* (broker vs mediator topology).

package/templates/architectures/event-driven/files/docs/architecture/event-driven.node.md

@@ -0,0 +1,98 @@
+# Architecture — Event-Driven
+
+Producers emit events to a broker; consumers react independently, and no producer knows a
+consumer exists. What keeps that true is a **build-failing script**, not a wiki page.
+
+## The one rule that matters
+
+> **Handlers may not import each other. Events cross boundaries, code does not.**
+>
+> `scripts/check-event-boundaries.mjs` fails the build the moment one handler imports another —
+> or imports a publisher, or reaches past the broker port into a concrete adapter.
+
+The moment handler A imports handler B you have a distributed monolith: all the eventual
+consistency and none of the decoupling you paid for. That is the failure mode this check exists
+to prevent. If handler A needs something to happen after it runs, it **publishes an event**.
+
+## Layout
+
+```
+src/
+  events/                      # the event catalog — bottom of the graph, imports nothing above it
+    envelope.ts                #   id, type, occurredAt, correlationId, payload
+    contract.ts                #   defineEvent() — name + version + parse
+    index.ts                   #   `catalog`: every published event, by wire type
+    {{ eventDomain | kebab }}/
+      {{ firstEvent | kebab }}/
+        v1.ts                  #   one file per version; v2.ts lands beside it, never replaces it
+  broker/                      # the broker abstraction
+    port.ts                    #   EventBroker: publish / subscribe / start / stop
+    config.ts                  #   every tunable, one typed default, read from env in one place
+    factory.ts                 #   the ONLY file that names a concrete adapter
+    adapters/
+      in-memory-broker.ts      #   default; not durable — swap before you depend on delivery
+  publishers/
+    {{ eventDomain | kebab }}.publisher.ts
+  handlers/                    # one folder per handler; siblings never import one another
+    {{ firstHandler | kebab }}/
+    {{ secondHandler | kebab }}/
+  bootstrap/
+    events.ts                  # composition root: the one file that knows every handler exists
+scripts/
+  check-event-boundaries.mjs   # the fitness test
+```
+
+Two handlers ship on purpose. Fan-out with one subscriber is not fan-out, and a "handlers are
+independent" check with one handler passes by comparing nothing.
+
+## Versioned events
+
+`{{ eventDomain | kebab }}.{{ firstEvent | kebab }}.v1` is the wire name, and it is append-only forever. A breaking change is
+`v2.ts` beside `v1.ts` with both registered in `catalog`; v1 subscribers keep working until they
+migrate, and you delete v1 when its topic goes quiet. Editing a shipped version instead is how
+you break a consumer you have never met.
+
+Consumers `parse()` at the edge because the wire is untyped however careful the publisher was.
+
+## Configuration
+
+Everything the broker needs comes from `loadBrokerConfig()` with one typed default each — no
+call site names a host or a topic:
+
+| Variable | Default |
+|---|---|
+| `EVENT_BROKER_DRIVER` | `in-memory` |
+| `EVENT_BROKER_URL` | *(empty)* |
+| `EVENT_BROKER_TOPIC_PREFIX` | `{{ solutionName | kebab }}` |
+| `EVENT_BROKER_CONSUMER_GROUP` | `{{ solutionName | kebab }}` |
+| `EVENT_BROKER_MAX_DELIVERY_ATTEMPTS` | `5` |
+| `EVENT_BROKER_DEAD_LETTER_SUFFIX` | `.dlq` |
+
+## Enforcement
+
+`node scripts/check-event-boundaries.mjs` — wire it into CI and `npm run check:events`:
+
+- no handler imports another handler,
+- no handler imports a publisher, and no publisher imports a handler,
+- the event catalog imports nothing above it,
+- nothing outside `src/broker/` names a concrete adapter.
+
+It reads import specifiers as written and never resolves them on disk, so it is immune to
+bundler and TypeScript resolution quirks. Run `--self-test` to prove the rules still fire, and
+note that it exits non-zero if it finds no handlers at all — a check that silently inspects
+nothing is worse than no check.
+
+## What is NOT enforced mechanically
+
+- **Idempotent handlers.** At-least-once delivery means every handler runs twice eventually. No
+  linter can prove yours tolerates it; key the work on `(subjectId, correlationId)` and test it.
+- **Correlation IDs propagated.** The envelope carries one, but nothing forces a handler to pass
+  it into the events it emits. Without it you have no substitute for the call stack you gave up.
+- **Ordering and replay.** The in-memory adapter has neither. If you need late subscribers or
+  reprocessing after a bug fix, you need a durable log (Kafka, Event Hubs, JetStream), not a
+  pub/sub broker — decide before you build on the default.
+
+Sources: [Azure — Event-Driven Architecture Style](https://learn.microsoft.com/en-us/azure/architecture/guide/architecture-styles/event-driven) ·
+[Azure — Publisher/Subscriber pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/publisher-subscriber) ·
+[Fowler — What do you mean by "Event-Driven"?](https://martinfowler.com/articles/201701-event-driven.html) ·
+Richards & Ford, *Fundamentals of Software Architecture* (broker vs mediator topology).

package/templates/architectures/event-driven/files/docs/architecture/event-driven.python.md

@@ -0,0 +1,100 @@
+# Architecture — Event-Driven
+
+Producers emit events to a broker; consumers react independently, and no producer knows a
+consumer exists. What keeps that true is a **build-failing check**, not a wiki page.
+
+## The one rule that matters
+
+> **Handlers may not import each other. Events cross boundaries, code does not.**
+>
+> `lint-imports` and `tests/architecture/test_event_boundaries.py` both fail the moment one
+> handler imports another — or imports a publisher, or reaches past the broker into `adapters`.
+
+The moment `handlers.{{ firstHandler | snake }}` imports `handlers.{{ secondHandler | snake }}` you have a distributed
+monolith: all the eventual consistency and none of the decoupling you paid for. If a handler
+needs something to happen after it runs, it **publishes an event**.
+
+## Layout
+
+```
+src/{{ solutionName | snake }}/
+  events/                        # the event catalog — bottom of the graph, imports nothing above it
+    envelope.py                  #   id, type, occurred_at, correlation_id, payload
+    contract.py                  #   EventContract — name + version + parse
+    __init__.py                  #   CATALOG: every published event, by wire type
+    {{ eventDomain | snake }}/
+      {{ firstEvent | snake }}/
+        v1.py                    #   one module per version; v2.py lands beside it
+  broker/                        # the broker abstraction
+    port.py                      #   EventBroker Protocol: publish / subscribe / start / stop
+    config.py                    #   every tunable, one typed default, read from env in one place
+    factory.py                   #   the ONLY module that names a concrete adapter
+    adapters/
+      in_memory.py               #   default; not durable — swap before you depend on delivery
+  publishers/
+    {{ eventDomain | snake }}.py
+  handlers/                      # one package per handler; siblings never import one another
+    {{ firstHandler | snake }}/
+    {{ secondHandler | snake }}/
+  eventing.py                    # composition root: the one module that knows every handler exists
+tests/architecture/
+  test_event_boundaries.py       # the fitness test
+.importlinter                    # the same rules, in the standard tool
+```
+
+Two handlers ship on purpose. Fan-out with one subscriber is not fan-out, and an independence
+check over one handler passes by comparing nothing.
+
+## Versioned events
+
+`{{ eventDomain | kebab }}.{{ firstEvent | kebab }}.v1` is the wire name, and it is append-only forever. A breaking change is
+`v2.py` beside `v1.py` with both in `CATALOG`; v1 subscribers keep working until they migrate.
+Editing a shipped version instead is how you break a consumer you have never met.
+
+Handlers call `.parse()` at the edge because the wire is untyped however careful the publisher was.
+
+## Configuration
+
+`load_broker_config()` is the only place these are read, each with one typed default:
+
+| Variable | Default |
+|---|---|
+| `EVENT_BROKER_DRIVER` | `in-memory` |
+| `EVENT_BROKER_URL` | *(empty)* |
+| `EVENT_BROKER_TOPIC_PREFIX` | `{{ solutionName | kebab }}` |
+| `EVENT_BROKER_CONSUMER_GROUP` | `{{ solutionName | kebab }}` |
+| `EVENT_BROKER_MAX_DELIVERY_ATTEMPTS` | `5` |
+| `EVENT_BROKER_DEAD_LETTER_SUFFIX` | `.dlq` |
+
+## Enforcement
+
+Two layers, both failing:
+
+- **`lint-imports`** reads `.importlinter`: catalog-is-the-bottom, handlers-are-independent,
+  publishers-and-handlers-never-meet, broker-adapters-are-private. Standard tooling, but each
+  new handler must be added to the `handlers-are-independent` contract by hand.
+- **`pytest tests/architecture/test_event_boundaries.py`** walks the AST and discovers handler
+  packages by tree, so adding a handler needs no upkeep. It also runs standalone
+  (`python tests/architecture/test_event_boundaries.py`) for repos without a test layer, and
+  carries a self-test proving the rules still fire.
+
+Ship both — the linter is what CI recognizes, the test is what stays correct as the tree grows.
+
+If you use Celery, be clear with yourself that it is a **task queue, not an event broker**;
+using it as one is the most common expensive mistake in this style on Python. For real brokers,
+`faststream` gives Kafka, RabbitMQ, NATS and Redis behind one API — write it as an adapter under
+`broker/adapters/` so nothing above the port changes.
+
+## What is NOT enforced mechanically
+
+- **Idempotent handlers.** At-least-once delivery means every handler runs twice eventually. No
+  linter can prove yours tolerates it; key the work on `(subject_id, correlation_id)` and test it.
+- **Correlation IDs propagated.** The envelope carries one, but nothing forces a handler to pass
+  it into the events it emits. Without it you have no substitute for the call stack you gave up.
+- **Ordering and replay.** The in-memory adapter has neither. Late subscribers and reprocessing
+  after a bug fix need a durable log, not a pub/sub broker — decide before you build on it.
+
+Sources: [Azure — Event-Driven Architecture Style](https://learn.microsoft.com/en-us/azure/architecture/guide/architecture-styles/event-driven) ·
+[Azure — Publisher/Subscriber pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/publisher-subscriber) ·
+[Fowler — What do you mean by "Event-Driven"?](https://martinfowler.com/articles/201701-event-driven.html) ·
+Richards & Ford, *Fundamentals of Software Architecture* (broker vs mediator topology).