aether/.product-strategy/BACKLOG_QUICK_REFERENCE.md

Aether Backlog: Quick Reference

Full backlog: /BACKLOG.md (2600+ lines, complete details)

This page is a quick reference for navigating the backlog.

---

Phase Overview

Phase	Name	Capabilities	Issues	Dependencies
1	Event Sourcing Foundation	1, 2, 3	17	None (foundation)
2	Local Event Bus	8	9	Phase 1
3	Cluster Coordination	5, 6, 7	20	Phase 1
4	Namespace & NATS	4, 9	21	Phases 1-3 (parallel)

---

Issue Count by Context

Bounded Context	Phase 1	Phase 2	Phase 3	Phase 4	Total
Event Sourcing	10	-	-	-	10
OCC	2	-	-	-	2
Event Bus	-	9	-	3	12
Cluster	-	-	20	-	20
Namespace	-	-	-	4	4
Documentation	-	-	-	14	14
Total	12	9	20	21	67

---

Phase 1: Event Sourcing Foundation (Issues 1.1-1.12)

Core Storage (1.1-1.5)

Issue	Title	Type	Priority
1.1	SaveEvent with monotonic version	Command	P0
1.2	Enforce append-only	Rule	P0
1.3	Publish EventStored	Event	P0
1.4	Publish VersionConflict	Event	P0
1.5	GetLatestVersion query	Query	P0

State Rebuild (1.6-1.10)

Issue	Title	Type	Priority
1.6	GetEvents for replay	Query	P0
1.7	Snapshot invalidation policy	Rule	P1
1.8	Publish SnapshotCreated	Event	P1
1.9	GetEventsWithErrors	Query	P1
1.10	SnapshotStore interface	Interface	P0

OCC (1.11-1.12)

Issue	Title	Type	Priority
1.11	Fail-fast on conflict	Rule	P0
1.12	Document retry patterns	Docs	P1

---

Phase 2: Local Event Bus (Issues 2.1-2.9)

Routing & Filtering (2.1-2.7)

Issue	Title	Type	Priority
2.1	Publish command	Command	P1
2.2	Subscribe with filter	Command	P1
2.3	Enforce exact isolation	Rule	P1
2.4	Document wildcard security	Docs	P1
2.5	Publish SubscriptionCreated	Event	P2
2.6	Publish EventPublished	Event	P2
2.7	GetSubscriptions query	Query	P2

Backpressure (2.8-2.9)

Issue	Title	Type	Priority
2.8	Non-blocking delivery	Rule	P1
2.9	Document backpressure	Docs	P2

---

Phase 3: Cluster Coordination (Issues 3.1-3.17)

Topology & Leadership (3.1-3.7)

Issue	Title	Type	Priority
3.1	JoinCluster protocol	Command	P1
3.2	LeaderElection	Command	P0
3.3	Single leader invariant	Rule	P0
3.4	Publish LeaderElected	Event	P1
3.5	Publish LeadershipLost	Event	P2
3.6	GetClusterTopology	Query	P1
3.7	GetLeader	Query	P0

Shard Distribution (3.8-3.11)

Issue	Title	Type	Priority
3.8	Consistent hash ring	Command	P1
3.9	Single shard owner invariant	Rule	P0
3.10	Publish ShardAssigned	Event	P2
3.11	GetShardAssignments	Query	P1

Failure & Recovery (3.12-3.17)

Issue	Title	Type	Priority
3.12	Node health checks	Command	P1
3.13	RebalanceShards	Command	P0
3.14	No-orphan invariant	Rule	P0
3.15	Publish NodeFailed	Event	P2
3.16	Publish ShardMigrated	Event	P2
3.17	Document actor migration	Docs	P2

---

Phase 4: Namespace & NATS (Issues 4.1-4.8)

Namespace Storage (4.1-4.4)

Issue	Title	Type	Priority
4.1	Stream naming	Rule	P1
4.2	Storage isolation	Rule	P0
4.3	Design patterns	Docs	P1
4.4	Format validation	Validation	P2

NATS Delivery (4.5-4.8)

Issue	Title	Type	Priority
4.5	NATSEventBus	Command	P1
4.6	Exactly-once delivery	Rule	P1
4.7	Publish EventPublished	Event	P2
4.8	Cross-node subscription	Query	P1

---

Dependency Graph

Phase 1 (Foundation)
├─ 1.1 (SaveEvent)
│  ├─ 1.2 (Append-only)
│  ├─ 1.3 (EventStored event)
│  ├─ 1.4 (VersionConflict event)
│  ├─ 1.5 (GetLatestVersion)
│  ├─ 1.6 (GetEvents)
│  │  ├─ 1.7 (Snapshot policy)
│  │  ├─ 1.8 (SnapshotCreated)
│  │  └─ 1.9 (GetEventsWithErrors)
│  └─ 1.10 (SnapshotStore)
├─ 1.11 (Fail-fast)
│  └─ 1.12 (Retry patterns)

Phase 2 (Event Bus)
├─ 2.2 (Subscribe)
│  ├─ 2.1 (Publish)
│  │  ├─ 2.3 (Exact isolation)
│  │  ├─ 2.5 (SubscriptionCreated)
│  │  └─ 2.6 (EventPublished)
│  └─ 2.7 (GetSubscriptions)
├─ 2.4 (Wildcard docs)
├─ 2.8 (Non-blocking)
│  └─ 2.9 (Backpressure docs)

Phase 3 (Cluster)
├─ 3.1 (JoinCluster)
│  ├─ 3.2 (LeaderElection)
│  │  ├─ 3.3 (Single leader)
│  │  ├─ 3.4 (LeaderElected event)
│  │  ├─ 3.5 (LeadershipLost event)
│  │  └─ 3.7 (GetLeader)
│  ├─ 3.6 (GetClusterTopology)
│  ├─ 3.8 (Consistent hash)
│  │  ├─ 3.9 (Single owner)
│  │  ├─ 3.10 (ShardAssigned)
│  │  └─ 3.11 (GetShardAssignments)
│  ├─ 3.12 (Health checks)
│  │  ├─ 3.13 (RebalanceShards)
│  │  │  ├─ 3.14 (No-orphan)
│  │  │  ├─ 3.15 (NodeFailed)
│  │  │  └─ 3.16 (ShardMigrated)
│  │  └─ 3.17 (Migration docs)

Phase 4 (Namespace & NATS)
├─ 4.1 (Stream naming)
│  ├─ 4.2 (Storage isolation)
│  ├─ 4.3 (Design patterns)
│  └─ 4.4 (Validation)
├─ 4.5 (NATSEventBus) [depends on 2.1]
│  ├─ 4.6 (Exactly-once)
│  ├─ 4.7 (EventPublished)
│  └─ 4.8 (Cross-node subscription)

---

Critical Path

Minimum viable cluster (13 issues):

1. 1.1 SaveEvent (P0)
2. 1.5 GetLatestVersion (P0)
3. 1.6 GetEvents (P0)
4. 1.10 SnapshotStore (P0)
5. 1.11 Fail-fast (P0)
6. 2.1 Publish (P1)
7. 2.2 Subscribe (P1)
8. 3.2 LeaderElection (P0)
9. 3.8 Consistent hash (P1)
10. 3.12 Health checks (P1)
11. 3.13 RebalanceShards (P0)
12. 4.1 Stream naming (P1)
13. 4.5 NATSEventBus (P1)

Estimated duration: 4-6 weeks (aggressive)

---

Implementation Recommendations

Start With Phase 1

• Everything depends on it
• Core domain logic
• Enables testing without clustering
• Parallel: can implement 1.1-1.5 concurrently

Phase 2 Early

• Observability (metrics, logging)
• Tests easier without cluster
• Validate design before clustering

Phase 3 in Parallel

• Can start while Phase 2 incomplete
• Higher complexity (needs multi-node tests)
• Consider spike if team unfamiliar with clustering

Phase 4 Last

• Namespace: orthogonal (can do anytime)
• NATS: depends on 2.1 (Publish)
• Complex (distributed tracing, durability)

---

Key Files

Purpose	File
Full backlog	/BACKLOG.md
Capabilities	/CAPABILITIES.md
Domain models	/DOMAIN_MODEL_*.md
Bounded contexts	/BOUNDED_CONTEXT_MAP.md
This doc	/BACKLOG_QUICK_REFERENCE.md

---

Using This Backlog

For Project Managers

• Use Phase breakdown for milestones
• Critical path shows minimum scope
• Dependency graph prevents sequencing errors

For Engineers

• Each issue has acceptance criteria
• DDD guidance explains domain concepts
• Dependencies prevent blocking work
• Start with Phase 1 for foundation

For Architects

• Capability map shows user value
• Bounded contexts explain isolation
• Feature sets show vertical slices
• Domain models guide implementation

---

Common Questions

Q: Can phases be parallelized? A: Partially. Phase 1 must complete first. Phases 2-3 can overlap after Phase 1. Phase 4 can be delayed.

Q: What if we skip Phase 3 (clustering)? A: Possible. You get event sourcing, local pub/sub, namespaces. But distributed actors won't work. Phase 1 + 2 + 4 is a valid product.

Q: What's the hardest phase? A: Phase 3 (clustering). Requires multi-node tests, distributed algorithms, failure scenarios. Phase 1 is foundational but not complex.

Q: Can we deliver value incrementally? A: Yes. After Phase 1: "Event sourcing with OCC". After Phase 2: "Local pub/sub". After Phase 3: "Distributed cluster". After Phase 4: "Multi-tenant NATS".

Q: Which issues are P0 vs P1? A: P0 = blocking (no alternative); P1 = important (ship without, but limited); P2 = nice-to-have (polish, observability). Focus on P0 first.

---

Metrics to Track

• Velocity: Issues per sprint (size estimates TBD)
• Burndown: Phase completion vs planned
• Quality: Test coverage per phase
• Risk: Dependency blocking (red flag)

---

Related Skills

• /issue-writing - Create Gitea issues from this backlog
• /spawn-issues - Parallelize implementation with worktrees
• /product-strategy - Decompose vision to work (meta-skill used here)
• /ddd - Domain-driven design concepts and patterns

---

Questions?

Refer to:

• Full backlog: /BACKLOG.md
• Domain models: /DOMAIN_MODEL_*.md
• Capabilities: /CAPABILITIES.md
• Vision: /vision.md
• Product strategy: /STRATEGY_CHAIN.md