@opengroundplan/core 0.1.1

package/templates/architectures/modular-monolith/blueprint.yaml

@@ -0,0 +1,111 @@
+id: modular-monolith
+kind: architecture
+name: Modular Monolith
+description: >
+  One deployable unit partitioned into modules that map to bounded contexts, each exposing a
+  public Api surface over private internals, communicating through an in-process event bus.
+
+tags: [architecture, modules, bounded-context]
+
+requires: []
+conflicts: []
+provides: [module-boundaries, in-process-events]
+supportsArchitectures: []
+
+variables:
+  # Seeds the first module. Modules are the unit of work here, so the layout is meaningless
+  # without at least one to show the shape.
+  - name: moduleName
+    prompt: Name of the first module (a bounded context, e.g. "ordering")
+    type: string
+    default: ordering
+    required: true
+
+  # Package versions are template inputs, not literals in the generated csproj — bumping
+  # them must be one edit, not a sweep across every module project.
+  - name: dotnetExtensionsVersion
+    prompt: Microsoft.Extensions.* package version
+    type: string
+    default: '10.0.8'
+    when: "stack == 'dotnet'"
+
+  - name: netArchTestVersion
+    prompt: NetArchTest.eNhancedEdition version (enforces module boundaries in tests)
+    type: string
+    default: '1.4.5'
+    when: "stack == 'dotnet'"
+
+  # Go import paths are absolute, so the module path must be known at generation time.
+  - name: moduleHost
+    prompt: Go module path (e.g. github.com/acme/billing)
+    type: string
+    default: example.com/app
+    when: "stack == 'go'"
+
+files:
+  - from: files/docs/architecture/modular-monolith.dotnet.md
+    to: .
+    when: "stack == 'dotnet'"
+  - from: files/docs/architecture/modular-monolith.node.md
+    to: .
+    when: "stack == 'node' || stack == 'typescript'"
+  - from: files/docs/architecture/modular-monolith.python.md
+    to: .
+    when: "stack == 'python'"
+  - from: files/docs/architecture/modular-monolith.go.md
+    to: .
+    when: "stack == 'go'"
+
+  - from: files/src/__solutionName.dot__.Modules.__moduleName.pascal__/**
+    to: .
+    when: "stack == 'dotnet'"
+  - from: files/src/__solutionName.dot__.SharedKernel/**
+    to: .
+    when: "stack == 'dotnet'"
+  # Boundary rules that live only in prose get violated; this fails the build instead.
+  - from: files/tests/__solutionName.dot__.ArchitectureTests/**
+    to: .
+    when: "stack == 'dotnet'"
+
+  # Lowercase, matching the Node bases. A single shared casing across the .NET and
+  # TS trees collides on a case-insensitive filesystem (TS1261).
+  - from: files/src/modules/__moduleName.kebab__/**
+    to: .
+    when: "stack == 'node' || stack == 'typescript'"
+  - from: files/src/shared/events/**
+    to: .
+    when: "stack == 'node' || stack == 'typescript'"
+  - from: files/scripts/check-module-boundaries.mjs
+    to: .
+    when: "stack == 'node' || stack == 'typescript'"
+
+  - from: files/src/__solutionName.snake__/**
+    to: .
+    when: "stack == 'python'"
+  - from: files/tests/architecture/test_module_boundaries.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/.importlinter
+    to: .
+    when: "stack == 'python'"
+
+  - from: files/internal/**
+    to: .
+    when: "stack == 'go'"
+
+  # 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'"
+
+  # 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'"
+
+postApply: []

package/templates/architectures/modular-monolith/files/.importlinter

@@ -0,0 +1,22 @@
+# 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.
+# The full "reach a module only through its api" rule is enforced by
+# tests/architecture/test_module_boundaries.py, which needs no per-module upkeep.
+[importlinter]
+root_package = {{ solutionName | snake }}
+
+[importlinter:contract:shared-below-modules]
+name = Shared kernel must not depend on any module
+type = forbidden
+source_modules =
+    {{ solutionName | snake }}.shared
+forbidden_modules =
+    {{ solutionName | snake }}.modules
+
+# As you add modules, list them here so import-linter proves they never couple to each other.
+# Independence forbids imports in BOTH directions between every pair named.
+[importlinter:contract:modules-are-independent]
+name = Modules do not import one another
+type = independence
+modules =
+    {{ solutionName | snake }}.modules.{{ moduleName | snake }}

package/templates/architectures/modular-monolith/files/Directory.Packages.props

@@ -0,0 +1,9 @@
+<Project>
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" 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/modular-monolith/files/__solutionName.dot__.slnx

@@ -0,0 +1,9 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/{{ solutionName | dot }}.Modules.{{ moduleName | pascal }}/{{ solutionName | dot }}.Modules.{{ moduleName | pascal }}.csproj" />
+    <Project Path="src/{{ solutionName | dot }}.SharedKernel/{{ solutionName | dot }}.SharedKernel.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/{{ solutionName | dot }}.ArchitectureTests/{{ solutionName | dot }}.ArchitectureTests.csproj" />
+  </Folder>
+</Solution>

package/templates/architectures/modular-monolith/files/docs/architecture/modular-monolith.dotnet.md

@@ -0,0 +1,54 @@
+# Architecture — Modular Monolith
+
+One deployable process, partitioned into business-capability modules whose boundaries the
+**compiler and a build-failing test** enforce, not a wiki page.
+
+## The one rule that matters
+
+> A module is reachable only through its `Api` namespace. Every other type in the module is
+> `internal`, so another module physically cannot reference it — the C# compiler stops it, and
+> `ModuleBoundaryTests` fails the build if a type is wrongly made public.
+
+Get this rule wrong and a modular monolith rots into a big ball of mud on the first deadline.
+That is the failure mode the enforcement exists to prevent.
+
+## Layout
+
+```
+src/
+  {{ solutionName | dot }}.SharedKernel/          # types every module may use; depends on no module
+    Events/                                        # in-process event bus (IEventBus)
+  Modules/
+    {{ solutionName | dot }}.Modules.{{ moduleName | pascal }}/
+      Api/                                          # the module's ONLY public surface
+        I{{ moduleName | pascal }}Module.cs         #   interface + DTOs
+        {{ moduleName | pascal }}Events.cs          #   integration events it publishes
+        {{ moduleName | pascal }}ModuleRegistration.cs
+      Internal/                                     # everything else — all `internal`
+        {{ moduleName | pascal }}Service.cs
+tests/
+  {{ solutionName | dot }}.ArchitectureTests/       # fitness functions — run by `dotnet test`
+    ModuleBoundaryTests.cs
+```
+
+Add a module by copying the `Modules/*` project, then reference it from the architecture-test
+project so its assembly is inspected — an unreferenced module is a module nobody is checking.
+
+## How modules talk
+
+- **Ask for data:** depend on another module's `Api` interface. Synchronous, in-process, cheap.
+- **Announce a fact:** publish an `IIntegrationEvent` on `IEventBus`. Consumers subscribe without
+  the publisher knowing they exist. This is the seam you cut along the day a module becomes a
+  service — the publisher's code does not change, only the bus implementation behind it.
+
+## Enforcement
+
+`dotnet test` runs `ModuleBoundaryTests` ([NetArchTest](https://github.com/BenMorris/NetArchTest)):
+
+- internal namespaces contain no public types,
+- no module depends on another module's `.Internal` namespace,
+- the shared kernel depends on no module.
+
+Sources: Richards & Ford, *Fundamentals of Software Architecture* (modular monolith) ·
+[Fowler, MonolithFirst](https://martinfowler.com/bliki/MonolithFirst.html) ·
+[ThoughtWorks — the modular monolith](https://www.thoughtworks.com/insights/blog/microservices/modular-monolith-better-way-build-software).

package/templates/architectures/modular-monolith/files/docs/architecture/modular-monolith.go.md

@@ -0,0 +1,50 @@
+# Architecture — Modular Monolith
+
+One deployable binary, partitioned into business-capability modules whose boundaries the **Go
+compiler itself** enforces, not a wiki page.
+
+## The one rule that matters
+
+> A module is reachable only through its top-level package. Its implementation lives under
+> `internal/`, and Go's own internal-package rule makes it a **compile error** for any other
+> module to import it — `go build ./...` fails, full stop.
+
+Get this rule wrong and a modular monolith rots into a big ball of mud on the first deadline.
+That is the failure mode the enforcement exists to prevent.
+
+## Layout
+
+```
+internal/
+  shared/
+    events/                     # in-process event bus (events.Bus); imports no module
+  modules/
+    {{ moduleName | lower }}/                   # package {{ moduleName | lower }} — the public surface
+      {{ moduleName | lower }}.go               #   interface, DTOs, events, New()
+      internal/                 # compiler-private to this module
+        store/store.go
+  architecture/
+    boundary_test.go            # reports the boundary in CI terms + guards the shared kernel
+```
+
+`internal/modules/{{ moduleName | lower }}/internal/...` can be imported only by packages under
+`internal/modules/{{ moduleName | lower }}/`. That is a language guarantee, not a convention.
+
+## How modules talk
+
+- **Ask for data:** import another module's package (e.g. `{{ moduleName | lower }}.Module`) and
+  call it. Synchronous, in-process, cheap.
+- **Announce a fact:** `bus.Publish(ctx, event)`. Consumers `Subscribe` without the publisher
+  knowing they exist. This is the seam you cut along the day a module becomes a service.
+
+## Enforcement
+
+- **`go build ./...`** — a cross-module private import does not compile. This is the primary,
+  unbypassable gate.
+- **`go test ./internal/architecture/`** — `boundary_test.go` walks every import and additionally
+  forbids the shared kernel from depending on a module, giving CI a named failure. It reads the
+  module path from `go.mod`, so nothing is hardcoded.
+
+Sources: Richards & Ford, *Fundamentals of Software Architecture* (modular monolith) ·
+[Fowler, MonolithFirst](https://martinfowler.com/bliki/MonolithFirst.html) ·
+[Go internal packages](https://go.dev/doc/go1.4#internalpackages).

package/templates/architectures/modular-monolith/files/docs/architecture/modular-monolith.node.md

@@ -0,0 +1,56 @@
+# Architecture — Modular Monolith
+
+One deployable process, partitioned into business-capability modules whose boundaries a
+**build-failing script** enforces, not a wiki page.
+
+## The one rule that matters
+
+> A module is reachable only through its `api/` folder. Anything under `internal/` is private,
+> and `scripts/check-module-boundaries.mjs` fails the build the moment another module — or the
+> shared kernel — imports past `api/`.
+
+Get this rule wrong and a modular monolith rots into a big ball of mud on the first deadline.
+That is the failure mode the enforcement exists to prevent.
+
+## Layout
+
+```
+src/
+  shared/
+    events/            # in-process event bus (InProcessEventBus); depends on no module
+  modules/
+    {{ moduleName | kebab }}/
+      api/             # the module's ONLY public surface
+        index.ts       #   re-exports the contract + a factory
+        contracts.ts   #   interface, DTOs, integration events
+      internal/        # everything else — never imported from outside
+        {{ moduleName | kebab }}.service.ts
+scripts/
+  check-module-boundaries.mjs   # the fitness test
+```
+
+Add a module by copying `modules/{{ moduleName | kebab }}/`; the checker discovers any folder
+that has an `api/` directory, so there is nothing to register.
+
+## How modules talk
+
+- **Ask for data:** import another module's `api/` and call its interface. Synchronous,
+  in-process, cheap.
+- **Announce a fact:** `publish()` an integration event on the bus. Consumers `subscribe()`
+  without the publisher knowing they exist. This is the seam you cut along the day a module
+  becomes a service — the publisher does not change, only the bus behind it.
+
+## Enforcement
+
+`node scripts/check-module-boundaries.mjs` (wire it into CI and `npm run arch`):
+
+- no import crosses into another module's `internal/`,
+- no bare specifier reaches a package's `internal/` subpath,
+- shared code never imports a module.
+
+It reads import specifiers as written and never resolves them on disk, so it is immune to
+bundler/TS resolution quirks. Run `--self-test` to prove the rule still fires.
+
+Sources: Richards & Ford, *Fundamentals of Software Architecture* (modular monolith) ·
+[Fowler, MonolithFirst](https://martinfowler.com/bliki/MonolithFirst.html) ·
+[ThoughtWorks — the modular monolith](https://www.thoughtworks.com/insights/blog/microservices/modular-monolith-better-way-build-software).

package/templates/architectures/modular-monolith/files/docs/architecture/modular-monolith.python.md

@@ -0,0 +1,54 @@
+# Architecture — Modular Monolith
+
+One deployable process, partitioned into business-capability modules whose boundaries a
+**build-failing test** enforces, not a wiki page.
+
+## The one rule that matters
+
+> A module is reachable only through its `api` sub-package. Anything under `internal` is
+> private, and `tests/architecture/test_module_boundaries.py` fails the build the moment
+> another module — or the shared kernel — imports past `api`.
+
+Get this rule wrong and a modular monolith rots into a big ball of mud on the first deadline.
+That is the failure mode the enforcement exists to prevent.
+
+## Layout
+
+```
+src/{{ solutionName | snake }}/
+  shared/
+    events/          # in-process event bus (InProcessEventBus); depends on no module
+  modules/
+    {{ moduleName | snake }}/
+      api/           # the module's ONLY public surface
+        __init__.py  #   re-exports the contract + a factory
+        contracts.py #   Protocol, DTOs, integration events
+        factory.py
+      internal/      # everything else — never imported from outside
+        service.py
+tests/architecture/
+  test_module_boundaries.py     # the fitness test
+```
+
+Add a module by copying `modules/{{ moduleName | snake }}/`; the AST test discovers modules by
+walking the tree, so there is nothing to register.
+
+## How modules talk
+
+- **Ask for data:** import another module's `api` package and call its `Protocol`. Synchronous,
+  in-process, cheap.
+- **Announce a fact:** `await bus.publish(event)`. Consumers `subscribe()` without the publisher
+  knowing they exist. This is the seam you cut along the day a module becomes a service.
+
+## Enforcement — two layers, both fail the build
+
+1. `tests/architecture/test_module_boundaries.py` (pytest, standard-library only) parses every
+   import and enforces the full "reach a module only through `api`" rule. It needs no
+   per-module upkeep and runs standalone: `python tests/architecture/test_module_boundaries.py`.
+2. `.importlinter` contracts (`lint-imports`) are the standard-tool guard: the shared kernel may
+   not import a module, and named modules stay independent. List each new module in the
+   `independence` contract.
+
+Sources: Richards & Ford, *Fundamentals of Software Architecture* (modular monolith) ·
+[Fowler, MonolithFirst](https://martinfowler.com/bliki/MonolithFirst.html) ·
+[import-linter](https://import-linter.readthedocs.io/).

package/templates/architectures/modular-monolith/files/internal/architecture/boundary_test.go

@@ -0,0 +1,151 @@
+// Package architecture holds the modular-monolith fitness test. Go's own internal/ rule already
+// fails the build on a cross-module private import; this test reports the same boundary in CI
+// terms and additionally forbids the shared kernel from depending on a module.
+package architecture
+
+import (
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// Path segments that name the two boundaries. Overridable, but the defaults match the layout.
+var (
+	modulesSegment = envOr("ARCH_MODULES_SEGMENT", "internal/modules")
+	sharedSegment  = envOr("ARCH_SHARED_SEGMENT", "internal/shared")
+	privateSegment = "internal" // the per-module private dir; Go enforces this one itself
+)
+
+func envOr(key, fallback string) string {
+	if value := os.Getenv(key); value != "" {
+		return value
+	}
+	return fallback
+}
+
+// moduleOf returns the module name owning an import path, or "" when the path is not in a module.
+func moduleOf(importPath string) string {
+	marker := "/" + modulesSegment + "/"
+	index := strings.Index(importPath, marker)
+	if index < 0 {
+		return ""
+	}
+	rest := importPath[index+len(marker):]
+	return strings.SplitN(rest, "/", 2)[0]
+}
+
+// reachesPrivate reports whether importPath points inside some module's private subtree.
+func reachesPrivate(importPath string) bool {
+	marker := "/" + modulesSegment + "/"
+	index := strings.Index(importPath, marker)
+	if index < 0 {
+		return false
+	}
+	rest := importPath[index+len(marker):]
+	segments := strings.Split(rest, "/")
+	for _, segment := range segments[1:] {
+		if segment == privateSegment {
+			return true
+		}
+	}
+	return false
+}
+
+func inShared(importPath string) bool {
+	return strings.Contains(importPath, "/"+sharedSegment+"/") || strings.HasSuffix(importPath, "/"+sharedSegment)
+}
+
+// violation is the single rule, isolated so the self-test proves it still fires.
+func violation(fromPkg, imported string) string {
+	if inShared(fromPkg) && moduleOf(imported) != "" {
+		return "shared kernel must not depend on a module: imports " + imported
+	}
+	target := moduleOf(imported)
+	if target == "" || target == moduleOf(fromPkg) {
+		return ""
+	}
+	if reachesPrivate(imported) {
+		return "reaches into another module's internals: " + imported + " (go through the module's public package)"
+	}
+	return ""
+}
+
+func TestBoundaryRuleStillDetectsAViolation(t *testing.T) {
+	cases := []struct {
+		from, imported string
+		want           bool
+	}{
+		{"x/internal/modules/orders/internal/svc", "x/internal/modules/catalog/internal/store", true},
+		{"x/internal/modules/orders", "x/internal/modules/catalog", false},
+		{"x/internal/modules/catalog", "x/internal/modules/catalog/internal/store", false},
+		{"x/internal/shared/events", "x/internal/modules/catalog", true},
+		{"x/cmd/app", "x/internal/modules/catalog", false},
+	}
+	for _, c := range cases {
+		if (violation(c.from, c.imported) != "") != c.want {
+			t.Fatalf("violation(%q, %q): want fail=%v", c.from, c.imported, c.want)
+		}
+	}
+}
+
+func TestNoModuleReachesAnotherModulesInternals(t *testing.T) {
+	root, modulePath := repoRoot(t)
+	fset := token.NewFileSet()
+
+	var failures []string
+	err := filepath.WalkDir(root, func(path string, entry os.DirEntry, err error) error {
+		if err != nil || entry.IsDir() || !strings.HasSuffix(path, ".go") {
+			return err
+		}
+		rel, _ := filepath.Rel(root, filepath.Dir(path))
+		fromPkg := modulePath + "/" + filepath.ToSlash(rel)
+
+		file, err := parser.ParseFile(fset, path, nil, parser.ImportsOnly)
+		if err != nil {
+			return err
+		}
+		for _, spec := range file.Imports {
+			imported := strings.Trim(spec.Path.Value, `"`)
+			if message := violation(fromPkg, imported); message != "" {
+				failures = append(failures, fromPkg+": "+message)
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(failures) > 0 {
+		t.Fatalf("module boundary violations:\n%s", strings.Join(failures, "\n"))
+	}
+}
+
+var moduleLine = regexp.MustCompile(`(?m)^module\s+(\S+)`)
+
+// repoRoot walks up from the test's working directory to the go.mod, and returns its module path.
+func repoRoot(t *testing.T) (string, string) {
+	t.Helper()
+	dir, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	for {
+		candidate := filepath.Join(dir, "go.mod")
+		if content, err := os.ReadFile(candidate); err == nil {
+			match := moduleLine.FindSubmatch(content)
+			if match == nil {
+				t.Fatalf("no module line in %s", candidate)
+			}
+			return dir, string(match[1])
+		}
+		parent := filepath.Dir(dir)
+		if parent == dir {
+			t.Fatal("go.mod not found above the test directory")
+		}
+		dir = parent
+	}
+}

package/templates/architectures/modular-monolith/files/internal/modules/__moduleName.lower__/__moduleName.lower__.go

@@ -0,0 +1,56 @@
+// Package {{ moduleName | lower }} is the public surface of the {{ moduleName | lower }} module. Everything else
+// lives under internal/, which the Go compiler forbids other modules from importing — the
+// boundary is enforced by `go build`, not by a review.
+package {{ moduleName | lower }}
+
+import (
+	"context"
+	"time"
+
+	"{{ moduleHost }}/{{ solutionName | kebab }}/internal/modules/{{ moduleName | lower }}/internal/store"
+	"{{ moduleHost }}/{{ solutionName | kebab }}/internal/shared/events"
+)
+
+// ChangedType is published when this module changes something other modules may care about.
+const ChangedType = "{{ moduleName | kebab }}.changed"
+
+// Summary is the read model handed across the boundary. Never a persistence row.
+type Summary struct {
+	ID   string
+	Name string
+}
+
+// Changed is an integration event other modules subscribe to via the bus.
+type Changed struct {
+	ID string
+	At time.Time
+}
+
+func (c Changed) EventType() string     { return ChangedType }
+func (c Changed) OccurredAt() time.Time { return c.At }
+
+// Module is the whole of this module's callable surface.
+type Module interface {
+	Find(ctx context.Context, id string) (*Summary, error)
+}
+
+// New wires the module. The caller gets the interface and learns nothing about what is behind it.
+func New(bus *events.Bus) Module {
+	return &service{bus: bus, repo: store.NewRepository()}
+}
+
+// service is unexported: the implementation is private even inside this package's own module.
+type service struct {
+	bus  *events.Bus
+	repo *store.Repository
+}
+
+func (s *service) Find(ctx context.Context, id string) (*Summary, error) {
+	name := s.repo.NameOf(id)
+
+	// Cross-module notification goes through the bus, never through a direct call.
+	if err := s.bus.Publish(ctx, Changed{ID: id, At: time.Now()}); err != nil {
+		return nil, err
+	}
+	return &Summary{ID: id, Name: name}, nil
+}

package/templates/architectures/modular-monolith/files/internal/modules/__moduleName.lower__/internal/store/store.go

@@ -0,0 +1,12 @@
+// Package store is private to the {{ moduleName | lower }} module. Because it sits under the module's
+// internal/ directory, the compiler rejects any import of it from another module.
+package store
+
+// Repository stands in for this module's persistence. Replace with the real thing.
+type Repository struct{}
+
+func NewRepository() *Repository { return &Repository{} }
+
+func (r *Repository) NameOf(id string) string {
+	return "{{ moduleName | title }} " + id
+}

package/templates/architectures/modular-monolith/files/internal/shared/events/bus.go

@@ -0,0 +1,60 @@
+// Package events is the in-process event bus: the only sanctioned way for one module to
+// notify another. It sits in the shared kernel and must never import a module.
+package events
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// Event is a fact one module publishes and any other module may react to.
+type Event interface {
+	// EventType routes the event to its consumers.
+	EventType() string
+	// OccurredAt is when the fact happened, not when it was dispatched.
+	OccurredAt() time.Time
+}
+
+// Consumer handles one event. A returned error aborts the publish.
+type Consumer func(ctx context.Context, e Event) error
+
+// Bus dispatches to every consumer registered for the event type, in registration order, on
+// the publisher's goroutine. Swap it for a queue the day a module is extracted.
+type Bus struct {
+	mu        sync.RWMutex
+	consumers map[string][]Consumer
+}
+
+func NewBus() *Bus {
+	return &Bus{consumers: make(map[string][]Consumer)}
+}
+
+// Subscribe returns an unsubscribe func so tests and short-lived scopes can clean up.
+func (b *Bus) Subscribe(eventType string, consumer Consumer) func() {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	index := len(b.consumers[eventType])
+	b.consumers[eventType] = append(b.consumers[eventType], consumer)
+	return func() {
+		b.mu.Lock()
+		defer b.mu.Unlock()
+		b.consumers[eventType][index] = nil
+	}
+}
+
+func (b *Bus) Publish(ctx context.Context, e Event) error {
+	b.mu.RLock()
+	registered := append([]Consumer(nil), b.consumers[e.EventType()]...)
+	b.mu.RUnlock()
+
+	for _, consumer := range registered {
+		if consumer == nil {
+			continue
+		}
+		if err := consumer(ctx, e); err != nil {
+			return err
+		}
+	}
+	return nil
+}