# Aether Domain Models

This directory contains complete Domain-Driven Design (DDD) models for Aether's bounded contexts.

## Quick Navigation

**Just want to understand Namespace Isolation quickly?**
→ Start with [NAMESPACE_ISOLATION_QUICK_REFERENCE.md](./NAMESPACE_ISOLATION_QUICK_REFERENCE.md) (5 min read)

**Planning refactoring work?**
→ Read [NAMESPACE_ISOLATION_SUMMARY.md](./NAMESPACE_ISOLATION_SUMMARY.md) (15 min)

**Need complete reference for implementation?**
→ Review [DOMAIN_MODEL_NAMESPACE_ISOLATION.md](./DOMAIN_MODEL_NAMESPACE_ISOLATION.md) (45 min)

**Want visual architecture and diagrams?**
→ Check [NAMESPACE_ISOLATION_ARCHITECTURE.md](./NAMESPACE_ISOLATION_ARCHITECTURE.md) (20 min)

**Integrating multiple contexts?**
→ See [DOMAIN_MODEL_INDEX.md](./DOMAIN_MODEL_INDEX.md) for all contexts

---

## Namespace Isolation Context (Your Focus)

**Status:** Implementation complete, refactoring planned

**Documents (in order of detail):**

| Document | Size | Read Time | Purpose |
|----------|------|-----------|---------|
| [NAMESPACE_ISOLATION_QUICK_REFERENCE.md](./NAMESPACE_ISOLATION_QUICK_REFERENCE.md) | 12 KB | 5 min | Checklists, code examples, quick lookups |
| [NAMESPACE_ISOLATION_SUMMARY.md](./NAMESPACE_ISOLATION_SUMMARY.md) | 16 KB | 15 min | Status, gaps, priorities, security |
| [NAMESPACE_ISOLATION_ARCHITECTURE.md](./NAMESPACE_ISOLATION_ARCHITECTURE.md) | 20 KB | 20 min | Diagrams, flows, visual explanations |
| [DOMAIN_MODEL_NAMESPACE_ISOLATION.md](./DOMAIN_MODEL_NAMESPACE_ISOLATION.md) | 40 KB | 45 min | Complete domain model, all aspects |
| [NAMESPACE_ISOLATION_DELIVERY.md](./NAMESPACE_ISOLATION_DELIVERY.md) | 16 KB | 10 min | What was delivered, how to use it |

**Total:** 104 KB, 2,590 lines of documentation

---

## Core Invariant (TL;DR)

**Events in namespace X must be invisible to queries from namespace Y** (except via explicit wildcard subscriptions by trusted components)

Enforced at three layers:
1. **Memory:** EventBus separates exact and wildcard subscribers
2. **Storage:** JetStreamEventStore creates separate streams per namespace
3. **Network:** NATSEventBus publishes to namespaced NATS subjects

---

## Other Bounded Contexts

Also available (created in previous modeling sessions):

- [DOMAIN_MODEL_EVENT_SOURCING.md](./DOMAIN_MODEL_EVENT_SOURCING.md) (37 KB) - Event persistence and replay
- [DOMAIN_MODEL_OCC.md](./DOMAIN_MODEL_OCC.md) (29 KB) - Optimistic concurrency control
- [DOMAIN_MODEL_INDEX.md](./DOMAIN_MODEL_INDEX.md) (16 KB) - Index of all contexts

---

## How These Were Created

Using DDD framework:

1. **Identified Invariants:** Business rules that must never break
2. **Defined Aggregates:** Clusters enforcing invariants (found 0 in Namespace Isolation - it's primitives)
3. **Specified Commands:** User/system intents to change state (4 defined)
4. **Designed Events:** Facts that happened (3 defined)
5. **Created Policies:** Automated reactions (6 defined)
6. **Modeled Read Models:** Queryable views with no invariants (4 defined)
7. **Analyzed Code:** Compared intended vs. actual implementation (found 5 gaps)
8. **Built Refactoring Backlog:** Actionable improvements (6 issues prioritized)

---

## Key Files in Codebase

```
eventbus.go (268 lines)           - Local pub/sub with isolation
nats_eventbus.go (231 lines)      - Cross-node replication
pattern.go (197 lines)            - Pattern matching & filtering
store/jetstream.go (382 lines)    - Storage isolation
store/namespace_test.go (125 lines) - Existing tests
```

---

## Refactoring Priorities

| Priority | Work | Effort | Impact |
|----------|------|--------|--------|
| P1 | Add namespace field to Event | 2-3 days | HIGH - enables auditing |
| P2 | Explicit namespace validation | 1 day | MEDIUM - prevents silent errors |
| P3 | NamespacedEventBus wrapper | 2-3 days | MEDIUM - easier API |
| P4 | Integration tests | 1-2 days | HIGH - confidence |
| P5 | Documentation | 1 day | MEDIUM - clarity |

**Total Effort:** 8-10 days, no blocking dependencies

---

## Security Checklist

- [ ] Wildcard subscriptions are trusted code only (ops, logging, admin)
- [ ] Application validates namespace format
- [ ] No way for external clients to trigger wildcard
- [ ] Audit logging enabled for wildcard subscriptions
- [ ] Cross-namespace queries fail (GetEvents blocks at stream level)
- [ ] Integration tests verify isolation

---

## For Different Roles

**Product Manager:**
1. NAMESPACE_ISOLATION_SUMMARY.md (5 min)
2. Refactoring priorities table
3. Security checklist

**Developer:**
1. DOMAIN_MODEL_NAMESPACE_ISOLATION.md (30 min)
2. Choose refactoring from P1-P3
3. Reference QUICK_REFERENCE.md while coding

**Architect:**
1. NAMESPACE_ISOLATION_ARCHITECTURE.md (20 min)
2. Review design decisions
3. Check integration with other contexts via DOMAIN_MODEL_INDEX.md

**Security Auditor:**
1. NAMESPACE_ISOLATION_SUMMARY.md Security section (10 min)
2. QUICK_REFERENCE.md Security Checklist (15 min)
3. Safety Documentation in full model

**Code Reviewer:**
1. QUICK_REFERENCE.md Anti-Patterns (2 min)
2. SUMMARY.md Implementation Alignment (15 min)
3. ARCHITECTURE.md event flows as reference

---

## Questions?

- **What is namespace isolation?** → QUICK_REFERENCE.md
- **What needs to be fixed?** → SUMMARY.md Refactoring Priorities
- **How does it work?** → ARCHITECTURE.md diagrams
- **What's the complete design?** → DOMAIN_MODEL_NAMESPACE_ISOLATION.md
- **How do I find information?** → DOMAIN_MODEL_INDEX.md

---

## Files in This Directory

**Namespace Isolation (Your Focus):**
- README_DOMAIN_MODELS.md (this file)
- NAMESPACE_ISOLATION_QUICK_REFERENCE.md
- NAMESPACE_ISOLATION_SUMMARY.md
- NAMESPACE_ISOLATION_ARCHITECTURE.md
- DOMAIN_MODEL_NAMESPACE_ISOLATION.md
- NAMESPACE_ISOLATION_DELIVERY.md

**Other Contexts:**
- DOMAIN_MODEL_INDEX.md (all contexts)
- DOMAIN_MODEL_EVENT_SOURCING.md
- DOMAIN_MODEL_OCC.md
- DOMAIN_MODEL_SUMMARY.md (high-level overview)

**Total:** 10 documents, ~200 KB

---

**Status:** All domain models complete and production-ready
**Last Updated:** 2026-01-12
**Modeled By:** DDD Framework (Claude Haiku 4.5)