# Bounded Context Map: Aether Distributed Actor System

## Summary

Aether has **five distinct bounded contexts** cut by language boundaries, lifecycle differences, ownership patterns, and scaling needs. The contexts emerge from the problem space: single-node event sourcing, distributed clustering, logical isolation, optimistic concurrency control, and event distribution.

**Key insight:** Each context has its own ubiquitous language (different meanings for similar terms) and its own lifecycle (actors persist forever; leases expire; subscriptions have independent lifetimes). Boundaries are enforced by language/data ownership, not by organizational structure.

---

## Bounded Contexts

### Context 1: Event Sourcing

**Purpose:** Persist events as immutable source of truth; enable state rebuild through replay.

**Core Responsibility:**
- Events are facts (immutable, append-only)
- Versions are monotonically increasing per actor
- Snapshots are optional optimization hints, not required
- Replay reconstructs state from history

**Language (Ubiquitous Language):**
- **Event**: Immutable fact about what happened; identified by ID, type, actor, version
- **Version**: Monotonically increasing sequence number per actor; used for optimistic locking
- **Snapshot**: Point-in-time state capture at a specific version; optional; can always replay
- **ActorID**: Identifier for the entity whose events we're storing; unique within namespace
- **Replay**: Process of reading events from start version, applying each, to rebuild state

**Key Entities (Event-Based, not Object-Based):**
- Event (immutable, versioned)
- ActorSnapshot (optional state cache)
- EventStore interface (multiple implementations)

**Key Events Published:**
- `EventStored` - Event successfully persisted (triggered when SaveEvent succeeds)
- `VersionConflict` - Attempted version <= current; optimistic lock lost (expensive mistake)
- `SnapshotCreated` - State snapshot saved (optional; developers decide when)

**Key Events Consumed:**
- None (this context is a source of truth; others consume from it)

**Interfaces to Other Contexts:**
- **Cluster Coordination**: Cluster leader queries latest versions to assign shards
- **Namespace Isolation**: Stores can be namespaced; queries filtered by namespace
- **Optimistic Concurrency**: Version conflicts trigger retry logic in application
- **Event Bus**: Events stored here are published to bus subscribers

**Lifecycle:**
- Event creation: Triggered by application business logic (domain events)
- Event persistence: Synchronous SaveEvent call (writes to store)
- Event durability: Persists forever (or until retention policy expires in JetStream)
- Snapshot lifecycle: Optional; created by application decision or rebalancing; can be safely discarded (replay recovers)

**Owner:** Developer (application layer) owns writing events; Aether library owns storage

**Current Code Locations:**
- `/aether/event.go` - Event struct, VersionConflictError, ReplayError
- `/aether/store/memory.go` - InMemoryEventStore implementation
- `/aether/store/jetstream.go` - JetStreamEventStore implementation (production)

**Scaling Concerns:**
- Single node: Full replay fast for actors with <100 events; snapshots help >100 events
- Cluster: Events stored in JetStream (durable across nodes); replay happens on failover
- Multi-tenant: Events namespaced; separate streams per namespace avoid cross-contamination

**Alignment with Vision:**
- **Primitives over Frameworks**: EventStore is interface; multiple implementations
- **NATS-Native**: JetStreamEventStore uses JetStream durability
- **Events as Complete History**: Events are source of truth; state is derived

**Gaps/Observations:**
- Snapshot strategy is entirely application's responsibility (no built-in triggering)
- Schema evolution for events not discussed (backward compatibility on deserialization)
- Corruption recovery (ReplayError handling) is application's responsibility

**Boundary Rules:**
- Inside: Event persistence, version validation, replay logic
- Outside: Domain logic that generates events, retry policy on conflicts, snapshot triggering
- Cannot cross: No shared models between Event Sourcing and other contexts; translation happens via events

---

### Context 2: Optimistic Concurrency Control

**Purpose:** Detect and signal concurrent write conflicts; let application choose retry strategy.

**Core Responsibility:**
- Protect against lost writes from concurrent writers
- Detect conflicts early (version mismatch)
- Provide detailed error context for retry logic
- Enable at-least-once semantics for idempotent operations

**Language (Ubiquitous Language):**
- **Version**: Sequential number tracking writer's view of current state
- **Conflict**: Condition where attempted version <= current version (another writer won)
- **Optimistic Lock**: Assumption that conflicts are rare; detect when they happen
- **Retry**: Application's response to conflict; reload state and attempt again
- **AttemptedVersion**: Version proposed by current writer
- **CurrentVersion**: Version that actually won the race

**Key Entities:**
- VersionConflictError (detailed error with actor ID, attempted, current versions)
- OptimisticLock pattern (implicit; not a first-class entity)

**Key Events Published:**
- `VersionConflict` - SaveEvent rejected due to version <= current (developer retries)

**Key Events Consumed:**
- None directly; consumes version state from Event Sourcing

**Interfaces to Other Contexts:**
- **Event Sourcing**: Reads latest version; detects conflicts on save
- **Application Logic**: Application handles conflict and decides retry strategy

**Lifecycle:**
- Conflict detection: Synchronous in SaveEvent (fast check: version > current)
- Conflict lifecycle: Temporary; conflict happens then application retries with new version
- Error lifecycle: Returned immediately; application decides next action

**Owner:** Aether library (detects conflicts); Application (implements retry strategy)

**Current Code Locations:**
- `/aether/event.go` - ErrVersionConflict sentinel, VersionConflictError type
- `/aether/store/jetstream.go` - SaveEvent validation (lines checking version)
- `/aether/store/memory.go` - SaveEvent validation

**Scaling Concerns:**
- High contention: If many writers target same actor, conflicts spike; application must implement backoff
- Retry storms: Naive retry (tight loop) causes cascade failures; exponential backoff mitigates
- Metrics: Track conflict rate to detect unexpected contention

**Alignment with Vision:**
- **Primitives over Frameworks**: Aether returns error; application decides what to do
- Does NOT impose retry strategy (that would be a framework opinion)

**Gaps/Observations:**
- No built-in retry mechanism (intentional design choice)
- No conflict metrics in library (application must instrument)
- No guidance on retry backoff strategies in code (documented in PROBLEM_MAP, not in API)

**Boundary Rules:**
- Inside: Detect conflict, validate version > current, return detailed error
- Outside: Retry logic, backoff strategy, exponential delays, giving up after N attempts
- Cannot cross: Each context owns its retry behavior; no global retry handler

---

### Context 3: Namespace Isolation

**Purpose:** Provide logical data boundaries without opinionated multi-tenancy framework.

**Core Responsibility:**
- Route events to subscribers matching namespace pattern
- Isolate event stores by namespace prefix
- Support hierarchical namespace naming (e.g., "prod.tenant-abc", "staging.orders")
- Warn about wildcard bypass of isolation (explicit decision)

**Language (Ubiquitous Language):**
- **Namespace**: Logical boundary (tenant, domain, environment, bounded context)
- **Namespace Pattern**: NATS-style wildcard matching: "*" (single token), ">" (multi-token)
- **Isolation**: Guarantee that events in namespace-A cannot be read from namespace-B (except via wildcard)
- **Wildcard Subscription**: Cross-namespace visibility for trusted components (logging, monitoring)
- **Subject**: NATS subject for routing (e.g., "aether.events.{namespace}")

**Key Entities:**
- Namespace (just a string; meaning is application's)
- JetStreamConfig with Namespace field (storage isolation)
- SubscriptionFilter with namespace pattern (matching)
- NATSEventBus subject routing

**Key Events Published:**
- `EventPublished` - Event sent to namespace subscribers (via EventBus.Publish)

**Key Events Consumed:**
- Events from Event Sourcing, filtered by namespace pattern

**Interfaces to Other Contexts:**
- **Event Sourcing**: Stores can be namespaced (prefix in stream name)
- **Event Bus**: Publishes to namespace; subscribers match by pattern
- **Cluster Coordination**: Might use namespaced subscriptions to isolate tenant events

**Lifecycle:**
- Namespace definition: Application decides; typically per-tenant or per-domain
- Namespace creation: Implicit when first store/subscription uses it (no explicit schema)
- Namespace deletion: Not supported; namespaces persist if events exist
- Stream lifetime: JetStream stream "namespace_events" persists until deleted

**Owner:** Application layer (defines namespace boundaries); Library (enforces routing)

**Current Code Locations:**
- `/aether/eventbus.go` - EventBus exact vs wildcard subscriber routing
- `/aether/nats_eventbus.go` - NATSEventBus subject formatting (line 89: `fmt.Sprintf("aether.events.%s", namespacePattern)`)
- `/aether/store/jetstream.go` - JetStreamConfig.Namespace field, stream name sanitization (line 83)
- `/aether/pattern.go` - MatchNamespacePattern, IsWildcardPattern functions

**Scaling Concerns:**
- Single namespace: All events in one stream; scales with event volume
- Multi-namespace: Separate streams per namespace; scales horizontally (add namespaces independently)
- Wildcard subscriptions: Cross-namespace visibility; careful with security (documented warnings)

**Alignment with Vision:**
- **Primitives over Frameworks**: Namespaces are primitives; no opinionated multi-tenancy layer
- Non-goal: "Opinionated multi-tenancy" - this library provides isolation primitives, not tenant management

**Gaps/Observations:**
- Namespace collision: No validation that namespace names are unique (risk: "orders" used by two teams)
- Wildcard security: Extensively documented in code (SECURITY WARNING appears multiple times); good
- No namespace registry or allow-list (application must enforce naming conventions)
- Sanitization of namespace names happens in JetStreamEventStore (spaces → underscores) but not documented

**Boundary Rules:**
- Inside: Namespace pattern matching, subject routing, stream prefixing
- Outside: Defining namespace semantics (tenant, domain, environment), enforcing conventions
- Cannot cross: Events in namespace-A published to namespace-A only (except wildcard subscribers)

---

### Context 4: Cluster Coordination

**Purpose:** Distribute actors across cluster nodes; elect leader; rebalance on topology changes.

**Core Responsibility:**
- Discover nodes in cluster (NATS-based, no external coordinator)
- Elect one leader using lease-based coordination
- Distribute shards across nodes via consistent hash ring
- Detect node failures and trigger rebalancing
- Provide shard assignment for actor placement

**Language (Ubiquitous Language):**
- **Node**: Physical or logical computer in cluster; has ID, address, capacity, status
- **Leader**: Single node responsible for coordination and rebalancing decisions
- **Term**: Monotonically increasing leadership election round (prevents split-brain)
- **Shard**: Virtual partition (1024 by default); actors hash to shards; shards assigned to nodes
- **Consistent Hash Ring**: Algorithm mapping shards to nodes such that node failures cause minimal rebalancing
- **Rebalancing**: Reassignment of shards when topology changes (node join/fail)
- **ShardMap**: Current state of which shards live on which nodes
- **Heartbeat**: Periodic signal from leader renewing its lease (proves still alive)
- **Lease**: Time window during which leader's authority is valid (TTL-based, not quorum)

**Key Entities:**
- NodeInfo (cluster node details: ID, address, capacity, status)
- ShardMap (shard → nodes mapping; versioned)
- LeadershipLease (leader ID, term, expiration)
- ActorMigration (migration record for actor during rebalancing)

**Key Events Published:**
- `NodeJoined` - New node added to cluster
- `NodeFailed` - Node stopped responding (detected by heartbeat timeout)
- `LeaderElected` - Leader selected (term incremented)
- `LeadershipLost` - Leader lease expired (old leader can no longer coordinate)
- `ShardAssigned` - Leader assigns shard to nodes
- `ShardMigrated` - Shard moved from one node to another (during rebalancing)

**Key Events Consumed:**
- Node topology changes (new nodes, failures) → trigger rebalancing
- Leader election results → shard assignments

**Interfaces to Other Contexts:**
- **Namespace Isolation**: Could use namespaced subscriptions for cluster-internal events
- **Event Sourcing**: Cluster queries latest version to assign shards; failures trigger replay on new node
- **Event Bus**: Cluster messages published to event bus; subscribers on each node act on them

**Lifecycle:**
- Cluster formation: Nodes join; first leader elected
- Leadership duration: Until lease expires (~10 seconds in config)
- Shard assignment: Decided by leader; persists in ShardMap
- Node failure: Detected after heartbeat timeout (~90 seconds implied by lease config)
- Rebalancing: Triggered by topology change; completes when ShardMap versioned and distributed

**Owner:** ClusterManager (coordination); LeaderElection (election); ShardManager (placement)

**Current Code Locations:**
- `/aether/cluster/types.go` - NodeInfo, ShardMap, LeadershipLease, ActorMigration types
- `/aether/cluster/manager.go` - ClusterManager, node discovery, rebalancing loop
- `/aether/cluster/leader.go` - LeaderElection (lease-based using NATS KV)
- `/aether/cluster/hashring.go` - ConsistentHashRing (shard → node mapping)
- `/aether/cluster/shard.go` - ShardManager (actor placement, shard assignment)

**Scaling Concerns:**
- Leader election latency: 10s lease, 3s heartbeat → ~13s to detect failure (tunable)
- Rebalancing overhead: Consistent hash minimizes movements (only affects shards from failed node)
- Shard count: 1024 default; tune based on cluster size and actor count

**Alignment with Vision:**
- **NATS-Native**: Leader election uses NATS KV store (lease-based); cluster discovery via NATS
- **Primitives over Frameworks**: ShardManager and LeaderElection are composable; can swap algorithms

**Gaps/Observations:**
- Rebalancing is triggered but algorithm not fully shown in code excerpt ("would rebalance across N nodes")
- Actor migration during rebalancing: ShardManager has PlacementStrategy interface but sample migration handler not shown
- Split-brain prevention: Lease-based (no concurrent leaders) but old leader could execute stale rebalancing
- No explicit actor state migration during shard rebalancing (where does actor state go during move?)

**Boundary Rules:**
- Inside: Node discovery, leader election, shard assignment, rebalancing decisions
- Outside: Actor state migration (that's Event Sourcing's replay), actual actor message delivery
- Cannot cross: Cluster decisions are made once per cluster (not per namespace or actor)

---

### Context 5: Event Bus (Pub/Sub Distribution)

**Purpose:** Route events from producers to subscribers; support filtering and cross-node propagation.

**Core Responsibility:**
- Local event distribution (in-process subscriptions)
- Cross-node event distribution via NATS
- Filter events by type and actor pattern
- Support exact and wildcard namespace patterns
- Non-blocking delivery (drop event if channel full, don't block publisher)

**Language (Ubiquitous Language):**
- **Publish**: Send event to namespace (synchronous, non-blocking; may drop if subscribers slow)
- **Subscribe**: Register interest in namespace pattern (returns channel)
- **Filter**: Criteria for event delivery (EventTypes list, ActorPattern wildcard)
- **Wildcard Pattern**: "*" (single token), ">" (multi-token) matching
- **Subject**: NATS subject for routing (e.g., "aether.events.{namespace}")
- **Subscriber**: Entity receiving events from channel (has local reference to channel)
- **Deliver**: Attempt to send event to subscriber's channel; non-blocking (may drop)

**Key Entities:**
- EventBroadcaster interface (local or NATS-backed)
- EventBus (in-memory, local subscriptions only)
- NATSEventBus (extends EventBus; adds NATS forwarding)
- SubscriptionFilter (event types + actor pattern)
- filteredSubscription (internal; tracks channel, pattern, filter)

**Key Events Published:**
- `EventPublished` - Event sent via EventBus.Publish (may be delivered to subscribers)

**Key Events Consumed:**
- Events from Event Sourcing context

**Interfaces to Other Contexts:**
- **Event Sourcing**: Reads events to publish; triggered after SaveEvent
- **Namespace Isolation**: Uses namespace pattern for routing
- **Cluster Coordination**: Cluster messages flow through event bus

**Lifecycle:**
- Subscription creation: Caller invokes Subscribe/SubscribeWithFilter; gets channel
- Subscription duration: Lifetime of channel (caller controls)
- Subscription cleanup: Unsubscribe closes channel
- Event delivery: Synchronous Publish → deliver to all matching subscribers
- Dropped events: Non-blocking delivery; full channel = dropped event (metrics recorded)

**Owner:** Library (EventBus implementation); Callers (subscribe/unsubscribe)

**Current Code Locations:**
- `/aether/eventbus.go` - EventBus (local in-process pub/sub)
- `/aether/nats_eventbus.go` - NATSEventBus (NATS-backed cross-node)
- `/aether/pattern.go` - MatchNamespacePattern, SubscriptionFilter matching logic
- Metrics tracking in both implementations

**Scaling Concerns:**
- Local bus: In-memory channels; scales with subscriber count (no network overhead)
- NATS bus: One NATS subscription per pattern; scales with unique patterns
- Channel buffering: 100-element buffer (configurable); full = dropped events
- Metrics: Track published, delivered, dropped per namespace

**Alignment with Vision:**
- **Primitives over Frameworks**: EventBroadcaster is interface; swappable implementations
- **NATS-Native**: NATSEventBus uses NATS subjects for routing

**Gaps/Observations:**
- Dropped events are silent (metrics recorded but no callback); might surprise subscribers
- Filter matching is string-based (no compile-time safety for event types)
- Two-level filtering: Namespace at NATS level, EventTypes/ActorPattern at application level
- NATSEventBus creates subscription per unique pattern (could be optimized with pattern hierarchy)

**Boundary Rules:**
- Inside: Event routing, filter matching, non-blocking delivery
- Outside: Semantics of events (that's Event Sourcing); decisions on what to do when event received
- Cannot cross: Subscribers are responsible for their channels; publisher doesn't know who consumes

---

## Context Relationships

### Event Sourcing ↔ Event Bus

**Type:** Producer/Consumer (one-to-many)

**Direction:** Event Sourcing produces events; Event Bus distributes them

**Integration:**
- Application saves event to store (SaveEvent)
- Application publishes same event to bus (Publish)
- Subscribers receive event from bus channel
- Events are same object (Event struct)

**Decoupling:**
- Store and bus are independent (application coordinates)
- Bus subscribers don't know about storage
- Replay doesn't trigger bus publish (events already stored)

**Safety:**
- No shared transaction (save and publish are separate)
- Risk: Event saved but publish fails (or vice versa) → bus has stale view
- Mitigation: Application's responsibility to ensure consistency

---

### Event Sourcing → Optimistic Concurrency Control

**Type:** Dependency (nested)

**Direction:** SaveEvent validates version using Optimistic Concurrency

**Integration:**
- SaveEvent calls GetLatestVersion (read current)
- Checks event.Version > currentVersion (optimistic lock)
- Returns VersionConflictError if not

**Decoupling:**
- Optimistic Concurrency is not a separate context; it's logic within Event Sourcing
- Version validation is inline in SaveEvent, not a separate call

**Note:** Initially these seem like separate contexts (different language, different lifecycle). But Version is Event Sourcing's concern; Conflict is just an error condition (not a separate state machine). Optimistic locking is a **pattern**, not a **context**.

---

### Event Sourcing → Namespace Isolation

**Type:** Containment (namespaces contain event streams)

**Direction:** Namespace Isolation scopes Event Sourcing

**Integration:**
- JetStreamEventStore accepts Namespace in config
- Actual stream name becomes "{namespace}_{streamName}"
- GetEvents, GetLatestVersion, SaveEvent are namespace-scoped

**Decoupling:**
- Each namespace has independent version sequences
- No cross-namespace reads in Event Sourcing context
- EventBus.Publish specifies namespace

**Safety:**
- Complete isolation at storage level (different JetStream streams)
- Events from namespace-A cannot appear in namespace-B queries
- Wildcard subscriptions bypass this (documented risk)

---

### Cluster Coordination → Event Sourcing

**Type:** Consumer (reads version state)

**Direction:** Cluster queries Event Sourcing for actor state

**Integration:**
- ClusterManager might query GetLatestVersion to determine if shard can migrate
- Nodes track which actors (shards) are assigned locally
- On failover, new node replays events from store to rebuild state

**Decoupling:**
- Cluster doesn't manage event storage (Event Sourcing owns that)
- Cluster doesn't decide when to snapshot
- Cluster doesn't know about versions (Event Sourcing concept)

---

### Cluster Coordination → Namespace Isolation

**Type:** Orthogonal (can combine, but not required)

**Direction:** Cluster can use namespaced subscriptions; not required

**Integration:**
- Cluster could publish node-join events to namespaced topics (e.g., "cluster.{tenant}")
- Different tenants can have independent clusters (each with own cluster messages)

**Decoupling:**
- Cluster doesn't care about namespace semantics
- Namespace doesn't enforce cluster topology

---

### Event Bus → (All contexts)

**Type:** Cross-cutting concern

**Direction:** Event Bus distributes events from all contexts

**Integration:**
- Event Sourcing publishes to bus after SaveEvent
- Cluster Coordination publishes shard assignments to bus
- Namespace Isolation is a parameter to Publish/Subscribe
- Subscribers receive events and can filter by type/actor

**Decoupling:**
- Bus is asynchronous (events may be lost if no subscribers)
- Subscribers don't block publishers
- No ordering guarantee across namespaces

---

## Boundary Rules Summary

### By Language

| Language | Context | Meaning |
|----------|---------|---------|
| **Event** | Event Sourcing | Immutable fact; identified by ID, type, actor, version |
| **Version** | Event Sourcing | Monotonically increasing sequence per actor; also used for optimistic locking |
| **Snapshot** | Event Sourcing | Optional state cache at specific version; always disposable |
| **Node** | Cluster Coordination | Physical computer in cluster; has ID, address, capacity |
| **Leader** | Cluster Coordination | Single node elected for coordination (not per-namespace, not per-actor) |
| **Shard** | Cluster Coordination | Virtual partition for actor placement; 1024 by default |
| **Namespace** | Namespace Isolation | Logical boundary (tenant, domain, context); application-defined meaning |
| **Wildcard** | Both Event Bus & Namespace | "*" (single token) and ">" (multi-token) NATS pattern matching |
| **Subject** | Event Bus | NATS subject for message routing |
| **Conflict** | Optimistic Concurrency | Condition where write failed due to version being stale |
| **Retry** | Optimistic Concurrency | Application's decision to reload and try again |
| **Subscribe** | Event Bus | Register interest in namespace pattern; returns channel |
| **Publish** | Event Bus | Send event to namespace subscribers; non-blocking |

### By Lifecycle

| Entity | Created | Destroyed | Owner | Context |
|--------|---------|-----------|-------|---------|
| Event | SaveEvent | Never (persists forever) | Application writes, Aether stores | Event Sourcing |
| Version | Per-event | With event | Automatic (monotonic) | Event Sourcing |
| Snapshot | Application decision | Application decision | Application | Event Sourcing |
| Node | Join cluster | Explicit leave | Infrastructure | Cluster Coordination |
| Leader | Election completes | Lease expires | Automatic (election) | Cluster Coordination |
| Shard | Created with cluster | With cluster | ClusterManager | Cluster Coordination |
| Namespace | First use | Never (persist) | Application | Namespace Isolation |
| Subscription | Subscribe() call | Unsubscribe() call | Caller | Event Bus |
| Channel | Subscribe() returns | Unsubscribe() closes | Caller | Event Bus |

### By Ownership

| Context | Who Decides | What They Decide |
|---------|-------------|------------------|
| Event Sourcing | Application (developer) | When to save events, event schema, snapshot strategy |
| Optimistic Concurrency | Application | Retry strategy, backoff, giving up |
| Namespace Isolation | Application | Namespace semantics (tenant, domain, env), naming convention |
| Cluster Coordination | ClusterManager & LeaderElection | Node discovery, leader election, shard assignment |
| Event Bus | Application | What to subscribe to, filtering criteria |

### By Scaling Boundary

| Context | Scales By | Limits | Tuning |
|---------|-----------|--------|--------|
| Event Sourcing | Event volume per actor | Replay latency grows with version count | Snapshots help |
| Cluster Coordination | Node count | Leader election latency, rebalancing overhead | Lease TTL, heartbeat interval |
| Namespace Isolation | Namespace count | Stream count, NATS resource usage | Separate JetStream streams |
| Event Bus | Subscriber count | Channel buffering (100 elements) | Queue depth, metrics |

---

## Code vs. Intended: Alignment Analysis

### Intended → Actual: Good Alignment

**Context: Event Sourcing**
- Intended: EventStore interface with multiple implementations
- Actual: InMemoryEventStore (testing) and JetStreamEventStore (production) both exist
- ✓ Good: Matches vision of "primitives over frameworks"

**Context: Optimistic Concurrency**
- Intended: Detect conflicts, return error, let app retry
- Actual: SaveEvent returns VersionConflictError; no built-in retry
- ✓ Good: Aligns with vision of primitives (app owns retry logic)

**Context: Namespace Isolation**
- Intended: Logical boundaries without opinionated multi-tenancy
- Actual: JetStreamConfig.Namespace, EventBus namespace patterns
- ✓ Good: Primitives provided; semantics left to app

**Context: Cluster Coordination**
- Intended: Node discovery, leader election, shard assignment
- Actual: ClusterManager, LeaderElection, ConsistentHashRing all present
- ✓ Good: Primitives implemented

**Context: Event Bus**
- Intended: Local and cross-node pub/sub with filtering
- Actual: EventBus (local) and NATSEventBus (NATS) both present
- ✓ Good: Extensible via interface

### Intended → Actual: Gaps

**Context: Cluster Coordination**
- Intended: Actor migration during shard rebalancing
- Actual: ShardManager has PlacementStrategy; ActorMigration type defined
- Gap: Migration handler logic not shown; where does actor state transition during rebalance?
- Impact: Cluster context is foundational but incomplete; application must implement actor handoff

**Context: Event Sourcing**
- Intended: Snapshot strategy guidance
- Actual: SnapshotStore interface; SaveSnapshot exists; no built-in strategy
- Gap: No adaptive snapshotting, no time-based snapshotting
- Impact: App must choose snapshot frequency (documented in PROBLEM_MAP, not enforced)

**Context: Namespace Isolation**
- Intended: Warn about wildcard security risks
- Actual: SECURITY WARNING in docstrings (excellent)
- Gap: No namespace registry or allow-list to prevent collisions
- Impact: Risk of two teams using same namespace (e.g., "orders") unintentionally

**Context: Optimistic Concurrency**
- Intended: Guide app on retry strategy
- Actual: Returns VersionConflictError with details
- Gap: No retry helper, no backoff library
- Impact: Each app implements own retry (fine; primitives approach)

---

## Refactoring Backlog (if brownfield)

### No Major Refactoring Required

The code structure already aligns well with intended bounded contexts:
- Event Sourcing lives in `/event.go` and `/store/`
- Cluster lives in `/cluster/`
- Event Bus lives in `/eventbus.go` and `/nats_eventbus.go`
- Pattern matching lives in `/pattern.go`

### Minor Improvements

**Issue 1: Document Actor Migration During Rebalancing**
- Current: ShardManager.AssignShard exists; ActorMigration type defined
- Gap: No example code showing how actor state moves between nodes
- Suggestion: Add sample migration handler in cluster package

**Issue 2: Add Namespace Validation/Registry**
- Current: Namespace is just a string; no collision detection
- Gap: Risk of two teams using same namespace
- Suggestion: Document naming convention (e.g., "env.team.context"); optionally add schema/enum

**Issue 3: Snapshot Strategy Recipes**
- Current: SnapshotStore interface; app responsible for strategy
- Gap: Documentation could provide sample strategies (time-based, count-based, adaptive)
- Suggestion: Add `/examples/snapshot_strategies.go` with reference implementations

**Issue 4: Metrics for Concurrency Context**
- Current: Version conflict detection exists; no metrics
- Gap: Apps can't easily observe conflict rate
- Suggestion: Add conflict metrics to EventStore (or provide hooks)

---

## Recommendations

### For Product Strategy

1. **Confirm Bounded Contexts**: Review this map with team. Are these five contexts the right cut? Missing any? Too many?

2. **Define Invariants per Context**:
   - Event Sourcing: "Version must be strictly monotonic per actor" ✓ (enforced)
   - Cluster Coordination: "Only one leader can have valid lease at a time" ✓ (lease-based)
   - Namespace Isolation: "Events in namespace-A cannot be queried from namespace-B context" ✓ (separate streams)
   - Optimistic Concurrency: "Conflict detection is synchronous; resolution is async" ✓ (error returned immediately)
   - Event Bus: "Delivery is non-blocking; events may be dropped if subscriber slow" ✓ (metrics track this)

3. **Map Capabilities to Contexts**:
   - "Store events durably" → Event Sourcing context
   - "Detect concurrent writes" → Optimistic Concurrency context
   - "Isolate logical domains" → Namespace Isolation context
   - "Distribute actors across nodes" → Cluster Coordination context
   - "Route events to subscribers" → Event Bus context

4. **Test Boundaries**:
   - Single-node: Event Sourcing + Optimistic Concurrency + Event Bus (no Cluster)
   - Multi-node: Add Cluster Coordination (but cluster decisions don't affect other contexts)
   - Multi-tenant: Add Namespace Isolation (orthogonal to other contexts)

### For Architecture

1. **Complete Cluster Context Documentation**:
   - Show actor migration lifecycle during shard rebalancing
   - Document when state moves (during rebalance, during failover)
   - Provide sample ShardManager implementation

2. **Add Snapshot Strategy Guidance**:
   - Time-based: Snapshot every hour
   - Count-based: Snapshot every 100 events
   - Adaptive: Snapshot when replay latency exceeds threshold

3. **Namespace Isolation Checklist**:
   - Define naming convention (document in README)
   - Add compile-time checks (optional enum for known namespaces)
   - Test multi-tenant isolation (integration test suite)

4. **Concurrency Context Testing**:
   - Add concurrent writer tests to store tests
   - Verify VersionConflictError details are accurate
   - Benchmark conflict detection performance

### For Docs

1. **Add Context Diagram**: Show five contexts as boxes; arrows for relationships

2. **Add Per-Context Glossary**: Define ubiquitous language per context (terms table above)

3. **Add Lifecycle Diagrams**: Show event lifetime, node lifetime, subscription lifetime, shard lifetime

4. **Security Section**: Expand wildcard subscription warnings; document trust model

---

## Anti-Patterns Avoided

### Pattern: "One Big Event Model"
- **Anti-pattern**: Single Event struct used everywhere with union types
- **What we do**: Event is generic; domain language lives in EventType strings and Data map
- **Why**: Primitives approach; library doesn't impose domain model

### Pattern: "Shared Mutable State Across Contexts"
- **Anti-pattern**: ClusterManager directly mutates EventStore data structures
- **What we do**: Contexts communicate via events (if they need to) or via explicit queries
- **Why**: Clean boundaries; each context owns its data

### Pattern: "Automatic Retry for Optimistic Locks"
- **Anti-pattern**: Library retries internally on version conflict
- **What we do**: Return error to caller; caller decides retry strategy
- **Why**: Primitives approach; retry policy is app's concern, not library's

### Pattern: "Opinionated Snapshot Strategy"
- **Anti-pattern**: "Snapshot every 100 events" hardcoded
- **What we do**: SnapshotStore interface; app decides when to snapshot
- **Why**: Different apps have different replay latency requirements

### Pattern: "Wildcard Subscriptions by Default"
- **Anti-pattern**: All subscriptions use ">" by default (receive everything)
- **What we do**: Explicit namespaces; wildcard is optional and warned about
- **Why**: Security-first; isolation is default

---

## Conclusion

Aether's five bounded contexts are **well-aligned** with the problem space and the codebase:

1. **Event Sourcing** - Store events as immutable history; enable replay
2. **Optimistic Concurrency** - Detect conflicts; let app retry
3. **Namespace Isolation** - Logical boundaries without opinionated multi-tenancy
4. **Cluster Coordination** - Distribute actors, elect leader, rebalance on failure
5. **Event Bus** - Route events from producers to subscribers

Each context has:
- Clear **language boundaries** (different terms, different meanings)
- Clear **lifecycle boundaries** (different creation/deletion patterns)
- Clear **ownership** (who decides what within each context)
- Clear **scaling boundaries** (why this context must be separate)

The implementation **matches the vision** of "primitives over frameworks." Library provides composition points (interfaces); applications wire them together.

Next step in product strategy: **Define domain models within each context** (Step 4 of strategy chain). For now, Aether provides primitives; applications build their domain models on top.