ADR 0017: One project statement, and counts come from a script

Status: Proposed Date: 2026-10-25 Scope: orbit-rs Deciders:

Context

Each overview page restates what orbit-rs is and how big it is, and they disagree with the code and with each other. The public overview lists seven protocols and omits MongoDB (a target in ADR 0005 and ADR 0006); says “1,078+ tests” and “148,780+ lines” where scripts/project_facts.py counts 3,986 test functions and 457,233 lines of Rust at commit 222ac1c2; and says nothing of schemas, roles and privileges (ADR 0003, ADR 0013) or Raft replication (ADR 0004). Hand-typed counts go stale the day they are written.

Decision

  1. One statement. Every overview, README and site page that says what orbit-rs is uses the canonical wording below, and links to the protocol table in ADR 0006 and to the maturity page (ADR 0015). Pages do not paraphrase it.
  2. Generated figures. Counts of tests, lines, protocols and the conformance floor come from scripts/project_facts.py, quoted with the date and commit it prints. A page that needs a fresh number runs the script; nobody types one from memory.
  3. Protocols listed once. The set of protocol layers and their target versions lives in ADR 0006’s table. Other documents link to it or copy it whole, with each layer’s label from the maturity page.
  4. A claim has a source. A sentence that states a capability links the test, corpus file or record that shows it; one that states a goal says “goal”.

Consequences

  • The several overview pages shrink to the statement plus links, so they cannot drift apart.
  • docs/project_overview.md and the pages that copy it are rewritten from this record and ADRs 0002, 0015 and 0016.
  • A documentation check can compare quoted figures with scripts/project_facts.py --json later.

Canonical wording

Orbit-RS is a distributed database that speaks several wire protocols over one durable, replicated store. Its goal is full compatibility with PostgreSQL 18, measured against the PostgreSQL 18 conformance corpus; each other protocol layer targets the latest version of the system it imitates (see the protocol table). Compatibility, maturity and performance are stated only as measured: a conformance pass rate with its date, a maturity label with its evidence, and benchmark results with their method.

Verification

scripts/project_facts.py runs from a clean checkout; make adr-check rejects the retired wording in the scanned pages; the overview pages carry the statement verbatim.