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.

The front door — auth-first ingress

Before any agent reasons, a request has to get in. A message from Microsoft Teams or Slack arrives at one channel-neutral gateway and clears four sequential checks — signature verification, per-user OIDC identity (RS256 / JWKS), replay/nonce rejection, and a budget ceiling. Only an authenticated, in-budget request reaches the deliberation loop below; anything that fails a check is rejected at the door.

Design-partner preview. The spine is verified against a local OIDC validator; connectors for commercial identity providers (Entra, Okta, Auth0) are configuration-level and not yet exercised — shown dashed below.

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.

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

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.

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.