vdm/docs/adr/0015-generated-binding-changes-and-versioning.md

ADR 0015 — Versioning a generated-binding break with an unchanged wire

Status: accepted · Date: 2026-09-10 · Lane: PROTO Prompted by: the 1.4.0 bump (DAEMON's P1 — HandlerResult / HandlerError on the generated C++ Dispatcher), recorded here as a rule rather than left as a one-off.

Context

contracts/README.md rule 4 says: optional field or new method → minor; rename, remove, retype, or default change → major + an ADR. Read literally, the 1.4.0 change retyped every Dispatcher::on_* method (Result<T> → HandlerResult<T>) and so should have been major with an ADR.

It was shipped as a minor bump with a migration note and no ADR. That call was right, but the reasoning only lived in a commit message and a proto-answers-* doc. The next generated-binding change — and there will be one; the C++ and TypeScript emitters are young — would get argued from rule 4's literal text again, and rule 4 would read as though PROTO quietly exempts itself whenever it's inconvenient.

Decision

VERSION tracks the wire protocol, not any binding's API or ABI. Two clients at the same VERSION speak the same JSON-RPC: same methods, same params and result shapes, same event payloads, same error codes on the wire. That is the whole promise session.hello enforces (major-only), and it is the only thing VERSION is allowed to mean.

From that, the versioning rule for a change that leaves the wire byte-identical but alters the generated binding's source-level API (a return type, a struct name, a signature — anything that makes a regenerated core/generated/ or extension/src/shared/protocol/ stop compiling against last version's hand-written code):

• Minor bump. Not major. A major bump makes session.hello reject a client that is wire-compatible — actively worse than the problem, since the wire didn't change.
• A migration note in the same PR: what to regenerate, and the mechanical edit each consumer makes (e.g. "swap Result → HandlerResult on every on_* override"). The proto-answers-* doc for the requesting lane is the normal home; contracts/README.md's version banner carries the one-line summary.
• An ADR only when the change encodes a design decision — a new type's shape, a new contract, a semantic split. A purely mechanical shape change (this one: the error-channel type DAEMON proposed, applied as sketched) does not need one; it needs the migration note. "One lane consumes it today" is not a reason to skip the ADR when the change is a design decision — GUI already links velox::proto, and the next such change will have more than one consumer from day one.

Rule 4's "retype → major" is about the wire. Retyping a field on TaskError, TaskSummary, a method's params or result — anything a client parses off the socket — is major, because a peer at the old version mis-parses it. Retyping a generated C++ virtual's return type is not that: no byte on the wire moved, and the compiler catches every call site at build time. The two are different failure modes and get different rules.

A regeneration hazard worth naming

nlohmann::json brace-initialization from nullptr produces the array [null], not JSON null. HandlerError's data member is written nlohmann::json data = nullptr; (copy-init) for exactly this reason; a member written data{nullptr} compiles, passes a casual read, and makes every defaulted HandlerError{} emit "data":[null] in the error response. It was caught here only by an end-to-end assertion on dispatch()'s output.

Anyone hand-editing contracts/codegen/gen_cpp.py around json defaults or literals: prefer = nullptr / = {} / json::object() / json::array() over brace-init with a single element, and keep the dispatch()-output assertions that would catch a regression.

Consequences

• The 1.4.0 bump stands as a minor with a migration note; this ADR is its written backing.
• A future generated-binding retype cites this ADR instead of relitigating rule 4.
• contracts/README.md rule 4 gets a pointer here so the "major + ADR" line isn't read in isolation.

Alternatives rejected

Make it major, per rule 4's literal text. Rejected: session.hello compares majors and would refuse a client whose wire behaviour is unchanged. The rule's purpose is to stop incompatible peers connecting; applying it here would block compatible ones.

Leave the reasoning in commit messages and proto-answers-* docs, as done for 1.4.0. Rejected: those are per-instance and get lost. The rule needs one durable home, which is what docs/adr/ is for (ADR 0001).