"Communication protocols"

Communication protocols

This page is the prose companion to the machine-readable catalog at contracts/communication/protocol-catalog.yaml.

What is unified

Vox uses a single taxonomy, not a single wire format.

  • Keep one machine-readable inventory of protocol families, delivery planes, and ownership.
  • Keep one prose reference page per protocol family that points back to its contract artifact.
  • Reuse helpers only where payload shape and lifecycle genuinely match.
  • For which wire to pick when adding traffic (SSE vs WebSocket vs HTTP-only, MCP remote vs stdio, mesh vs DB inbox), use the lane matrix and bibliography in Protocol convergence research 2026 as advisory input; this reference page remains the normative inventory and reduction policy.

Delivery planes

These are the canonical plane names used when comparing transports across the repo:

PlaneMeaningTypical examples
local_ephemeralSame-process delivery with no restart durabilityactor mailboxes, orchestrator local A2A bus
local_durableHost-local durable storage with explicit replay/ack semanticsDB inbox, persistence outbox
remote_meshRemote HTTP-mediated delivery across nodes with bearer/JWT authPopuli control plane and relay
broadcastFanout where receivers observe local order onlysubscription notifications, bulletin/event buses, webhooks
streamOrdered incremental delivery over one connection or byte streamruntime SSE, MCP WS gateway, OpenClaw WS, JSON-line daemons

Family matrix

FamilyPrimary contractPrimary docCanonical decision
MCP stdiocontracts/mcp/tool-registry.canonical.yaml[`docs/src/reference/cli.md)Keep as the default host/editor control surface
MCP HTTP gatewaycontracts/mcp/http-gateway.openapi.yamlmcp-http-gateway-contract.mdKeep bounded and opt-in for remote/mobile control
Populi HTTP control planecontracts/populi/control-plane.openapi.yamlpopuli.mdKeep HTTP-first per ADR 008
Populi A2A relaycontracts/populi/control-plane.openapi.yamlpopuli.mdEvaluate overlap only against DB inbox after telemetry-backed review
Orchestrator local A2Ain-code types onlyorchestration-unified.mdKeep as the low-latency same-process lane
Orchestrator DB inbox / outboxcontracts/communication/orchestrator-persistence-outbox.schema.json (outbox lifecycle/queue) + in-code DB inbox typesorchestration-unified.mdKeep durable semantics separate from ephemeral/local bus semantics
Runtime SSEin-code types only[`docs/src/reference/cli.md)Keep SSE as the default app streaming transport
DeI JSON-line RPCcontracts/dei/rpc-methods.schema.jsonorchestration-unified.mdEvaluate convergence only where envelopes already align
Orchestrator JSON-line RPCcontracts/orchestration/orch-daemon-rpc-methods.schema.jsonorchestration-unified.mdKeep separate from DeI while vox-orchestrator-d orch.* parity evolves
LSP JSON-RPCexternal protocolthis pageKeep independent; ecosystem protocol
OpenClaw WSfixture contracts under contracts/openclaw/docs/src/adr/013-openclaw-ws-native-strategy.mdKeep WS-first because upstream is WS-native
Codex HTTP APIcontracts/codex-api.openapi.yamlcodex-http-api.mdKeep as a separate public/service API family

Current reduction policy

  • Do not collapse local_ephemeral, local_durable, and remote_mesh into one abstract transport with hidden semantics.
  • Do not add a parallel in-tree gRPC/QUIC default beside Populi HTTP without a replacement ADR.
  • Do not replace runtime SSE with WebSocket by default.
  • Do not merge external ecosystem protocols such as LSP or OpenClaw into Vox-specific RPC envelopes.

Retirement checkpoints

Protocol families marked evaluate in the catalog should only be merged or removed when all of the following are true:

  1. They serve the same use case.
  2. They have compatible auth, durability, and observability needs.
  3. There is a migration path with stable aliases or coexistence.
  4. Existing telemetry and contract checks are sufficient to prove parity.