Every `expected_version` on this surface is composed from a token some response
carried, and until now every response that carried one was a WRITE. A client
that wanted to read a row, decide from what it said, and write it back under a
guard had to precede its first guarded write with a write it did not want to
make — or guard on nothing, which is the lost update the whole family exists to
refuse. Five places in the document said "no READ on this surface publishes a
revision yet" and named the member a read would have to agree with. This is that
member.
Spec first, then `make api-gen`, then the projection.
GET /v0/beads/issues/{id} PUBLISHES IT; GET /v0/beads/issues DOES NOT, and the
reason is not payload. Measured against a 20,482-row production export the
member is 28 bytes on a 1449-byte median row — under 2%, and the list rows are
already fat enough that a token would disappear into them. The reason is that
`types.IssueWithCounts` is ALSO THE INTERCHANGE ROW: `exportIssueRecord` embeds
it in both `bd export` and the auto-export that flushes a git-tracked
`issues.jsonl`, and the token is re-minted by every write, so publishing it on
that element would put a per-write-random value into a file whose whole value is
that it diffs when something meant something. That is precisely the loss
`types.Issue.RowVersion`'s `json:"-"` is there to prevent, and a wire member
cannot opt out of it — the list element and the export element are one pinned Go
struct. `types.IssueDetails` has neither problem: nothing interchanges it, and
`workapi.BuildIssueDetails` is its ONE production construction site against
IssueWithCounts's SIX, which is the second half of the argument. (Six
field-populating non-test literals: export.go, export_auto.go, search.go,
claim_next.go, ready_work_counts.go and uow/ready_claimer.go. The `[]*T{claimed}`
spellings in ready.go and ready_proxied_server.go are slice literals wrapping a
role-built element, not independent places to forget a field, and they are not
counted.) A token field on a struct built in six places is silently 0 wherever a
site forgets it, and 0 is a LEGAL token (the migration-0054 backfill), so
nothing — no test, no client — can tell a forgotten one from a legacy row.
So the projection moved onto the canonical type behind ONE DOOR. types.Revision
is set by types.NewIssueDetails and nowhere else, because a struct literal with
an unset token publishes a wrong answer that looks exactly like a right one.
THE DOOR IS WRITTEN INTO THE DOCUMENT, not just into this description. A later
revision that wants the token on the list rows needs a list element that is NOT
the interchange element, and the listing's own prose now says so — together with
the rule a client needs meanwhile: model the absent member as ABSENT, never as
0, because 0 is a real token and a client that defaulted would compose guards
matching exactly the rows it is most dangerous to be wrong about.
THIS DELETES A PARITY DIVERGENCE RATHER THAN ADDING ONE. `bd show --json` has
published this token for as long as guarded writes have existed, through a
CLI-only wrapper, and `readsParityAllowlist` waived the difference with the note
"if the token is ever needed over HTTP, extend that surface and delete this
entry". The wrapper is gone, both front doors read the member off the one detail
seam, and the allowlist is now EMPTY — kept declared, because an empty allowlist
is a stronger statement than no allowlist.
The wire council's outstanding fix rides along, because it is the same member
family: `ApplyItemResult.revision` and both apply-item `expected_version`
members gained the DECODE-AS-64-BIT clause every other revision-bearing member
already carried. The batch spelling is where it bites hardest — a token
corrupted by an IEEE-754-double parser refuses the WHOLE plan rather than one
write.
Evidence. Four mutations, each watched to go red in the right place and only
there: the constructor stopping projecting reddens all three legs; the seam
regressing to a struct literal reddens the workapi pin ALONE and leaves the
httpapi case green, which is why both exist; `omitempty` reddens exactly the
legacy-zero arms; and adding the field to `types.IssueWithCounts` reddens the
new list case while leaving `TestRowVersionNeverSerialized` GREEN — the separate
unset field carries none of the forbidden spellings — and reddens
`TestWireTagBijection` only while the document has not caught up. That measured
pair is written into the new case's own comment, because it is why the case is
not redundant with either gate.
Real Dolt through a real `bd serve`: read the token, guard a patch with it, watch
it land; watch a write move it; watch the read and the write agree on the new
one; watch the stale guard 409 with `param: expected_version`; re-read and watch
the retry land. The same loop on `close`, and the ephemeral fallback — where the
token is a different column on a different table and the failure mode is a zero
rather than an absence.
Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run --new-from-rev=origin/main` on the touched packages (0
issues), the internal/types, internal/workapi, internal/httpapi and
internal/storage package runs, the byte-pinned `cmd/bd/protocol` corpus, and
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
'TestProxiedServerServeReadRevision|TestProxiedServerServeReadParity'` green
against real Dolt. The pre-commit hook's `go run golangci-lint@v2.10.1` fails on
this host with a toolchain mismatch unrelated to this change, so the hook's
contents were run by hand before committing with --no-verify.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>