sami/vdm

Files

T

samiandClaude Opus 5 53421d6cb8 proto: freeze the wire contract at 1.0.0

Schemas for the whole v1 surface: 38 methods, 9 events, 25 named types and the
JSON-RPC envelope, with x-privileged / x-transports / x-deadlineMs / x-errors
annotations that both generators emit as data rather than prose.

Four generators over one IR (contracts/codegen/schema_ir.py), so the C++ structs,
the TypeScript types and the OpenRPC document cannot disagree about what the
contract says:

  gen_cpp.py             -> core/generated/velox_proto.{hpp,cpp}
  gen_ts.py              -> extension/src/shared/protocol/
  gen_openrpc.py         -> contracts/openrpc.json
  gen_cpp_conformance.py -> tests/conformance/cpp/fixture_dispatcher.hpp

Inbound parsing never throws: parse<T>() returns std::expected<T, ParseError> and
nlohmann's throwing ADL from_json is deliberately not emitted. Schema constraints
(minimum, maxLength, pattern, ...) become real runtime checks in both languages —
the daemon does not trust the extension and the extension does not trust the
daemon.

59 golden fixtures: a success case per method, 12 error cases, 9 events. Replayed
by tests/conformance/ against both the generated C++ and a live server over both
transports. tools/mockd serves the same fixtures with unhappy-path flags so the
GUI and EXT lanes never wait for veloxd.

run.sh also proves capture.offer fails open: with a daemon answering slower than
750 ms the client gives up and lets Firefox take the download.

core/generated/ is libveloxproto, a separate target from libveloxcore, which
still never sees JSON — see docs/adr/0009.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV

2026-09-09 19:55:54 +04:00

4.1 KiB

Raw Blame History

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, 25 named types and the JSON-RPC envelope, exactly as contracts/README.md documents it.

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.

4.1 KiB Raw Blame History