CONCEPTS

Conceptual model

Verdaca's architecture is built around two independent axes of extensibility: the horizontal persona layer, where you compose who deliberates, and the vertical adapter layer, where you configure what infrastructure those personas use. Understanding how the kernel mediates between them is the key to extending the platform without breaking existing workflows.

Two-axis pluggability

The horizontal axis controls deliberation composition — which personas are in the room and in what sequence they reason. The vertical axis controls substrate — which memory backend, model provider, and compaction engine the kernel routes through. A change on one axis has no effect on the other, because both axes talk only to the port contracts in between.

╔════════════════════════════════════════════════════════════════════╗
║  WORKFLOWS   "Strategy review" · "Code review" · "Hiring"          ║
║              · "M&A diligence" · "Architecture review"             ║
╠════════════════════════════════════════════════════════════════════╣
║  AGENTS      Plug-in personas (the "who" in the room)              ║
║  ┌────────┬────────┬────────┬────────┬────────┐                    ║
║  │Strategy│  UX/   │Software│  Data  │  Your  │                    ║
║  │  pack  │ Design │  Eng   │Science │ custom │                    ║
║  │        │  pack  │  pack  │  pack  │  pack  │                    ║
║  └────────┴────────┴────────┴────────┴────────┘                    ║
╠════════════════════════════════════════════════════════════════════╣
║  KERNEL      Orchestration · Routing · Provenance                  ║
║              (knows nothing about domain — just protocol)          ║
╠════════════════════════════════════════════════════════════════════╣
║  PORTS       Memory · LLM Proxy · Compaction · QA · Coord          ║
╠════════════════════════════════════════════════════════════════════╣
║  ADAPTERS    Mem0/Letta · Anthropic/OpenAI · Forge/Caveman/...     ║
╚════════════════════════════════════════════════════════════════════╝

Deliberation loop

Each persona in a session passes through a fixed five-phase loop: receive the current context, reason against its role constraints, propose an output, pass through the quality gate, and emit to the synthesis layer. Proposals that fail the gate re-enter the reason phase rather than propagating downstream. The kernel coordinates sequencing and provenance; it does not interpret domain content.

  INPUT
    │
    ▼
  RECEIVE  →  REASON  →  PROPOSE  →  GATE  →  EMIT
    │                                  │
    │         (per persona)            │ reject: re-reason
    └──────────────────────────────────┘

Kernel responsibilities

The kernel handles three things and nothing else:

Route inputs and inter-agent messages according to the workflow graph, without applying domain logic
Track provenance — which persona produced which claim, in which round, and with what gate result
Enforce the port contracts at every adapter boundary and reject calls that violate the interface

ADVISORY

The kernel has no domain knowledge and applies no editorial judgment. If two personas reach contradictory conclusions, both are preserved in the output; resolution is the human practitioner's call, not the kernel's.

Adapter contract

Every adapter in Verdaca implements the same typed protocol for its port category. The memory adapter contract, for example, requires three methods. Any class that satisfies the protocol — including custom implementations — is a valid drop-in.

class MemoryAdapter(Protocol):
    def store(self, key: str, value: Any) -> None: ...
    def retrieve(self, key: str) -> Optional[Any]: ...
    def search(self, query: str, top_k: int) -> list[Any]: ...

Vendored components

These are the pinned components Verdaca vendors and validates at the adapter layer. Each pin is a specific version or commit SHA chosen for behavioral reproducibility — both Apache-2.0 and MIT entries are license-clean for commercial distribution, and "validates" means Verdaca's contract tests run against the pinned artifact on every build, not against the upstream tip.

Component	Purpose	Pinned version
`mem0`	Memory adapter — hybrid vector + graph store	`v1.0.11` (Apache-2.0)
`letta`	Memory adapter — stateful memory management	`v1.10.3` (Apache-2.0)
`tonl`	Serialization — structured agent message format	`pinned SHA` (Apache-2.0)
`beads`	Versioned-state — conversation state versioning	`pinned SHA` (MIT)
`forge`	Compaction — context window compaction	`pinned SHA` (MIT)
`pi-mono`	Cost-meter — per-session token cost tracking	`pinned SHA` (MIT)
`rtk`	LLM-proxy — model-provider routing adapter	`pinned SHA` (MIT)

Pinned versions are locked in pyproject.toml and verified against the no-waiver conformance suite on every release; a version bump requires a passing test run before the pin advances.