# ADR 0005 — Protocol v1.0.0 freeze and the versioning rule

**Status:** accepted · **Date:** 2026-09-09 · **Lane:** PROTO

## Context

M0 exists to produce one thing: an interface the CORE, DAEMON, GUI and EXT lanes can build
against in parallel without meeting. Everything after M0 is four lanes working from the
same contract and not talking to each other for weeks. The cost of getting this wrong is
not a bug; it is an M2 integration rewrite.

The failure mode this is designed against is specific and predictable: a lane needs a field
that isn't in the contract, adds it locally "just for now", and nobody finds out until four
implementations disagree at once.

## Decision

`contracts/VERSION` is frozen at **1.0.0**. The surface is 38 methods, 9 events, 26 named
types and the JSON-RPC envelope, exactly as `contracts/README.md` documents it.

Three corrections landed into 1.0.0 before it reached `main`, answering CORE's
freeze-blockers: a `TaskErrorCode` wire taxonomy, the effective-vs-requested meaning of
`TaskSummary.segments`, and the segment range convention. See ADR 0010 — including why
correcting an unpublished 1.0.0 in place is not the major bump this ADR's own rule would
otherwise demand.

**Semantics of a change:**

| Change | Bump | Also needs |
|---|---|---|
| New method, new event, new optional field | minor | fixtures for it |
| New enum value | minor | both generators handle it; check client `default:` arms |
| Rename, remove, retype, change a default | **major** | an ADR with a migration note |

`session.hello` compares **majors only**. A mismatch is refused with `-32001` and a message
the GUI renders as "Velox needs updating"; a differing minor or patch is always accepted.
Failing loudly at connect is the point — the alternative is failing subtly at the tenth
field, three weeks later.

**Process:** changes arrive as a PR touching `contracts/` alone, containing the schema edit,
the fixtures, the regenerated code and the `VERSION` bump. Lanes rebase onto it. This is the
only synchronization point in the project, so it is kept cheap and frequent rather than big
and rare.

## What enforces this rather than hoping for it

* Generated code is **committed**, so no lane is blocked on running Python, and a stale
  regeneration is a diff in the PR rather than an invisible skew.
* `tests/conformance/check_contract.py` re-runs all four generators and fails if any
  committed output differs. Hand-editing generated code cannot be merged.
* The generators refuse schema constructs they cannot lower, so an unrepresentable schema
  stops the build instead of producing subtly wrong code in one language only.
* Every method must have a success fixture, checked mechanically.
* `SettingKey` and `Settings.properties` must name the same keys, checked mechanically —
  the GUI cannot invent a settings key that isn't in the contract.

## Consequences

* Adding a field costs a round trip through PROTO. That is the price of the guarantee, and
  it is deliberately much cheaper than the M2 rewrite it prevents.
* Four generators must stay in step with `schema_ir.py`. They share one IR precisely so
  this is one change, not four.
* The frozen surface has known asymmetries, left in on purpose rather than invented around:
  there is no `queue.remove` and no `rules.remove` (rules are deleted through
  `rules.upsert`'s `remove` list, queues not at all in v1). These were not added because
  `contracts/README.md` does not list them, and quietly widening the surface during the
  freeze is the exact habit this ADR exists to prevent. They are minor bumps whenever a lane
  actually needs them.

## Alternatives rejected

**Hand-written types per lane.** This is the default and it is how projects like this fail.
Four hand-maintained copies of a type diverge silently; the divergence is discovered at
integration, when all four are load-bearing.

**Protobuf or Cap'n Proto.** Better wire types, but the extension must speak this protocol
from a WebExtension, and JSON-RPC over JSON is what a browser speaks natively. A binary
codec buys efficiency on a control plane that moves a few hundred small messages a second,
and costs a build dependency in every lane plus a much worse debugging story: `nc` and a
browser devtools console can both read this wire.

**Not freezing, and letting the contract evolve continuously.** The whole parallel-lane plan
depends on the interface being still. An unfrozen contract means every lane rebases onto a
moving target, which is the serialized dependency M0 exists to remove.