This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

VOX Core System Architecture: Component Ontology & Structural Constraints

LEGACY — superseded. This spec predates the current implementation. Prefer VOXOrchestrator, VOXAgent, and VOXCapability. Concrete details here (e.g. is_healthy(), early lifecycle states) describe an earlier design and are retained for history only.

Classification: Internal Architecture Specification
Scope: Orchestrator, Agent, and Capability subsystems
Compliance: Mandatory — violations produce undefined behavior in the execution model

---

Table of Contents

1. Architectural Components
   • 1.1 The Orchestrator (Control Plane)
   • 1.2 The Agent (Execution Node)
   • 1.3 The Capability (Mountable Driver)
2. Zero-Trust Structural Isolation
3. Intercomponent Data Flow & Contract Interfaces
4. Immutable Constraints — Cross-Component Comparison
5. Design Constraints for the LLMCapability Migration

---

1. Architectural Components

1.1 The Orchestrator (Control Plane)

Definition: The deterministic infrastructure runtime that owns process lifecycle, socket I/O, capability injection, and inter-component message routing. It is the single entry point for all external inputs.

Responsibilities:

Responsibility	Specification
Unix Domain Socket ownership	Binds and listens on /tmp/vox.sock; the sole external ingress point. All inbound payloads arrive here.
Deployment manifest resolution	Reads agent.yml at boot to determine agent topology, capability bindings, and parameter overrides.
Process lifecycle management	Boot, supervise, and terminate agent processes. State machine: IDLE → ACTIVE → ERROR → DEAD.
Message routing	Unidirectional delivery from external input to target agent via internal async channels. No bus semantics; point-to-point.
Capability dependency injection	Resolves capability manifests, instantiates CapabilityProviderProtocol implementations, and binds them to agents via VOXBoundCapability proxies.
Infrastructure telemetry	Writes structured event records to a system-level log for DFIR traceability. Events: delivery, routing, lifecycle transitions, health status changes.

Exclusions:

• The Orchestrator does not maintain agent state, memory, or identity.
• The Orchestrator does not perform natural language processing or LLM inference.
• The Orchestrator does not initiate actions autonomously; it is purely reactive.

Immutable constraints:

1. Asynchronous execution model. All I/O operations use asyncio. Synchronous blocking calls (time.sleep, requests.get) are prohibited in the control path.
2. Protocol-mediated communication. The Orchestrator interacts with agents exclusively through CapabilityProviderProtocol and typed event interfaces. Direct property access on agent objects is forbidden.
3. Domain-agnostic routing. The Orchestrator does not interpret payload semantics. It validates structure (JSON schema, required fields) and routes bytes to the target agent specified in the manifest. It has no knowledge of prompts, messages, or document types.

---

1.2 The Agent (Execution Node)

Definition: A stateful execution silo with a fixed persona, a private append-only ledger (memory.db), a private key-value store (VOXAgentStore), and a deterministic perception–thought–action–observation loop. Each agent is a single execution identity within the hierarchical tree.

Responsibilities:

Responsibility	Specification
Deterministic reasoning loop	Sequential execution of perception, thought, action, and observation stages. Given identical input and memory state, the output sequence must be identical.
Private memory management	Owns memory.db — an append-only SQLite ledger. Every internal decision is recorded with an ISO-8601 timestamp. No row modification or deletion is permitted.
Private storage	Manages VOXAgentStore for persona-persistent data (files, assets, configuration).
Capability invocation	Calls mounted capabilities exclusively through VOXBoundCapability proxies. Direct access to HTTP clients, database connections, or external APIs is prohibited.
Hierarchical awareness	Maintains references to exactly one superior node and N subordinate nodes. No lateral peer awareness.

Exclusions:

• The Agent does not expose APIs or accept external connections.
• The Agent does not manage infrastructure resources (sockets, connection pools, manifests).
• The Agent does not communicate with peer agents at the same hierarchy level.

Immutable constraints:

1. Strict Horizontal Boundary Partitioning. An agent has no reference to, and cannot communicate with, any agent outside its direct lineage (superior → self → subordinates). This prevents inter-silo state leakage, collusion, and information flow across isolated execution contexts.

2. Deterministic Loop Invariant. The agent's reasoning loop must be functionally deterministic. Intelligence is derived exclusively from injected capabilities. For a fixed input vector and memory state, the action vector must be reproducible.

3. Append-Only Ledger Invariant. Every perception, thought, capability invocation, and observation is recorded as an immutable row in memory.db. Write-once semantics: INSERT only, no UPDATE or DELETE. Timestamps use ISO-8601 with timezone.

4. Input Sanitization Mandate. All payloads received from the Orchestrator must be validated for schema conformance, type correctness, and bounds before processing. Unsanitized input is a security boundary violation.

---

1.3 The Capability (Mountable Driver)

Definition: A stateless, reusable infrastructure driver that implements a specialized operation (LLM inference, HTTP navigation, messaging protocol adaptation). It is injected into an agent at boot time by the Orchestrator via a VOXBoundCapability proxy.

Responsibilities:

Responsibility	Specification
Operation execution	Accepts a typed request payload, performs the operation, and returns a typed response.
Client lifecycle management	Initializes and tears down operational clients (httpx.AsyncClient, database connections) within boot() and shutdown() hooks.
Self-description	Exposes metadata via PARAMS (parameter schema), CAPABILITY_NAME (unique identifier), and CapabilityProviderProtocol (discovery interface).
Health reporting	Implements is_healthy() returning a boolean. The Orchestrator polls this for availability monitoring.

Exclusions:

• The Capability has no identity, no memory of past invocations, and no decision-making authority.
• The Capability does not know which agent invoked it. It receives only the request payload.
• The Capability does not access agent-private storage (memory.db, VOXAgentStore) directly.

Immutable constraints:

1. Proxy-Mediated Sandboxing. The VOXBoundCapability layer is the ontological boundary. The capability receives only explicitly declared parameters. Any attempt to access the hosting agent's object graph is intercepted and blocked at the proxy layer.

   [Agent] ←→ [VOXBoundCapability] ←→ [Capability]
        prohibited      │
                        └─── Proxy performs parameter filtering,
                             context injection, and schema validation.
   

2. Stateless Invocation Model. The capability must not retain state between invocations. Cross-request caching or RAG must use transient filesystem paths provided as invocation parameters (e.g., context_token=/path/to/memory.db). In-memory state shared across requests is prohibited.

3. Single Boot-time Connection Pool. All external clients are initialized once in boot() and torn down in shutdown(). Per-invocation connection open/close is prohibited. This constraint exists to minimize resource consumption on constrained VPS environments (1 GB RAM, 1 vCPU).

4. Side-Effect Containment. The capability must not write outside its designated working directory, initiate undocumented network calls, or modify agent state. Filesystem writes are restricted to paths declared in its parameter schema.

---

2. Zero-Trust Structural Isolation

2.1 Principle

Each component possesses the minimum set of references and privileges required to fulfill its specified responsibilities. Cross-component access is mediated by validated interfaces only.

This is not a security add-on — it is a structural property of the architecture. It arises from three interdependent mechanisms:

2.2 Isolation Mechanisms

Mechanism	Implementation	Behavioral Property
Memory boundary enforcement	The Agent does not expose memory.db or VOXAgentStore references to capabilities. Capabilities receive only file paths, never file handles or database connections.	A fault in any capability cannot propagate into agent memory.
Implicit trust elimination	All inter-component communication passes through a validation boundary (VOXBoundCapability proxy, typed protocol contracts). No component accepts raw object references from another.	Privilege escalation via component compromise cannot cross isolation boundaries.
Infrastructure decoupling	The Agent has no direct dependency on sockets, manifests, or connection pools. The Orchestrator can migrate agents across threads or processes without agent-level changes.	Resource rebalancing and horizontal scaling do not require agent code modification.

2.3 Invocation Trace (Zero-Trust Path)

1. EXTERNAL INPUT → Orchestrator    validates origin, applies rate limits, checks schema
2. Orchestrator   → Agent            delivers payload, does not forward socket handle
3. Agent          → VOXBoundCapability  requests execution, does not forward memory.db path
4. VOXBoundCapability → Capability   filters parameters, injects only declared context
5. Capability     → External API     executes, has no reference to the calling agent
6. Response propagates back through the same chain with validation at each hop

Each arrow represents a type-checked boundary crossing. The receiving component must validate the payload before processing.

2.4 Resource-Constrained Deployment Implications

Resource	Mitigation Strategy
CPU (1 vCPU)	Connection pooling avoids per-request TLS handshake overhead. Semantic caching reduces LLM invocation frequency.
RAM (1 GB)	Stateless capability model allows memory reclamation between requests. Copy-on-write kernel semantics are leveraged for shared capability binaries.
Disk (SSD 20 GB)	Append-only SQLite with WAL journaling. No per-agent data duplication.
Network (100 Mbps)	Two-tier routing: simple queries are served by local Ollama (zero network latency); complex queries are routed to cloud backends.

---

3. Intercomponent Data Flow & Contract Interfaces

3.1 Complete Invocation Sequence

┌─────────────────────────────────────────────────────────────────────────┐
│                        EXTERNAL INPUT                                   │
│                  (Telegram / CLI / Webhook)                              │
└────────────────────────┬────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ① ORCHESTRATOR (Control Plane)                                         │
│                                                                         │
│   Input:  {"type":"message","agent":"<agent_name>","payload":"...","ts":...}    │
│                                                                         │
│   Operations:                                                           │
│     ├── JSON schema validation                                          │
│     ├── Rate-limit check against sliding-window counter                 │
│     ├── Agent resolution from deployment manifest                       │
│     ├── Payload dispatch via async inter-process channel                │
│     └── Structured log: event=DELIVERY agent=<agent_name> status=ROUTED │
└────────────────────────┬────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ② AGENT (Execution Node - "<agent_name>")                               │
│                                                                         │
│   Input:  {"type":"message","payload":"...","ts":...,"from":"..."}      │
│                                                                         │
│   Operations:                                                           │
│     ├── Schema and bounds validation                                    │
│     ├── Ledger append: INSERT INTO activity_log                        │
│     │   (event, data, agent, ts) VALUES ('perception', {...}, NOW)     │
│     ├── Reasoning loop (deterministic state machine):                   │
│     │   ┌──────────────┐                                                │
│     │   │ Perception   │──→ decode input, update context               │
│     │   ├──────────────┤                                                │
│     │   │ Thought      │──→ evaluate, select action                    │
│     │   ├──────────────┤                                                │
│     │   │ Action       │──→ invoke capability via VOXBoundCapability   │
│     │   ├──────────────┤                                                │
│     │   │ Observation  │──→ process capability response                │
│     │   └──────────────┘                                                │
│     └── Ledger append per stage                                        │
└────────────────────────┬────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ③ VOXBoundCapability (Proxy Layer)                                     │
│                                                                         │
│   Input:  {"method":"generate","params":{"system","prompt",...}}        │
│                                                                         │
│   Operations:                                                           │
│     ├── Parameter whitelist filtering                                   │
│     ├── Internal reference blocking                                     │
│     ├── context_token → absolute file path resolution                   │
│     └── Delegation to capability instance                               │
│                                                                         │
│   Generated automatically — not manually implemented.                   │
└────────────────────────┬────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ④ CAPABILITY (LLMCapability - Driver)                                  │
│                                                                         │
│   Input:  RequestPayload(system, prompt, model, ...)                    │
│                                                                         │
│   Pipeline:                                                             │
│     ├── PromptSanitizer    structural normalization, token ceiling      │
│     ├── SemanticCache      SHA-256 exact match + cosine similarity      │
│     ├── RAGRetriever       FTS5 search on memory.db (via context_token) │
│     ├── Router             complexity classification → backend select   │
│     ├── Backend            HTTP call to Ollama or cloud API             │
│     └── SemanticCache      response storage (SHA-256 key, TTL)          │
│                                                                         │
│   Output: ResponsePayload(content, model, cached: bool, tokens: int)    │
│                                                                         │
│   Invoking agent identity is not propagated to the capability.          │
└────────────────────────┬────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ ⑤ RESPONSE (reverse path)                                              │
│                                                                         │
│   Capability → VOXBoundCapability → Agent → Orchestrator → User         │
│                                                                         │
│   Each hop:                                                             │
│     ├── Receiving component validates payload type and schema            │
│     └── Structured log: recv_from=X event=Y status=Z latency=W          │
│                                                                         │
│   Terminal agent action:                                                │
│     INSERT INTO activity_log (event, data, ts)                          │
│     VALUES ('observation', '{"result":"...","model":"..."}', NOW);      │
└─────────────────────────────────────────────────────────────────────────┘

3.2 Interface Contracts

// CapabilityProviderProtocol — Orchestrator ↔ Capability discovery
interface CapabilityProviderProtocol:
    boot() -> None
    shutdown() -> None
    get_params() -> dict[str, ParamDescriptor]
    is_healthy() -> bool
    get_capabilities() -> list[CapabilityManifest]

// VOXBoundCapability — auto-generated proxy, Agent ↔ Capability contract
interface VOXBoundCapability:
    name: str
    async generate(system: str, prompt: str, *,
                   model: str | None,
                   json_mode: bool,
                   context_token: str | None) -> str
    async generate_vision(system: str, prompt: str,
                          image_path: str) -> str

// Forensic Ledger Schema — memory.db, append-only
table activity_log:
    id:     INTEGER PRIMARY KEY AUTOINCREMENT
    event:  TEXT NOT NULL          -- 'perception' | 'thought' | 'action' | 'observation'
    data:   TEXT NOT NULL          -- JSON-encoded payload
    agent:  TEXT NOT NULL          -- agent identifier
    branch: TEXT NOT NULL DEFAULT 'main'
    ts:     TEXT NOT NULL          -- ISO-8601 with timezone offset

---

4. Immutable Constraints — Cross-Component Comparison

Dimension	Orchestrator	Agent	Capability
Identity	None	Static: name, role, persona	None
Persistence	None	Append-only SQLite ledger + key-value store	Time-bound cache only (TTL-enforced)
Autonomy	Reactive event-driven	Deterministic state machine	None — receives requests, returns responses
Concurrency model	asyncio event loop	Sequential single-threaded loop	Reusable connection pool
Peer awareness	Full topology visibility	Strict lineage only (superior + N subordinates)	None
Failure domain	System-wide — crash terminates all agents	Localized — crash terminates single agent only	Contained — failure does not propagate to agent
Interface surface	CapabilityProviderProtocol	VOXBoundCapability proxy	Driver-specific methods
Language runtime	Python + asyncio	Python + capability invocations	Python + domain drivers

---

5. Design Constraints for the LLMCapability Migration

The component ontology defined in this document imposes binding design constraints on the OllamaCapability → LLMCapability migration. Non-compliance constitutes an architectural violation.

5.1 Required Properties

Constraint	Ontology Reference	Implementation Requirement
Global connection pool	Capability §1.3, constraint 3	Single httpx.AsyncClient initialized in boot(), reused across all generate() calls.
Transient cache	Capability §1.3, constraint 2	SemanticCache operates on SQLite at a configurable path. TTL bounds entry lifetime. No in-memory state carried between invocations.
Filesystem-mediated RAG	Capability §1.3, constraint 2	context_token is resolved to an absolute filesystem path by VOXBoundCapability. LLMCapability performs read-only SQLite queries on that path.
Identity isolation	Capability §1.3, exclusion 2	LLMCapability does not receive or log the invoking agent's identity. It operates exclusively on the request payload.
Parameter sandboxing	Capability §1.3, constraint 1	VOXBoundCapability enforces a whitelist: system, prompt, model, json_mode, context_token. Any undeclared parameter is dropped.

5.2 Prohibited Patterns

Prohibition	Ontology Reference	Consequence of Violation
VOXAgentStore access	Capability §1.3 exclusion 3	Breaks memory isolation; agent state becomes reachable from the capability's fault domain.
Stateful conversation tracking	Capability §1.3 constraint 2	Cross-request state leakage between agents sharing the same capability instance.
memory.db write operations	Agent §1.2 constraint 3	Violates append-only invariant; capability would bypass the agent's ledger abstraction.
Agent identity logging	Capability §1.3 exclusion 2	Introduces ontological coupling between capability and caller; capability loses reusability.
Direct os.environ reads	Capability §1.3 constraint 1, Orchestrator §1.1 constraint 3	Bypasses the parameter injection pipeline; configuration becomes untraceable.

5.3 Lifecycle Binding Sequence

[Orchestrator.boot()]
    │
    ├── LLMCapability.boot()
    │     ├── httpx.AsyncClient()         // reusable connection pool
    │     ├── SemanticCache(path, ttl)    // transient cache store
    │     ├── Router(config)              // complexity heuristics
    │     └── return OK via CapabilityProviderProtocol
    │
    ├── Orchestrator.bind(agent="<agent_name>", capability=LLMCapability)
    │     └── VOXBoundCapability.generate()  // auto-generated proxy
    │
    ├── [Runtime: agent invokes generate()]
    │     └── VOXBoundCapability.filter(system, prompt, model, ...)
    │           └── LLMCapability.generate()
    │                 ├── PromptSanitizer.normalize()
    │                 ├── SemanticCache.lookup()
    │                 ├── RAGRetriever.retrieve()  [if context_token set]
    │                 ├── Router.classify()
    │                 └── Backend.generate()
    │
    └── [Orchestrator.shutdown()]
          └── LLMCapability.shutdown()
                ├── httpx.AsyncClient.close()
                └── SemanticCache.close()

---

Appendix A: Terminology Reference

Term	Definition
Orchestrator	Infrastructure runtime managing process lifecycle, socket I/O, and dependency injection. Zero business logic.
Agent	Stateful execution node with append-only memory, hierarchical parent awareness, and deterministic reasoning loop.
Capability	Stateless mountable driver implementing a specialized operation. No identity or autonomy.
VOXBoundCapability	Auto-generated proxy enforcing parameter whitelisting and type validation between Agent and Capability.
Control Plane	Synonym for Orchestrator; denotes responsibility for coordination rather than data processing.
Forensic Ledger	Append-only SQLite table recording every agent state transition. Write-once semantics.
Execution Silo	Agent instance with isolated memory, filesystem namespace, and capability bindings.
Horizontal Boundary Partitioning	Prohibition against inter-agent communication outside the direct hierarchical lineage.
Zero-Trust Boundary	Inter-component interface requiring explicit type validation before payload processing.

---

Appendix B: System Topology Diagram

                         ┌──────────────────────┐
                         │    ORCHESTRATOR      │  (Control Plane)
                         │  socket, lifecycle,  │
                         │  DI container         │
                         └──────────┬───────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    │               │               │
              ┌─────▼──────┐  ┌────▼──────┐  ┌────▼──────┐
              │ AGENT      │  │ AGENT     │  │ AGENT     │
              │ "agent_a"  │  │ "agent_b" │  │ "agent_c" │
              │            │  │           │  │           │
              │ memory.db  │  │ memory.db │  │ memory.db │
              │ store/     │  │ store/    │  │ store/    │
              └─────┬──────┘  └────┬──────┘  └────┬──────┘
                    │              │              │
              ┌─────▼──────┐  ┌────▼──────┐  ┌────▼──────┐
              │VOXBound    │  │VOXBound   │  │VOXBound   │
              │Capability  │  │Capability │  │Capability │
              │ (proxy)    │  │ (proxy)   │  │ (proxy)   │
              └─────┬──────┘  └────┬──────┘  └────┬──────┘
                    │              │              │
              ┌─────▼──────────────▼──────────────▼──────┐
              │           CAPABILITY POOL               │
              │  LLMCapability, WebBrowserCapability,   │
              │  TelegramCapability, ...                 │
              │  Shared instances, stateless, pooled     │
              └─────────────────────────────────────────┘