Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0055

ADR-0055: volk_registry lives in the agents layer; L0 protocols never name concretes

← ADR-0054 · ADR-0056 →

The record

Date: 2026-09-21 · Status: Accepted (executed under Mohamed's direction)

Context

kernel/volk_registry.py (L4) is the volk/agent registry — an agent-domain concept — but its L4 home forced L3 consumers (agents/runtime.py) and even the L0 protocol module core/protocols/volk_health.py into upward imports. The review's migration map placed it in orchestrata.kernel; the migration plan's root-cause analysis placed it in orchestrata.agents. The documents contradicted each other.

Decision

• Relocate kernel/volk_registry.py → agents/volk_registry.py (K3, merged). The registry is an agent-domain concern; kernel still wires the concrete at the composition root behind VolkRegistryProtocol (target-architecture wiring table amended accordingly).
• L0 purity rule: protocol modules must not import concretes, even under TYPE_CHECKING. core/protocols/volk_health.py no longer references the concrete VolkRegistry/VolkHealth at all — it uses the existing VolkRegistryProtocol/VolkHealthProbe structural protocols in core/protocols/decoupling.py. Structural conformance of the concrete is asserted by a smoke test.

Consequences

• The map-vs-plan contradiction is resolved in the plan's favor; the map is now the single authoritative target list (reconciled 2026-09-21).
• agents/runtime.py's two upward edges became intra-package (L3) imports.
• Sets the precedent for Cycle-2 (K6): core must import nothing from cxp/postman/orchestrator/kernel — vocabulary, not concretes.

Related ADRs

No other ADR is named in this record.

Rulings cited

None.

Specs cited

None (or no spec page exists for the ones named).