ADR 0006: Reference server and version for each protocol layer

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

Context

“Compatible” needs a reference and a version, because a corpus is recorded from a real instance (ADR 0002). The owner listed the protocols that need full compatibility, with the latest version of each: Redis RESP, PostgreSQL, MySQL, CQL, HTTP REST, gRPC and Cypher/Bolt, and separately asked for AQL, MongoDB and OrbitQL (OrbitQL version 1.0). This record treats both lists as in scope, which makes ten layers.

The specifications under specifications/protocols/ target older lines (MySQL 8.0/9.5, Cassandra 4.x/5.x, MongoDB 6.x/7.x, ArangoDB 3.10+, Neo4j Bolt 5.x, Redis 7.x). mysql/adapter.rs reports whatever server_version its config holds.

Decision

Policy: each layer targets the latest generally available release of its reference, pinned in the corpus and re-recorded when a newer release ships. A corpus records the exact version it was taken from; the pass rate is always stated with that version. When a new release appears, the new corpus is recorded, the layer’s pass rate is restated against it, and the previous corpus is kept as a regression set for the older version.

Latest releases found on 2026-10-24 (a web search; most from a single source, none confirmed on the vendor’s own release page, so each must be confirmed before recording):

Layer Reference Latest found Notes
PostgreSQL PostgreSQL 18 Fixed by ADR 0001. A newer major version is a new decision.
MySQL MySQL Community Server LTS 9.7 (target, owner 2026-10-24); also 26.10 Innovation and LTS 8.4 MySQL moved Innovation releases to calendar versions (YY.M.P) from 26.7. Which line is “latest” is open, see below.
Redis RESP Redis Open Source 8.8 (one aggregator; unconfirmed) RESP2 and RESP3, the command set and modules that ship in Redis 8.
CQL Apache Cassandra 5.0 (5.0.9, unconfirmed) Native protocol v4 and v5, CQL grammar.
Cypher/Bolt Neo4j Release 2026.06 and Bolt 6.0 (third-party reports; unconfirmed) Cypher language and Bolt protocol. Neo4j 5.26 LTS is also current.
AQL ArangoDB 3.12 (3.12.11, unconfirmed) AQL grammar and functions, the HTTP API drivers use, graphs and traversals.
MongoDB MongoDB Community 8.3 OP_MSG wire protocol, CRUD, aggregation pipeline, indexes, transactions, change streams.
OrbitQL The OrbitQL 1.0 specification 1.0 (owner) No external server; see below.
HTTP REST Orbit’s own API specification not set No external reference; see below.
gRPC Orbit’s own service definitions not set gRPC is a standard; the Orbit services are Orbit’s own. See below.

For each external reference the corpus is recorded from the real server, which must pass it 100%. No exclusion list is proposed, consistent with ADR 0001; items are sequenced last, not excluded.

Open for the owner (still unanswered when accepted)

  1. MySQL line. “Latest” is 26.10 Innovation, which changes monthly and is not an LTS. Options: record against the latest Innovation release; record against the latest LTS (9.7); or both, with the LTS as the stated target. MariaDB is a separate question. Resolved 2026-10-24 (owner): the stated target is MySQL LTS 9.7. Innovation releases (26.10 and later) are re-recorded as a secondary measurement and are not the headline number.
  2. OrbitQL, HTTP REST and gRPC have no external server. “Latest version” has no meaning for them. Proposed: each gets a written, versioned specification (OrbitQL 1.0 as set; an OpenAPI document for HTTP REST; the .proto files for gRPC), and conformance means passing a suite derived from it. Alternatively, drop HTTP REST and gRPC from the compatibility program, since they are Orbit’s own interfaces.
  3. Scope. Whether Redis, Cypher/Bolt, HTTP REST and gRPC join AQL, MongoDB and OrbitQL as full layers under ADR 0005.
  4. Neo4j. Whether the target is the 2026.xx release line, the 5.26 LTS, or both; and which Bolt versions.

Consequences

  • Each external target needs a real instance for recording (Docker, or a local install) available to the person running make conformance-record.
  • Tracking the latest release means the work never reaches a fixed finish line: a new upstream release can lower a layer’s pass rate. That is reported, not hidden.
  • Changing the policy or a pinned version is a new record that supersedes this one.
  • OrbitQL 1.0 needs a written specification, tagged 1.0, before its suite can be called conformance; until then its checks are feature checks.

Verification

Per layer: the oracle run passes 100% on the pinned reference version; the ratchet file records the pass rate for orbit-rs against it. No pass rate exists yet for any layer except PostgreSQL.