# Maven Ecosystem Architecture ## 1. Purpose This document defines Maven's role in the local ecosystem formed by: - **Maven** — conversational control center and personal assistant - **Nexus** — canonical identity and relationship service - **Praxis** — operational state and attention service - **Hexis** — capability registry and controlled execution service The design keeps Maven useful without turning it into the owner of every concern. The core rule is: ```text Nexus identifies. Praxis observes. Hexis acts. Maven understands and coordinates. ``` Maven is the user-facing control center, but not the source of truth for identities, operational state, or execution. --- ## 2. Maven's role Maven provides the human interface over the other systems. It is responsible for: - interpreting Russian and English utterances - deciding whether the user wants information, memory access, or an action - assembling relevant world-state context - querying Praxis for operational attention - resolving references through Nexus - discovering and invoking capabilities through Hexis - managing conversational clarification and confirmation - phrasing structured results naturally - exposing the same state through voice, Telegram, web, and other supported channels - retaining personal memory, reminders, and conversational history Maven is not responsible for: - owning canonical identities - ingesting every external notification directly - monitoring all infrastructure and agent sessions itself - storing execution definitions - executing arbitrary commands - deciding that an attention item should trigger an action automatically - sharing databases with Nexus, Praxis, or Hexis - treating LLM output as authorization --- ## 3. Existing Maven architecture Maven remains a set of Go daemons connected through Unix sockets. | Binary | Role | |---|---| | `mavend` | Core router, phraser, memory, reminders, digestion, integrations, and IPC owner | | `mavweb` | HTTP UI and PWA | | `mavsttd` | Speech-to-text through whisper.cpp | | `mavttsd` | Text-to-speech through Piper | | `mavwaked` | Wake-word and VAD gate | | `mavenclient` | Voice interaction loop | | `mavpoll` | Telegram reach | | `mavcaldav` | CalDAV synchronization | The resident Qwen3-1.7B model remains bounded to: - structured routing - concise natural-language phrasing - bounded digestion synthesis It does not directly query databases or execute external operations. --- ## 4. Ecosystem topology ```text user voice / web / Telegram / text | v +------------------+ | Maven | | conversation and | | coordination | +--------+---------+ | +----------------+----------------+ | | | v v v +-------------+ +-------------+ +-------------+ | Nexus | | Praxis | | Hexis | | identity | | operational | | capabilities| | relations | | attention | | execution | +-------------+ +-------------+ +-------------+ ^ ^ | | | | +----------------+----------------+ shared canonical entity IDs ``` Maven talks to each service through a versioned client contract. No component reads another component's SQLite database. --- ## 5. Core interaction model A Maven turn follows this shape: ```text utterance -> stage-0 deterministic fast path -> world-state snapshot -> router -> reference resolution -> information query or capability discovery -> confirmation when required -> execution or response -> phrasing -> delivery -> trace ``` Expanded: ```text 1. receive utterance 2. normalize text and collect channel metadata 3. build bounded world-state context 4. route into a structured intent 5. resolve referenced entities through Nexus 6. query Praxis or Hexis as required 7. stop and clarify on ambiguity 8. request explicit confirmation for protected actions 9. execute through Hexis when authorized 10. phrase the structured result 11. deliver through the originating or selected channel 12. record a complete trace ``` --- ## 6. Maven and Nexus ### 6.1 Purpose Maven uses Nexus whenever an utterance refers to a real entity: - project - repository - device - service - application - person - pet - location - agent session - household object - external task project Examples: ```text "correx" "the correx repository" "коррекс" ``` All may resolve to the same canonical entity. ### 6.2 Resolution flow ```text utterance -> Maven extracts reference text and expected entity types -> Nexus resolves candidates -> Maven receives resolved / ambiguous / not_found ``` Resolved: ```json { "status": "resolved", "entity_id": "ent_correx", "entity_type": "project.software", "display_name": "Correx" } ``` Ambiguous: ```json { "status": "ambiguous", "candidates": [ {"entity_id": "ent_muzick_indexer", "label": "Muzick indexer"}, {"entity_id": "ent_manga_indexer", "label": "Manga indexer"} ] } ``` Maven must ask for clarification instead of choosing silently. ### 6.3 Rules - canonical entity IDs are used in all downstream calls - free-text names must not reach mutating Hexis operations - low-confidence mappings may be shown as suggestions but not used for mutation - Maven may submit user-confirmed alias or mapping feedback to Nexus - Maven must not create entities automatically unless the operation is explicit - entity display names are presentation data, not authorization data --- ## 7. Maven and Praxis ### 7.1 Purpose Praxis gives Maven a normalized view of external operational state. Examples: - coding agent waiting for input - coding agent failed - service degraded - notification still unresolved - task or project item requiring attention - source integration stale - required routine item not completed - execution succeeded but recovery not yet observed Maven asks Praxis questions such as: ```text what needs attention? what changed since this morning? what is unresolved for Correx? which agent is waiting? what happened after the restart? ``` ### 7.2 Query contract Recommended Maven-facing operations: ```text praxis.list_attention praxis.list_changes praxis.list_items praxis.get_item praxis.search praxis.acknowledge praxis.resolve praxis.ignore praxis.pin praxis.list_item_capabilities praxis.list_item_executions ``` These may be exposed through a native API client or a compact internal tool abstraction. ### 7.3 Item lifecycle Maven must preserve Praxis semantics: ```text surfaced != acknowledged acknowledged != resolved execution_succeeded != recovered stale != resolved ignored != deleted ``` Examples: - reading an item aloud marks it surfaced, not acknowledged - the user saying "got it" may acknowledge it - the user saying "done" may resolve it - a successful restart command does not resolve a service failure - a later healthy observation may resolve it ### 7.4 Digestion integration Maven's digestion worker may query Praxis for: - newly unresolved attention - repeated operational patterns - items surfaced but never acknowledged - failed sources affecting visibility - recently recovered items Digestion may propose or summarize. It must not invoke Hexis automatically. --- ## 8. Maven and Hexis ### 8.1 Purpose Hexis exposes controlled capabilities. Examples: - inspect service status - restart a registered service - inspect logs - query repository state - trigger a local application operation - perform a predefined filesystem action - invoke a registered HTTP API action Hexis exposes: - native API - CLI - MCP adapter Maven should normally use the native API or a typed local client. The MCP adapter exists primarily for coding agents and other MCP clients. ### 8.2 Capability flow ```text Maven -> resolve target through Nexus -> ask Hexis for capabilities applicable to entity -> select capability from router output or deterministic mapping -> validate arguments -> request confirmation when required -> execute through Hexis -> receive structured result -> phrase result ``` ### 8.3 Execution rules Maven must not: - generate shell commands for Hexis - bypass capability schemas - submit arbitrary target strings for mutating operations - interpret a successful command as operational recovery - retry unknown mutation outcomes automatically - treat MCP tool availability as permission ### 8.4 Confirmation Confirmation is bound to: - capability ID and version - canonical target entity - normalized arguments - requester identity - risk - expiry Conversation state stores the pending confirmation. Example: ```text User: restart the Muzick indexer. Maven: the restart affects Muzick indexer on homesrv. proceed? User: yes. ``` The final `yes` is accepted only when a valid pending confirmation exists. --- ## 9. Maven as control center Maven is a control center in the human-interface sense. It provides one place to: - ask what is happening - inspect attention - identify affected systems - request safe actions - understand results - move between voice, Telegram, and web - access personal memory and reminders It is not a central orchestrator in the infrastructure sense. The other services remain independently usable: - Nexus through API and CLI - Praxis through API, CLI, and web - Hexis through API, CLI, and MCP If Maven is down: - identities remain available - observations continue - attention state remains visible - Hexis capabilities remain callable by authorized clients --- ## 10. Maven internal packages Recommended additions or extensions: ```text pkg/ context/ snapshot.go providers.go nexus.go praxis.go hexis.go integrations/ nexus/ praxis/ hexis/ dialogue/ pending_reference.go pending_confirmation.go continuation.go tools/ nexus_tools.go praxis_tools.go hexis_tools.go trace/ external_call.go entity_resolution.go execution.go ``` The exact package layout may follow existing repository conventions. ### 10.1 Context providers Each external service contributes a bounded context fragment. ```go type Provider interface { Name() string Collect(ctx context.Context) (Fragment, error) } ``` Fragments include: - freshness - source - compact structured content - degradation state - token-budget estimate External service failure must not break a turn. ### 10.2 Typed clients Each integration uses a typed client with: - Unix socket and optional HTTP transport - context cancellation - strict deadlines - version negotiation - typed errors - bounded retries for safe reads - no automatic retries for uncertain mutations - correlation IDs --- ## 11. Router contract The resident model emits a fixed structured action. Conceptual shape: ```json { "tool": "praxis.list_attention", "args": { "entity_id": "ent_correx" }, "escalate": false } ``` or: ```json { "tool": "hexis.execute", "args": { "capability_id": "cap_service_restart_muzick", "target_entity_id": "ent_muzick_indexer", "arguments": {} }, "escalate": false } ``` Rules: - tool names are versioned - exposed tool schemas are compact - only relevant tools are placed in router context - canonical entity IDs are injected after deterministic resolution where possible - the model does not authorize execution - all arguments are validated by the receiving system - malformed output falls back to the deterministic classifier path --- ## 12. World-state snapshot Every route receives one immutable snapshot. Example: ```go type Snapshot struct { CapturedAt time.Time Time TimeContext Presence PresenceContext Calendar CalendarContext Attention PraxisContext Entities NexusContext Actions HexisContext Degraded []DependencyFailure } ``` The snapshot must remain small. It should contain summaries such as: ```text Praxis: - 2 high-attention items - Correx agent waiting - Maven calendar source stale Hexis: - 4 applicable read capabilities - 1 mutating capability unavailable Nexus: - current project resolved as Correx ``` Full data is fetched only after routing selects a relevant tool. --- ## 13. Trace design Maven's `/trace` must include cross-system calls. A turn trace records: ```text input received stage-0 decision world-state snapshot router prompt contract version router output Nexus resolution request and result Praxis query and result references Hexis capability discovery confirmation proposal Hexis execution ID phrasing input and output delivery result ``` Required fields: - turn ID - correlation ID - causation ID - service - operation - duration - status - contract version - redacted request summary - redacted response summary - fallback reason - error code Raw secrets, credentials, and unbounded payloads must never enter trace storage. --- ## 14. Failure handling ### Nexus unavailable Maven may: - answer using already verified entity IDs in current context - query Praxis by direct item ID - inspect existing pending confirmations Maven must not: - resolve new free-text action targets - execute mutations against unresolved targets - invent mappings ### Praxis unavailable Maven may: - continue personal memory, reminders, calendar, and direct Hexis operations - explain that operational attention is unavailable It must not claim that there is nothing requiring attention. ### Hexis unavailable Maven may: - inspect Praxis - describe the action that would be applicable - report that execution is unavailable It must not queue speculative mutating actions. ### Partial failure The response should distinguish known state from unavailable state. Example: ```text Muzick indexer is marked failed in Praxis. Hexis is unavailable, so I cannot inspect or restart it right now. ``` --- ## 15. Security model Maven is not trusted to authorize itself. Security boundaries: - Nexus authoritatively resolves identities - Hexis authoritatively validates and executes capabilities - Praxis authoritatively owns operational lifecycle - Maven owns conversation and user intent Requirements: - separate service credentials - Unix sockets by default - authenticated HTTP when used - no browser-visible Nexus or Hexis credentials - no direct database access - no arbitrary command transport - no execution based solely on LLM output - no automatic attention-to-action chain - explicit user confirmation for protected actions - requester identity propagated to Hexis - all cross-service requests carry correlation IDs - all contracts are versioned --- ## 16. Web UI role `mavweb` becomes the conversational control surface, not a replacement for the administrative UIs of the sibling systems. Recommended additions: ### `/dash` - compact Praxis attention summary - degraded dependency summary - active confirmations - recent Hexis executions - relevant personal reminders ### `/history` - Maven conversation history - linked Praxis items and Hexis executions ### `/trace` - full cross-service turn trace ### `/notifications` - Maven delivery and reach state - references to Praxis items where applicable ### `/tools` - compact user-facing view of relevant Hexis capabilities - capability availability - risk - canonical target - no raw command definitions Administrative identity editing should remain in Nexus or Praxis administration. Provider and capability registration should remain in Hexis administration. --- ## 17. Example scenarios ### 17.1 Morning summary 1. Maven digestion queries Praxis. 2. Praxis returns: - Correx agent waiting - Muzick agent failed - calendar source stale 3. Maven adds personal reminders and calendar state. 4. Maven phrases one bounded summary. 5. Included Praxis items are marked surfaced. 6. They are not automatically acknowledged. ### 17.2 Inspect waiting agent ```text User: what is Correx waiting for? ``` 1. Nexus resolves `Correx`. 2. Praxis finds the waiting agent item for that project. 3. Maven reads the bounded terminal evidence. 4. Maven phrases the exact question. 5. Hexis is not involved. ### 17.3 Restart service ```text User: restart the Muzick indexer. ``` 1. Nexus resolves the service. 2. Hexis returns applicable restart capability. 3. Maven requests confirmation according to risk. 4. User confirms. 5. Hexis executes. 6. Maven reports command success. 7. Praxis waits for independent recovery. 8. Maven later reports whether recovery occurred. ### 17.4 Ambiguous target ```text User: restart the indexer. ``` 1. Nexus returns Muzick and Manga indexers. 2. Maven asks which one. 3. No Hexis execution request is created. ### 17.5 Dependency outage ```text User: what needs attention? ``` Praxis is unavailable. Maven responds that operational attention cannot currently be read, while still reporting personal reminders and local Maven state. --- ## 18. Implementation phases ### Phase 1 — Read-only integration - typed Nexus client - typed Praxis client - typed Hexis client - world-state provider framework - trace integration - read-only Maven tools: - resolve entity - list attention - list changes - inspect item - list capabilities - inspect capability ### Phase 2 — Safe state transitions - acknowledge Praxis item - resolve Praxis item - ignore and pin operations - dialogue continuation - explicit entity disambiguation - cross-service correlation IDs ### Phase 3 — Controlled execution - Hexis execution request - confirmation lifecycle - execution status polling - unknown-outcome handling - Praxis execution correlation - web execution history ### Phase 4 — Digestion integration - Praxis change cursor - bounded operational summaries - surfacing semantics - repeated-pattern detection - source degradation awareness - no autonomous execution ### Phase 5 — Hardening - protocol compatibility tests - degraded-mode tests - replay fixtures - cross-service integration harness - latency budgets - security tests - model routing evaluation with ecosystem tools --- ## 19. Acceptance criteria 1. Maven can resolve Russian and English names through Nexus. 2. Ambiguous identities always cause clarification before mutation. 3. Maven can summarize Praxis attention without duplicating Praxis state. 4. Maven preserves surfaced, acknowledged, and resolved semantics. 5. Maven can discover Hexis capabilities for canonical entities. 6. Maven cannot submit arbitrary commands to Hexis. 7. Protected Hexis actions require bound confirmation. 8. Successful execution is reported separately from observed recovery. 9. Praxis remains responsible for operational item resolution. 10. All external calls appear in Maven trace. 11. Nexus, Praxis, and Hexis outages degrade independently. 12. No component database is accessed directly. 13. The resident model is used only for routing, phrasing, and bounded synthesis. 14. LLM output never bypasses deterministic validation or policy. 15. Maven remains useful when all three sibling systems are unavailable. 16. Nexus, Praxis, and Hexis remain useful when Maven is unavailable. 17. Cross-service contracts are versioned. 18. Requests propagate requester identity and correlation IDs. 19. No automatic Praxis-to-Hexis execution path exists. 20. The full integration works without cloud services. --- ## 20. Final invariant ```text Maven may coordinate the ecosystem, but it never replaces the authority of the system it calls. ``` - Nexus is authoritative for identity. - Praxis is authoritative for operational attention and lifecycle. - Hexis is authoritative for capabilities and execution. - Maven is authoritative for conversation, personal context, and user-facing coordination.