sami/vdm
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

proto: ADR 0014 — versioning a generated-binding break with an unchanged wire

Browse Source 
Records the rule 1.4.0 applied, so the next generated-binding retype cites it
instead of relitigating README rule 4's "retype → major + ADR" from scratch.

The rule: VERSION tracks the wire protocol, not any binding's API or ABI. A
change that leaves the wire byte-identical but breaks a generated binding's
source API (a C++ virtual's return type, a struct name) is a minor bump plus
a migration note — major would make session.hello refuse a client whose wire
behaviour is unchanged, which is worse than the problem. An ADR is still
required when the change encodes a design decision; "only one lane consumes
it" is not a reason to skip that, since GUI already links velox::proto and
the next such change starts with more than one consumer.

Rule 4 in contracts/README.md now points here so its "major + ADR" line
isn't read in isolation. proto-answers-daemon-m1.md's P1 writeup references
it as the durable home for the reasoning that was otherwise only in a commit
message.

Also names the nlohmann brace-init hazard the 1.4.0 work hit: json{nullptr}
is the array [null], not JSON null, so HandlerError::data is `= nullptr`. The
kind of thing a regeneration reintroduces; caught here only by an end-to-end
assertion on dispatch() output, which is called out to keep.

Docs only — no schema, VERSION, or generated-code change.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_012fgjnqFCS5h5L7gZTZo3rV
This commit is contained in:
sami
2026-09-10 15:24:53 +04:00
co-authored by Claude Sonnet 5
parent 5e3e21543a
commit 768f4f8e53
3 changed files with 92 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
contracts/proto-answers-daemon-m1.md
+10 -6
View File
@@ -56,12 +56,16 @@ reason.)
`Result` → `HandlerResult` automatically; `conformance_main.cpp` only ever inspects
`dispatch()`'s JSON output and needed no change.
**Version:** minor, 1.3.0 → 1.4.0. The wire is byte-identical — no schema, fixture, or
OpenRPC change — but every implementer of `Dispatcher` must swap `Result` → `HandlerResult`
on their `on_*` overrides or they won't compile, and a version bump is how lanes are told
to regenerate and adapt. Not major and not an ADR: one lane consumes this binding, it's
the lane that asked, and there's no contested design here — the shape is the one you
proposed. `kProtocolVersion` moves to `"1.4.0"` with it.
**Version:** minor, 1.3.0 → 1.4.0. The wire is byte-identical — no schema, fixture,
or OpenRPC change — but every implementer of `Dispatcher` must swap `Result` →
`HandlerResult` on their `on_*` overrides or they won't compile, and a version bump is
how lanes are told to regenerate and adapt. Minor, not major: a major would make
`session.hello` refuse a client whose wire behaviour is unchanged. The rule — a
generated-binding API break with an unchanged wire is minor + migration note, because
`VERSION` is the protocol version, not the C++ ABI — is written up as
`docs/adr/0014-generated-binding-changes-and-versioning.md` (this instance is
mechanical; the ADR records the rule for the next one, which GUI will also consume
since it already links `velox::proto`). `kProtocolVersion` moves to `"1.4.0"` with it.
## P2 — clarifications