fix(httpapi): make bd_version wire_revision inference advisory

Opus review of 12c5144ca (HIGH-3). The spec told a client inferring
wire_revision from bd_version to use the release cutoff >= 1.3.0, and said
nothing about what happens when that inference is wrong -- which it
demonstrably is for real builds already in the field:

- main builds up to commit b3ef65c85 report bd_version 1.2.2 (below any
  1.3.0 cutoff) while already sending the string-typed revision/
  expected_version shape (#6053).
- 1.3.0-rc.N pre-release builds sort BELOW the release cutoff 1.3.0 under
  plain string comparison despite already carrying the string shape.
- The bd-enterprise compatibility line at d3ab32773462 reports bd_version
  1.1.0 while also sending strings.

Moved the cutoff to >= 1.3.0-rc.1 (compared as semver-with-prerelease,
which at least captures the rc builds), documented both named exceptions
inline, and made the whole inference explicitly ADVISORY: a client must
accept revision/expected_version as either a string or a number whenever
wire_revision is absent (or probe directly) rather than let the inferred
value choose a decoder, and must never refuse solely because the inferred
revision is 0. Mirrored into engdocs/design/bd-serve-v0.md.

This is spec/doc prose only -- there is no server-side inference code to
change, since this server always sends wire_revision directly; the
inference is guidance for clients reading a pre-signal server's response
(this server, past builds, or an unrelated implementation).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Julian Knutsen 2026-10-05 00:39:43 +00:00 • committed by Eddie the Engineer
commit e8a4edbbdc
3 changed files with 66 additions and 11 deletions

View file

@ -547,9 +547,19 @@ property's description in `openapi.v0.yaml` — `0` for every build before this
field existed (an integer `revision`, pre-#6053), `1` for the brief
string-typed `revision` (#6053), `2` for the first build carrying
`wire_revision` itself. A client talking to a build too old to answer this
field at all infers the value from `bd_version`, which is always present; the
mapping is documented beside the property rather than assumed, because
`bd_version` alone does not sort the same way a counter does.
field at all may use `bd_version` as an ADVISORY hint, never proof: compare it
as semver with pre-release identifiers and treat `>= 1.3.0-rc.1` (not the
release cutoff `1.3.0` — a `1.3.0-rc.N` build already carries the string shape
and sorts below `1.3.0`) as a hint toward `1`, else a hint toward `0`. Two
known builds defeat even that corrected hint: `main` up to commit
`b3ef65c85` reports `bd_version: "1.2.2"` while already sending strings, and
the bd-enterprise compatibility line at `d3ab32773462` reports `"1.1.0"` while
also sending strings. A client therefore MUST accept `revision` and
`expected_version` as either a string or a number whenever `wire_revision` is
absent (or probe the shape directly) rather than let the inferred value
choose a decoder, and MUST NEVER refuse solely because the inferred revision
is `0` — see the `wire_revision` property's description for the exact
language.
`min_client_wire_revision` is the other half: the oldest revision a build
still answers correctly. A client that knows the revision it was compiled

View file

@ -1053,7 +1053,19 @@ type ContextResponse struct {
// `wire_revision` and `min_client_wire_revision` at all (this one).
//
//
// A client talking to a server that omits this member entirely is talking to a pre-signal server and INFERS the revision rather than reading one: `1` when `bd_version` is `>= 1.3.0`, else `0`. A client that does not know how to speak the revision it reads or infers must refuse to proceed rather than guess at the shape.
// A client talking to a server that omits this member entirely is talking to a pre-signal server. `bd_version` is a HINT for that case, never proof: compare it as semver WITH PRE-RELEASE identifiers, and treat `>= 1.3.0-rc.1` — not the release cutoff `1.3.0` itself — as a hint toward `1`, anything below as a hint toward `0`. The release cutoff is wrong on its own because a `1.3.0-rc.N` pre-release build already carries the `1` shape and sorts BELOW `1.3.0`.
//
// Known exceptions make even that corrected hint unreliable, which is why it is advisory rather than authoritative:
//
// * Builds from `main` up to commit `b3ef65c85` report
// `bd_version: "1.2.2"` — below the `1.3.0-rc.1` hint cutoff —
// while already sending the string-typed shape (`1`, not `0`).
// * The bd-enterprise compatibility line at commit `d3ab32773462`
// reports `bd_version: "1.1.0"` while also sending the
// string-typed shape.
//
//
// Because builds like these exist, a client MUST NOT trust the inferred revision to pick a decoder. Instead it MUST do ONE of: accept `revision` and `expected_version` as EITHER a JSON string OR a JSON number whenever `wire_revision` is absent, or probe the actual shape directly (for instance by inspecting the JSON type of a `revision` value already in hand). A client MUST NEVER refuse a request solely because the inferred revision is `0` — `0` here means only "this is an unreliable hint," never a confirmed fact to gate decoding on by itself. A client that still cannot cope with either shape after probing must refuse to proceed rather than guess, exactly as it would for a `wire_revision` it read directly and does not understand.
//
// This document's own drift gate is `TestWireShapeDigest` (`internal/httpapi/wireshape`): a golden digest of every EXISTING response member's (schema, member, type, format, enum, required) fails CI the moment any one of them changes without this field's Go constant (`CurrentWireRevision`, `internal/httpapi/wire_revision.go`) increasing to match. Regenerate the golden with `go run ./internal/httpapi/wireshape/cmd/gendigest` after a deliberate, revision-bumped change, and commit the result — see that package's doc.go for the exact command. A purely additive member or operation also changes the golden (it is appended to, never frozen in place) but needs no revision bump to pass.
//

View file

@ -220,9 +220,13 @@ info:
behavior: a non-additive change to an EXISTING member's type, meaning,
presence or name bumps `wire_revision`; a brand-new member or operation
does not. A client that reads no `wire_revision` at all is talking to a
server that predates it and infers one from `bd_version` (`>= 1.3.0`
means `1`, else `0`); see `ContextResponse.wire_revision` for the full
table and the `Bd-Wire-Revision` request header.
server that predates it and may use `bd_version` as an ADVISORY hint
(`>= 1.3.0-rc.1` hints `1`, else hints `0`) — never as proof: see
`ContextResponse.wire_revision` for the known builds where the hint is
wrong, why a client must accept `revision`/`expected_version` as either
a string or a number whenever `wire_revision` is absent, and why an
inferred `0` must never by itself be grounds to refuse a request. See
also the `Bd-Wire-Revision` request header.
* Clients MUST default-branch on unknown `code` and `reason` values within
a status class: both vocabularies grow additively, so an exhaustive
switch breaks on the first addition.
@ -7557,10 +7561,39 @@ components:
A client talking to a server that omits this member entirely is
talking to a pre-signal server and INFERS the revision rather than
reading one: `1` when `bd_version` is `>= 1.3.0`, else `0`. A
client that does not know how to speak the revision it reads or
infers must refuse to proceed rather than guess at the shape.
talking to a pre-signal server. `bd_version` is a HINT for that
case, never proof: compare it as semver WITH PRE-RELEASE
identifiers, and treat `>= 1.3.0-rc.1` — not the release cutoff
`1.3.0` itself — as a hint toward `1`, anything below as a hint
toward `0`. The release cutoff is wrong on its own because a
`1.3.0-rc.N` pre-release build already carries the `1` shape and
sorts BELOW `1.3.0`.
Known exceptions make even that corrected hint unreliable, which
is why it is advisory rather than authoritative:
* Builds from `main` up to commit `b3ef65c85` report
`bd_version: "1.2.2"` — below the `1.3.0-rc.1` hint cutoff —
while already sending the string-typed shape (`1`, not `0`).
* The bd-enterprise compatibility line at commit `d3ab32773462`
reports `bd_version: "1.1.0"` while also sending the
string-typed shape.
Because builds like these exist, a client MUST NOT trust the
inferred revision to pick a decoder. Instead it MUST do ONE of:
accept `revision` and `expected_version` as EITHER a JSON string
OR a JSON number whenever `wire_revision` is absent, or probe the
actual shape directly (for instance by inspecting the JSON type of
a `revision` value already in hand). A client MUST NEVER refuse a
request solely because the inferred revision is `0` — `0` here
means only "this is an unreliable hint," never a confirmed fact to
gate decoding on by itself. A client that still cannot cope with
either shape after probing must refuse to proceed rather than
guess, exactly as it would for a `wire_revision` it read directly
and does not understand.
This document's own drift gate is `TestWireShapeDigest`