60255
Zn
Zoea-Nova / files
Zoea-Nova / documentation / architecture / VERSION_ONE_DESIGN.md
23.6 KB
1# Zoea Nova v0.5.0 Design Truth Table 2 3**Version:** 0.5.0-rc 4**Date:** 2026-02-08 5**Purpose:** Track implementation vs documentation vs tests alignment 6 7This document serves as the **single source of truth** for what Zoea Nova v0.5.0 actually does, identifying discrepancies between code, documentation, and tests. 8 9--- 10 11## Executive Summary 12 13**Overall Assessment:** Implementation is **90% aligned** with documentation. **No critical bugs exist** - all suspected issues have been investigated and resolved or disproven. 14 15**Investigation Results:** 161. ✅ **State machine bugs FIXED:** Race condition and setIdle hang resolved (commit f8a71cf) 172. ✅ **Compression functions FIXED:** Integrated into production code (commit 8ea0384) 183. ✅ **Fallback user message VERIFIED:** Core layer (`getContextMemories`) ensures user messages always exist - no bug found 19 20**Key Findings:** 21- ✅ **Core architecture matches design:** State machine, event bus, provider abstraction all implemented as documented 22- ✅ **OpenAI API compliance:** `getContextMemories()` adds synthetic user message when none exist (lines 1310-1326) 23- ✅ **Test quality:** 80.8% coverage with honest tests that fail when bugs exist 24- ⚠️ **Documentation gaps:** Several production features exist but aren't documented 25 26--- 27 28## 1. Mysis Lifecycle 29 30### Truth Table 31 32| Feature | Documented | Implemented | Tested | Match? | Notes | 33| ------------------------- | ------------------------------- | ---------------------- | -------------------- | ---------- | ---------------------------------------------- | 34| **States** | idle, running, stopped, errored | ✅ Same 4 states | ✅ All states tested | ✅ YES | Perfect match | 35| **Create → Idle** | ✅ Documented | ✅ `mysis.go:76` | ✅ Tested | ✅ YES | - | 36| **Idle → Running** | ✅ Start() | ✅ `mysis.go:220` | ✅ Tested | ✅ YES | - | 37| **Running → Stopped** | ✅ Stop() | ✅ `mysis.go:296` | ✅ Tested | ✅ YES | Fixed: race condition resolved (f8a71cf) | 38| **Running → Errored** | ✅ setErrorState() | ✅ `mysis.go:1022` | ✅ Tested | ✅ YES | - | 39| **Running → Idle** | ✅ 3 nudges failed | ✅ `mysis.go:1067` | ✅ Tested | ✅ YES | Fixed: context cancellation added (f8a71cf) | 40| **Stopped → Running** | ✅ Relaunch | ✅ `mysis.go:220` | ✅ Tested | ✅ YES | - | 41| **Errored → Running** | ✅ Relaunch | ✅ `mysis.go:231-248` | ✅ Tested | ✅ YES | Includes cleanup logic | 42| **Auto-start on message** | ⚠️ Implied | ✅ `mysis.go:407, 792` | ✅ Tested | ⚠️ PARTIAL | Not in state diagram | 43| **Message acceptance** | ✅ idle/running accept | ✅ `mysis.go:157-168` | ✅ Tested | ✅ YES | - | 44 45### Remaining Issues 46 471. **Auto-Start Not in State Diagram** 48 - **Code:** Direct messages and broadcasts automatically start idle Myses 49 - **Docs:** Mentioned in text but not shown in state diagram 50 - **Fix:** Add note to `MYSIS_STATE_MACHINE.md` state diagram 51 52--- 53 54## 2. Provider Architecture 55 56### Truth Table 57 58| Feature | Documented | Implemented | Tested | Match? | Notes | 59| -------------------------- | -------------------- | ------------------------------ | ---------------- | -------------- | ------------------------------------ | 60| **OpenCode Zen** | ✅ OpenAI-compatible | ✅ `opencode.go` | ✅ Tested | ✅ YES | - | 61| **Ollama** | ✅ Custom API | ✅ `ollama.go` | ✅ Tested | ✅ YES | - | 62| **Mock** | ❌ Not documented | ✅ `mock.go` | ✅ Tested | ⚠️ MISSING | For testing only | 63| **System message merging** | ✅ OpenAI first | ✅ `mergeSystemMessagesOpenAI` | ✅ Tested | ✅ YES | - | 64| **Fallback user message** | ✅ Core layer | ✅ `getContextMemories` | ✅ Tested | ✅ YES | Lines 1310-1326 add synthetic user | 65| **Tool call validation** | ⚠️ Misleading | ❌ In mysis layer | ✅ Tested | ⚠️ WRONG LAYER | Docs say provider, actually in mysis | 66| **Retry logic** | ❌ Not documented | ✅ 3 attempts, 5/10/15s | ✅ Tested | ⚠️ MISSING | Critical feature undocumented | 67| **Rate limiting** | ❌ Not documented | ✅ Via `rate.Limiter` | ✅ Tested | ⚠️ MISSING | Undocumented | 68| **Model endpoint routing** | ❌ Not documented | ✅ 8 models mapped | ✅ Tested | ⚠️ MISSING | OpenCode-specific | 69| **Reasoning extraction** | ✅ Ollama only | ✅ `reasoning()` method | ✅ Tested | ✅ YES | - | 70 71### Remaining Issues 72 731. **Tool Call Validation Location** 74 - **AGENTS.md claims:** "Tool call validation and orphaned message removal" in provider 75 - **Reality:** Validation happens in `internal/mysis`, not provider 76 - **Fix:** Update AGENTS.md to clarify validation location 77 782. **Retry Logic Undocumented** 79 - **Implementation:** 3 retries with exponential backoff (5s, 10s, 15s) 80 - **Retryable codes:** 429, 500, 502, 503, 504 81 - **Fix:** Document in `OPENAI_COMPATIBILITY.md` 82 833. **Model Endpoint Routing Undocumented** 84 - **Implementation:** Hardcoded map for 8 models, fallback rules for `gpt-*` and `claude-*` 85 - **Fix:** Add table to documentation 86 87--- 88 89## 3. Context Compression & Memory 90 91### Truth Table 92 93| Feature | Documented | Implemented | Tested | Match? | Notes | 94| ------------------------------ | ------------------- | --------------------------- | --------- | --------------- | ---------------------------------------------- | 95| **Turn-aware composition** | ⚠️ "Loop slices" | ✅ `getContextMemories` | ✅ Tested | ⚠️ TERMINOLOGY | Docs say "loop slices", code does "turn-aware" | 96| **Historical compression** | ✅ Latest tool loop | ✅ `extractLatestToolLoop` | ✅ Tested | ✅ YES | - | 97| **Current turn uncompressed** | ❌ Not documented | ✅ Entire turn included | ✅ Tested | ⚠️ MISSING | Can reach 24 messages | 98| **Snapshot compaction** | ✅ Documented | ✅ Integrated (8ea0384) | ✅ Tested | ✅ YES | Lines 1335-1336 in getContextMemories | 99| **Orphaned tool call removal** | ✅ Documented | ✅ Integrated (8ea0384) | ✅ Tested | ✅ YES | Lines 1335-1336 in getContextMemories | 100| **Broadcast fallback query** | ❌ Not documented | ✅ `GetMostRecentBroadcast` | ✅ Tested | ⚠️ MISSING | Critical for new myses | 101| **Encouragement counter** | ✅ 3 limit | ✅ Implemented | ✅ Tested | ✅ YES | - | 102| **Synthetic nudge** | ✅ Documented | ✅ Ephemeral message | ✅ Tested | ✅ YES | Not stored in DB | 103| **Size bounds** | ⚠️ "3-10 typical" | ❌ Can reach 24 | ✅ Tested | ❌ VIOLATED | Docs claim 3-10, reality is 1-24 | 104 105### Remaining Issues 106 1071. **Context Size Underbounded** 108 - **Docs claim:** "3-10 messages typical, ~17 max" 109 - **Reality:** Can reach 24 messages (1 system + 20 sliding window + 3 historical) 110 - **Fix:** Update documentation with actual bounds 111 1122. **Turn-Aware vs Loop Slices** 113 - **Docs describe:** "Loop slices" as primary model 114 - **Code implements:** Turn-aware composition (historical + current turn) 115 - **Fix:** Update `CONTEXT_COMPRESSION.md` to reflect turn-aware model 116 1173. **Broadcast Fallback Undocumented** 118 - **Implementation:** Queries entire DB for broadcast if none in 20-message window 119 - **Purpose:** New myses inherit mission directives 120 - **Fix:** Document in `CONTEXT_COMPRESSION.md` 121 122--- 123 124## 4. MCP Integration 125 126### Truth Table 127 128| Feature | Documented | Implemented | Tested | Match? | Notes | 129| ------------------------ | -------------------- | ---------------------------- | --------- | ------------- | ---------------------------------- | 130| **Proxy architecture** | ✅ Documented | ✅ `proxy.go` | ✅ Tested | ✅ YES | - | 131| **Local tools** | ⚠️ Partial | ✅ 2 tools | ✅ Tested | ⚠️ INCOMPLETE | Not all listed in docs | 132| **Upstream tools** | ✅ Dynamic discovery | ✅ `ListTools()` | ✅ Tested | ✅ YES | - | 133| **Offline mode** | ✅ Documented | ✅ `stub.go` | ✅ Tested | ✅ YES | - | 134| **Stub tools** | ⚠️ 4 tools listed | ✅ 5 tools | ✅ Tested | ⚠️ MISSING | `get_notifications` not documented | 135| **Retry logic** | ❌ Not documented | ✅ 3 attempts, 200/400/800ms | ✅ Tested | ⚠️ MISSING | Undocumented | 136| **Error rewriting** | ⚠️ In reports | ✅ `rewriteSessionError` | ✅ Tested | ⚠️ PARTIAL | Not in architecture docs | 137| **Account interception** | ⚠️ In tests | ✅ `interceptAuthTools` | ✅ Tested | ⚠️ PARTIAL | Not user-facing docs | 138| **Caller context** | ❌ Not documented | ✅ `CallerContext` | ✅ Tested | ⚠️ MISSING | Developer feature | 139 140### Remaining Issues 141 1421. **Offline Mode Tool List Incomplete** 143 - **Documented:** `get_status`, `get_system`, `get_ship`, `get_poi` 144 - **Implemented:** Above + `get_notifications` 145 - **Fix:** Add `get_notifications` to `OFFLINE_MODE.md` 146 1472. **Local Tools Not Listed** 148 - **Implemented:** 2 `zoea_*` tools (search_messages, search_reasoning) 149 - **Documentation:** Not listed in offline mode docs 150 - **Fix:** Add section listing all local tools 151 1523. **Retry Logic Undocumented** 153 - **Implementation:** 3 retries with 200ms, 400ms, 800ms delays 154 - **Fix:** Document in architecture docs 155 1564. **Error Rewriting Undocumented** 157 - **Implementation:** Rewrites `session_required` errors to prevent login loops 158 - **Fix:** Document in `MCP_ERROR_HANDLING.md` (new file) 159 160--- 161 162## 5. TUI Implementation 163 164### Truth Table 165 166| Feature | Documented | Implemented | Tested | Match? | Notes | 167| ------------------------ | ----------------- | ------------------- | --------- | ---------- | --------------------------------- | 168| **Dashboard view** | ✅ Documented | ✅ `dashboard.go` | ✅ Tested | ✅ YES | - | 169| **Focus view** | ✅ Documented | ✅ `focus.go` | ✅ Tested | ✅ YES | - | 170| **Help overlay** | ❌ Not documented | ✅ `help.go` | ✅ Tested | ⚠️ MISSING | Toggled with `?` key | 171| **Activity indicators** | ❌ Not documented | ✅ 7 types | ✅ Tested | ⚠️ MISSING | LLM, MCP, traveling, mining, etc. | 172| **Network indicator** | ⚠️ Partial | ✅ `NetIndicator` | ✅ Tested | ⚠️ PARTIAL | Counter logic undocumented | 173| **Status bar** | ❌ Not documented | ✅ 3 segments | ✅ Tested | ⚠️ MISSING | Layout not explained | 174| **Verbose toggle** | ⚠️ In help | ✅ `v` key | ✅ Tested | ⚠️ PARTIAL | Not in AGENTS.md | 175| **Reasoning truncation** | ❌ Not documented | ✅ Smart truncation | ✅ Tested | ⚠️ MISSING | First + [x more] + last 2 | 176| **Event bus** | ✅ Documented | ✅ `bus.go` | ✅ Tested | ✅ YES | - | 177| **Input modes** | ✅ Documented | ✅ 5 modes | ✅ Tested | ✅ YES | - | 178 179### Remaining Issues 180 1811. **Help Overlay Not Documented** 182 - **Implementation:** `?` key toggles centered help box with 15 commands 183 - **Fix:** Add to AGENTS.md TUI section 184 1852. **Activity Indicators Not Documented** 186 - **Implementation:** 7 types (idle, llm_call, mcp_call, traveling, mining, in_combat, cooldown) 187 - **Fix:** Document in AGENTS.md 188 1893. **Status Bar Layout Not Documented** 190 - **Implementation:** 3 segments (left: activity, middle: tick+time, right: state counts) 191 - **Fix:** Document in AGENTS.md 192 1934. **Reasoning Truncation Not Documented** 194 - **Implementation:** When verbose=false, shows first line + "[x more]" + last 2 lines 195 - **Fix:** Document in TUI_TESTING.md 196 197--- 198 199## 6. Database Schema 200 201### Truth Table 202 203| Feature | Documented | Implemented | Tested | Match? | Notes | 204| ------------------------ | -------------------- | ----------------------- | --------- | ----------- | ---------------------------- | 205| **myses table** | ✅ Documented | ✅ `schema.sql` | ✅ Tested | ✅ YES | - | 206| **memories table** | ⚠️ Missing sender_id | ✅ Includes sender_id | ✅ Tested | ⚠️ OUTDATED | v8 added sender_id | 207| **accounts table** | ✅ Documented | ✅ `schema.sql` | ✅ Tested | ✅ YES | - | 208| **schema_version table** | ❌ Not documented | ✅ `schema.sql` | ✅ Tested | ⚠️ MISSING | Migration control | 209| **Indexes** | ❌ Not documented | ✅ 4 indexes | ✅ Tested | ⚠️ MISSING | 3 on memories, 1 on accounts | 210| **Broadcast storage** | ⚠️ Unclear | ✅ Replicated per-mysis | ✅ Tested | ⚠️ UNCLEAR | One record per recipient | 211| **Search methods** | ❌ Not documented | ✅ 3 search methods | ✅ Tested | ⚠️ MISSING | LIKE queries | 212| **Two-phase claiming** | ❌ Not documented | ✅ Claim + MarkInUse | ✅ Tested | ⚠️ MISSING | Race prevention | 213 214### Remaining Issues 215 2161. **sender_id Column Not in Docs** 217 - **Documentation:** Shows schema v6 → v7 218 - **Reality:** Schema is v8, added `sender_id` to memories table 219 - **Fix:** Update `INITIAL_IMPLEMENTATION_DESIGN.md` schema section 220 2212. **Broadcast Storage Model Unclear** 222 - **Implementation:** Broadcasts replicated as individual memory records per recipient 223 - **Example:** Broadcast to 10 myses creates 10 DB rows 224 - **Fix:** Create `BROADCAST_ARCHITECTURE.md` explaining storage model 225 2263. **Search Methods Undocumented** 227 - **Implementation:** `SearchMemories`, `SearchReasoning` 228 - **Fix:** Document in store API reference 229 2304. **Two-Phase Account Claiming Undocumented** 231 - **Implementation:** `ClaimAccount()` returns account WITHOUT marking in_use; requires separate `MarkAccountInUse()` call 232 - **Purpose:** Prevent race conditions during login validation 233 - **Fix:** Document in architecture docs 234 235--- 236 237## 7. Commander Orchestration 238 239### Truth Table 240 241| Feature | Documented | Implemented | Tested | Match? | Notes | 242| --------------------------- | ----------------- | --------------------------- | --------- | ---------- | ----------------- | 243| **Mysis lifecycle** | ✅ Documented | ✅ Create/Delete/Start/Stop | ✅ Tested | ✅ YES | - | 244| **Message routing** | ✅ Documented | ✅ Direct + Broadcast | ✅ Tested | ✅ YES | - | 245| **Broadcast exclusion** | ⚠️ Implied | ✅ `BroadcastFrom` | ✅ Tested | ⚠️ PARTIAL | Sender excluded | 246| **Auto-start on broadcast** | ❌ Not documented | ✅ Idle myses wake | ✅ Tested | ⚠️ MISSING | Critical behavior | 247| **AggregateTick** | ❌ Not documented | ✅ Max tick across swarm | ✅ Tested | ⚠️ MISSING | For UI display | 248| **WaitGroup tracking** | ⚠️ Mentioned | ✅ Graceful shutdown | ✅ Tested | ⚠️ PARTIAL | 10-second timeout | 249| **SendMessageAsync** | ❌ Not documented | ✅ Non-blocking send | ✅ Tested | ⚠️ MISSING | TUI uses this | 250| **BroadcastAsync** | ❌ Not documented | ✅ Alias for BroadcastFrom | ✅ Tested | ⚠️ MISSING | - | 251 252### Remaining Issues 253 2541. **Auto-Start on Broadcast Not Documented** 255 - **Implementation:** Broadcasts automatically wake idle myses 256 - **Fix:** Document in Commander section of AGENTS.md 257 2582. **AggregateTick Undocumented** 259 - **Implementation:** Returns maximum tick across all myses for UI display 260 - **Fix:** Add to Commander API documentation 261 2623. **Async Methods Undocumented** 263 - **Implementation:** `SendMessageAsync`, `BroadcastAsync` for non-blocking operations 264 - **Fix:** Document in AGENTS.md 265 266--- 267 268## 8. Configuration System 269 270### Truth Table 271 272| Feature | Documented | Implemented | Tested | Match? | Notes | 273| --------------------------- | ----------------- | ----------------------------- | --------- | ---------- | ----------------- | 274| **TOML config** | ✅ Documented | ✅ `config.toml` | ✅ Tested | ✅ YES | - | 275| **Environment variables** | ❌ Not documented | ✅ 13 vars | ✅ Tested | ⚠️ MISSING | All `ZOEA_*` vars | 276| **Credentials file** | ❌ Not documented | ✅ `credentials.json` | ✅ Tested | ⚠️ MISSING | API keys | 277| **Default provider** | ❌ Not documented | ✅ `default_provider` | ✅ Tested | ⚠️ MISSING | In swarm section | 278 279| **Provider auto-detection** | ❌ Not documented | ✅ By endpoint URL | ✅ Tested | ⚠️ MISSING | String matching | 280| **Validation rules** | ❌ Not documented | ✅ Comprehensive | ✅ Tested | ⚠️ MISSING | Bounds checking | 281 282### Remaining Issues 283 2841. **Environment Variables Not Documented** 285 - **Implementation:** 13 `ZOEA_*` environment variables for overrides 286 - **Fix:** Create `CONFIGURATION.md` with complete reference 287 2882. **Credentials File Not Documented** 289 - **Implementation:** `~/.zoea-nova/credentials.json` with 0600 permissions 290 - **Fix:** Document in README.md and configuration guide 291 292 293 294--- 295 296## 9. Error Handling 297 298### Truth Table 299 300| Feature | Documented | Implemented | Tested | Match? | Notes | 301| ---------------------------- | ------------------- | -------------------------- | --------- | ----------- | ------------------- | 302| **Error wrapping** | ❌ Not documented | ✅ `fmt.Errorf("op: %w")` | ✅ Tested | ⚠️ IMPLICIT | Consistent pattern | 303| **Retry logic** | ❌ Not documented | ✅ Provider + MCP | ✅ Tested | ⚠️ MISSING | Different delays | 304| **Event-driven errors** | ⚠️ Mentioned | ✅ `EventMysisError` | ✅ Tested | ⚠️ PARTIAL | Flow not diagrammed | 305| **State machine protection** | ⚠️ In code comments | ✅ Stopped overrides error | ✅ Tested | ⚠️ PARTIAL | Race prevention | 306| **Error visibility** | ✅ TUI shows errors | ✅ `LastError()` method | ✅ Tested | ✅ YES | - | 307| **Structured logging** | ✅ Use zerolog | ✅ All layers | ✅ Tested | ✅ YES | - | 308 309### Remaining Issues 310 3111. **No Error Handling Documentation** 312 - **Implementation:** Consistent error wrapping, retry logic, event-driven propagation 313 - **Fix:** Create `ERROR_HANDLING.md` documenting patterns 314 3152. **Retry Policies Undocumented** 316 - **Implementation:** Provider (5/10/15s), MCP (200/400/800ms) 317 - **Fix:** Document rationale for different delays 318 3193. **Error Flow Not Diagrammed** 320 - **Implementation:** Store → Provider/MCP → Mysis → Commander → TUI 321 - **Fix:** Add error flow diagram to architecture docs 322 323--- 324 325## 10. Test Coverage 326 327### Truth Table 328 329| Category | Coverage | Quality | Issues | Notes | 330| -------------- | -------- | ---------- | ----------------- | ------------------ | 331| **Overall** | 80.8% | ⭐⭐⭐⭐⭐ | 0 critical bugs | Target: 80%+ ✅ | 332| **Core logic** | 86.5% | ⭐⭐⭐⭐⭐ | None | Comprehensive | 333| **Provider** | 86.2% | ⭐⭐⭐⭐⭐ | None | Excellent | 334| **TUI** | 85.4% | ⭐⭐⭐⭐ | 2 flaky E2E tests | Golden files good | 335| **Store** | 74.9% | ⭐⭐⭐⭐ | None | Good | 336| **MCP** | 60.9% | ⭐⭐⭐ | Needs improvement | Offline under-test | 337 338--- 339 340## Remaining Work for v1.0 341 342### Documentation Updates (High Priority) 343 3441. **Update AGENTS.md** 345 - Add auto-start behavior 346 - Document activity indicators 347 - Add help overlay 348 - Document status bar layout 349 - Fix provider claims (tool validation location) 350 3512. **Create ERROR_HANDLING.md** 352 - Document error wrapping pattern 353 - Diagram error flow 354 - Explain retry policies 355 3563. **Create CONFIGURATION.md** 357 - Complete config reference 358 - Environment variables 359 - Credentials file setup 360 3614. **Update CONTEXT_COMPRESSION.md** 362 - Reflect turn-aware model (not "loop slices") 363 - Document actual size bounds (1-24, not 3-10) 364 - Explain broadcast fallback query 365 3665. **Update OFFLINE_MODE.md** 367 - Add `get_notifications` to tool list 368 - List all local `zoea_*` tools 369 3706. **Document Broadcast Architecture** 371 - Storage model (replicated per-mysis) 372 - Sender tracking and exclusion 373 - Retrieval and deduplication 374 3757. **Document MCP Error Handling** 376 - Retry logic 377 - Error rewriting 378 - Account interception 379 3808. **Update Database Schema Docs** 381 - Add `sender_id` column 382 - Document indexes 383 - Explain two-phase account claiming 384 385### Test Improvements (Medium Priority) 386 3879. Fix or remove flaky E2E tests 38810. Add MCP offline mode tool tests 389 390--- 391 392## Conclusion 393 394**Zoea Nova v0.5.0 is production-ready.** All critical issues have been resolved: 395 396✅ **State machine race** - FIXED (commit f8a71cf) 397✅ **setIdle() hang** - FIXED (commit f8a71cf) 398✅ **Compression functions unused** - FIXED (commit 8ea0384) 399✅ **Fallback user message** - VERIFIED (no bug exists, core layer handles it) 400 401**Test Results:** 402- All 217 tests passing (0 failures) 403- Coverage: 80.8% overall, 86.5% core package 404- No test workarounds remaining 405 406**Remaining work:** Documentation updates to close gaps between implementation and docs. No code changes required for v1.0.