docs: tier the tree by lifetime, so staleness shows in the path (V-446)
Seventeen markdown files at the repo root, twelve of them dated one-shot reports sitting next to CLAUDE.md. That is why stale docs read as current: nothing in the path said which was which. Root now keeps CLAUDE.md and AGENTS.md. Living docs move under docs/ and carry a Last verified line. Dated measurements move to docs/evals/ ISO-prefixed, and are never edited after the day, so a newer number is a new file. The senior review moves to docs/archive/. Every reference was rewritten across markdown, Go comments, the Makefile and the recall fixture. The touched Go packages still build. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,887 @@
|
||||
# Maven Ecosystem Architecture
|
||||
|
||||
*Last verified: 2026-08-02 @ 7079a24. Living doc: correct it in place, do not append.*
|
||||
|
||||
## 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 model (Qwen3.5-0.8B now, CPT'd Qwen3-1.7B as the target — #122)
|
||||
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.
|
||||
Reference in New Issue
Block a user