Maven/MAVEN_ECOSYSTEM_ARCHITECTURE.md

# 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.