ADR 0005: Each wire protocol is a separate compatibility layer with its own conformance corpus

Status: Accepted Date: 2026-10-24 Scope: orbit-rs Deciders: Ravindra Boddipalli (accepted 2026-10-24 by instruction to implement)

Context

ADR 0001 sets full PostgreSQL 18 compatibility as the goal and ADR 0002 says how it is measured. The owner asked for the same for MySQL, CQL, AQL, MongoDB and OrbitQL, each as a separate layer, and later listed Redis RESP, Cypher/Bolt, HTTP REST and gRPC as protocols that also need full compatibility with the latest version of their reference (ADR 0006). The table below covers the protocols with a layer today; Redis, Cypher/Bolt, HTTP REST and gRPC are not yet assessed.

State on 2026-10-24 (orbit/server/src/protocols/):

Protocol Source Execution path Conformance evidence
PostgreSQL postgres_wire/ Durable RocksDB engine, Raft 533-record corpus recorded from PostgreSQL 18, 481 pass
MySQL mysql/ (5.4k lines) Legacy SqlEngine (mysql/adapter.rs) over RocksDB-backed TieredTableStorage as wired in main.rs; not the durable engine, not Raft-replicated. How much of its SQL persists is unverified A Python driver script, no recorded corpus
CQL cql/ (10.8k lines) Own parser and adapter A Python driver script
AQL aql/ (12.3k lines) Own parser, query engine and storage A Python driver script
MongoDB mongodb/ (10.2k lines) Own protocol and storage A Python driver script
OrbitQL orbitql/ (1.8k lines) Executor reached through the PostgreSQL wire A Python driver script

All sit in the single orbit-server crate beside the PostgreSQL code. The driver scripts check that features exist; none compares results with the real server, and no pass rate is recorded for any of them. Whatever percentage the older documents quote for these protocols is therefore not a measurement.

Decision

  1. One layer per protocol. Each is its own crate (for example orbit-protocol-mysql) holding the wire codec, the dialect parser, type mapping, error codes and the translation onto the shared engine. A layer depends on the engine’s public interface and on nothing in another protocol’s layer. The goal of each layer is full compatibility with its reference server and version (see ADR 0006), stated under ADR 0002.
  2. One shared engine. Storage, transactions, replication and the catalog are shared. Every layer executes through the durable, replicated engine; the legacy SqlEngine path is retired for MySQL, and no layer keeps its own storage.
  3. One conformance harness per layer, like the PostgreSQL one: a corpus recorded from the real reference server, an oracle run that must pass 100% on that server, and a ratchet file. A layer’s pass rate is the only form in which its compatibility is stated.
  4. A shared contract suite for behaviour that must hold regardless of the front end: committed data survives kill -9, a write acknowledged by Raft is not lost across a leader kill, and two layers see the same data.

Consequences

  • Splitting crates is a large refactor with real cost. Each layer is first brought under its own corpus inside the current crate, then moved out, so the pass rate exists before the move.
  • Layers whose data models differ from SQL (Mongo documents, Cassandra wide rows, Arango graphs) need an engine interface richer than SQL tables. Whether that is a document and key-value API on the durable engine or an adapter that maps onto tables is a design question for each layer’s own record.
  • “Separate” costs duplicated effort on shared concerns (authentication, TLS, limits); those stay in the engine or in shared helpers, not copied.
  • OrbitQL has no external reference server, so its conformance is against its own specification (see ADR 0006).

Verification

Each layer has a make conformance-<protocol> target and an entry in the conformance plan with its pass rate and date. The contract suite runs in CI.