Move product strategy documentation to .product-strategy directory

Organize all product strategy and domain modeling documentation into a dedicated .product-strategy directory for better separation from code. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-12 23:57:11 +01:00
parent 18ea677585
commit 271f5db444
26 changed files with 16521 additions and 0 deletions
--- a/.product-strategy/DOMAIN_MODEL_INDEX.md
+++ b/.product-strategy/DOMAIN_MODEL_INDEX.md
@@ -0,0 +1,339 @@
+# 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