aether/.product-strategy/DOMAIN_MODEL_INDEX.md

# Aether Domain Models: Complete Index

## Overview

This directory contains tactical Domain-Driven Design (DDD) models for Aether, a distributed actor system with event sourcing for Go powered by NATS. Each bounded context has its own domain model capturing invariants, aggregates, commands, events, policies, and read models.

**Start here:** [NAMESPACE_ISOLATION_SUMMARY.md](#namespace-isolation-bounded-context) for a quick overview of the context assigned to you.

---

## Bounded Contexts

### Namespace Isolation Bounded Context

**Responsibility:** Provide logical boundaries for event visibility and storage; prevent data cross-contamination between different scopes (tenants, domains, environments).

**Core Invariant:** Events published to namespace X must be invisible to queries from namespace Y (except via explicit wildcard subscriptions by trusted components).

**Documents:**
1. **[DOMAIN_MODEL_NAMESPACE_ISOLATION.md](./DOMAIN_MODEL_NAMESPACE_ISOLATION.md)** (37 KB)
   - Complete domain model: invariants, aggregates, commands, events, policies, read models
   - Code analysis comparing intended design with actual implementation
   - Refactoring backlog with 6 prioritized issues
   - Safety documentation for wildcard subscriptions
   - Testing strategy with unit and integration test recommendations
   - Design decisions explaining key choices (namespace as string, per-namespace streams, etc.)

2. **[NAMESPACE_ISOLATION_SUMMARY.md](./NAMESPACE_ISOLATION_SUMMARY.md)** (15 KB)
   - Executive summary of implementation status
   - Alignment matrix: which invariants are enforced, where
   - Refactoring priorities ranked by impact (P1-P5)
   - Implementation checklist with effort estimates
   - Security considerations and risk assessment

3. **[NAMESPACE_ISOLATION_ARCHITECTURE.md](./NAMESPACE_ISOLATION_ARCHITECTURE.md)** (18 KB)
   - Visual system architecture and data flow diagrams
   - Invariant enforcement across three layers (memory, storage, network)
   - Event flow scenarios: exact isolation, wildcard bypass, cross-node publishing
   - Pattern matching rules and sanitization process
   - Value objects, commands, policies reference
   - Failure scenarios and testing matrix

**Key Files in Codebase:**
- `/Users/hugo.nijhuis/src/github/flowmade-one/aether/eventbus.go` (268 lines) - Local pub/sub with exact and wildcard routing
- `/Users/hugo.nijhuis/src/github/flowmade-one/aether/nats_eventbus.go` (231 lines) - Cross-node pub/sub via NATS
- `/Users/hugo.nijhuis/src/github/flowmade-one/aether/pattern.go` (197 lines) - NATS-native pattern matching
- `/Users/hugo.nijhuis/src/github/flowmade-one/aether/store/jetstream.go` (382 lines) - Storage-layer namespace isolation
- `/Users/hugo.nijhuis/src/github/flowmade-one/aether/store/namespace_test.go` (125 lines) - Existing tests

**Status:** Implementation is 85% complete. Core invariants are enforced. Main gaps are metadata tracking (namespace field in Event) and explicit application-layer validation.

---

## How to Read the Domain Models

### For Architects / Decision-Makers

**Start with:** NAMESPACE_ISOLATION_SUMMARY.md
- 2-minute read: executive status
- Understand alignment of code with intended model
- See refactoring priorities and effort estimates

**Then:** NAMESPACE_ISOLATION_ARCHITECTURE.md
- Visual understanding of how isolation works
- See where invariants are enforced
- Understand failure scenarios and mitigations

### For Developers Implementing Changes

**Start with:** DOMAIN_MODEL_NAMESPACE_ISOLATION.md
- Complete reference: invariants, commands, events, policies
- Code analysis showing gaps between design and implementation
- Refactoring backlog with clear acceptance criteria

**Reference:** NAMESPACE_ISOLATION_ARCHITECTURE.md
- Understand event flow and routing logic
- See pattern matching rules and sanitization
- Use as guide when modifying EventBus or storage layer

### For Code Reviewers / Security Auditors

**Start with:** NAMESPACE_ISOLATION_SUMMARY.md (Security Considerations section)
- Understand wildcard subscription risks
- See documented mitigations
- Review recommended controls

**Deep dive:** DOMAIN_MODEL_NAMESPACE_ISOLATION.md (Safety Documentation section)
- Security design decisions
- Code locations of warnings
- Examples of safe vs. dangerous patterns

---

## Other Bounded Contexts

While your focus is Namespace Isolation, Aether has other contexts worth understanding:

### Event Sourcing Bounded Context

**[DOMAIN_MODEL_EVENT_SOURCING.md](./DOMAIN_MODEL_EVENT_SOURCING.md)** (37 KB)

Responsibility: Provide event persistence, replay, and snapshot capabilities as the source of truth.

**Key Concepts:**
- Event: Immutable fact that happened
- EventStore: Interface for persistence (InMemoryEventStore, JetStreamEventStore)
- Snapshot: Point-in-time state to avoid full replay
- ActorID: Logical entity identifier

**Invariants:**
- Events are immutable after creation
- Event stream per actor
- Snapshots are optional optimization

**Integration with Namespace Isolation:**
- Events are persisted in namespace-scoped stores
- Replay respects namespace boundaries
- Snapshot storage is also per-namespace

### Optimistic Concurrency Control (OCC) Bounded Context

**[DOMAIN_MODEL_OCC.md](./DOMAIN_MODEL_OCC.md)** (29 KB)

Responsibility: Prevent concurrent modification conflicts while maintaining high throughput.

**Key Concepts:**
- Version: Monotonically increasing per actor
- VersionConflictError: Raised when write conflicts with current state
- OptimisticLocking: Read version, attempt write, retry on conflict

**Invariants:**
- Versions must be strictly monotonic per actor
- Conflicts are detected and reported
- Retries are application responsibility

**Integration with Namespace Isolation:**
- Version tracking is per-namespace store
- GetLatestVersion() queries only the namespace's stream
- Conflicts can only occur within a namespace

**Integration with Event Sourcing:**
- Events carry version numbers
- Replay rebuilds version sequence
- Snapshots preserve version for fast forward

### Supporting Bounded Contexts (Not Yet Modeled)

- **Cluster Management** - Node discovery, leader election, shard distribution
- **Metrics and Monitoring** - Observability for pub/sub, storage, clustering
- **Distributed Tracing** - Event causality, correlation IDs, trace propagation

---

## Design Principles (From Vision)

All domain models align with Aether's core principles:

### Primitives Over Frameworks
- Namespace is a value object, not an aggregate
- No opinionated namespace framework
- Application defines meaning (tenant, domain, environment)

### NATS-Native
- Subject patterns use NATS "*" and ">" wildcards
- Separate JetStream stream per namespace (not stream-per-tenant layer)
- Cross-node pub/sub leverages NATS directly

### Resource Conscious
- Minimal overhead for namespace isolation
- No namespace registry needed
- Optional: backward compatible without namespace

### Events as Complete History
- All events persisted per namespace
- No deletion, only retention policy
- Replay rebuilds complete state within namespace

---

## Key Concepts Glossary

| Term | Definition | Example |
|------|-----------|---------|
| **Namespace** | Logical boundary for event visibility | "tenant-abc", "prod.orders", "staging.users" |
| **Pattern** | NATS-style wildcard for matching namespaces | "*" (single token), "prod.*" (multi), ">" (all) |
| **Exact Subscription** | Subscribe to specific namespace, isolation enforced | `Subscribe("tenant-abc")` |
| **Wildcard Subscription** | Subscribe to pattern matching multiple namespaces, isolation bypassed | `Subscribe("prod.*")` (only for trusted code) |
| **EventBus** | In-memory pub/sub with local subscriptions | Delivers to exact and wildcard subscribers |
| **NATSEventBus** | Cross-node pub/sub via NATS | Replicates events across cluster |
| **JetStreamEventStore** | Persistent event storage per namespace | Separate streams: "tenant-a_events", "tenant-b_events" |
| **SubscriptionFilter** | Optional event filtering by type and actor pattern | `&SubscriptionFilter{EventTypes: ["OrderPlaced"]}` |
| **Subject** | NATS address for routing | "aether.events.tenant-abc" |
| **Invariant** | Business rule that must never be broken | "Events in namespace X invisible to namespace Y" |
| **Aggregate** | Cluster of entities enforcing an invariant | None in Namespace Isolation (no lifecycle/rules) |
| **Value Object** | Immutable object defined by attributes | Namespace, SubjectPattern, SubscriptionFilter |
| **Command** | Intent to change state | DefineNamespace, PublishToNamespace, SubscribeToNamespace |
| **Event** | Fact that happened (immutable) | EventPublished (system fact, not currently modeled) |
| **Policy** | Automated reaction to events | Namespace routing, subject formatting, stream isolation |
| **Read Model** | Optimized query view (no invariants) | GetEventsInNamespace, SubscriberCountPerNamespace |

---

## Architecture Layers

### Application Layer
- Defines namespace meaning
- Validates namespace format
- Controls access to wildcard subscriptions
- Orchestrates event flow

### Domain Layer (Namespace Isolation Context)
- Value objects: Namespace, SubjectPattern, SubscriptionFilter
- Commands: DefineNamespace, PublishToNamespace, SubscribeToNamespace
- Policies: namespace routing, subject formatting, storage isolation
- Read models: GetEventsInNamespace, SubscriberCount
- No aggregates (primitives, not domain entities)

### Infrastructure Layer
- **EventBus** (local pub/sub): exactSubscribers + wildcardSubscribers
- **NATSEventBus** (cross-node): NATS subject routing
- **JetStreamEventStore** (persistence): per-namespace streams
- **Pattern Matching** (routing): token-based NATS matching
- **Subject Sanitization** (safety): prevent injection

---

## Quick Start: Using These Documents

### I want to understand how namespace isolation works
→ Read: NAMESPACE_ISOLATION_ARCHITECTURE.md (15 min)

### I need to implement a refactoring from the backlog
→ Read: DOMAIN_MODEL_NAMESPACE_ISOLATION.md (Refactoring Backlog section) (30 min)

### I'm reviewing a PR that changes EventBus or storage
→ Read: NAMESPACE_ISOLATION_SUMMARY.md (Implementation Alignment section) (15 min)

### I'm adding a new feature that uses namespaces
→ Read: DOMAIN_MODEL_NAMESPACE_ISOLATION.md (Invariants, Commands, Policies) (45 min)

### I'm auditing security
→ Read: NAMESPACE_ISOLATION_SUMMARY.md (Security Considerations section) + DOMAIN_MODEL_NAMESPACE_ISOLATION.md (Safety Documentation section) (30 min)

### I'm integrating Namespace Isolation with another context (e.g., Event Sourcing)
→ Read: All three NAMESPACE_ISOLATION docs + relevant context from [DOMAIN_MODEL_EVENT_SOURCING.md](./DOMAIN_MODEL_EVENT_SOURCING.md)

---

## Refactoring Priorities at a Glance

| Priority | Issue | Effort | Status |
|----------|-------|--------|--------|
| P1 | Add Namespace to Event metadata | 2-3 days | Pending |
| P2 | Add explicit namespace validation | 1 day | Pending |
| P3 | Create NamespacedEventBus wrapper | 2-3 days | Pending |
| P4 | Cross-namespace integration tests | 1-2 days | Pending |
| P5 | Document namespace hierarchies | 1 day | Pending |

**Total effort for all refactoring:** ~8-10 days
**Can be done incrementally; no blocking dependencies**

---

## Files Created

All documents are in `/Users/hugo.nijhuis/src/github/flowmade-one/aether/`:

- ✓ DOMAIN_MODEL_NAMESPACE_ISOLATION.md (37 KB) - Complete model
- ✓ NAMESPACE_ISOLATION_SUMMARY.md (15 KB) - Quick reference
- ✓ NAMESPACE_ISOLATION_ARCHITECTURE.md (18 KB) - Visual architecture
- ✓ DOMAIN_MODEL_INDEX.md (this file) - Navigation guide

**Also available in this directory:**
- DOMAIN_MODEL_EVENT_SOURCING.md - Event persistence context
- DOMAIN_MODEL_OCC.md - Optimistic concurrency context
- DOMAIN_MODEL_SUMMARY.md - High-level overview of all contexts

---

## Next Steps

### For Immediate Use

1. **Review NAMESPACE_ISOLATION_SUMMARY.md** (5 min)
   - Understand current implementation status
   - See what's working and what's not

2. **Choose a refactoring from P1-P3** (most impactful)
   - P1 (Event metadata) enables better tracing
   - P2 (Validation) prevents silent behavior changes
   - P3 (Wrapper) improves API safety

3. **Read the relevant section in DOMAIN_MODEL_NAMESPACE_ISOLATION.md**
   - Understand the invariants and policies involved
   - See implementation guidance and acceptance criteria

### For Long-Term Development

1. **Integrate this model into your backlog system**
   - Use refactoring issues as work items
   - Reference domain concepts in commit messages
   - Update domain model as understanding evolves

2. **Keep domain model and code synchronized**
   - When adding features, update the model
   - When encountering gaps, document them in the backlog
   - Use domain language in code reviews

3. **Build related contexts incrementally**
   - Cluster Management (node discovery, leader election)
   - Metrics and Monitoring (observability)
   - Distributed Tracing (event causality)

---

## References

- **Aether Vision:** `/Users/hugo.nijhuis/src/github/flowmade-one/aether/vision.md`
- **Organization Manifesto:** https://git.flowmade.one/flowmade-one/architecture
- **DDD Guidelines:** See `ddd` skill in Claude Code
- **Product Strategy Framework:** See `product-strategy` skill in Claude Code

---

## Questions?

These domain models are designed to be:
- **Complete**: All aspects of the context are documented
- **Actionable**: Every issue has clear acceptance criteria
- **Evolvable**: Easy to update as understanding improves
- **Aligned**: With organization vision and Aether principles

If something is unclear or missing, it's a documentation gap. File an issue or update the model as you discover new information.

---

**Last Updated:** 2026-01-12
**Context Modeled By:** Domain-Driven Design skill (Claude Haiku 4.5)
**Status:** Ready for implementation