beads/cmd/bd/protocol
Julian Knutsen b858a29e4a
fix(contracts): JSON contract fixes before 1.3.0 freezes them — string revision tokens, --set-metadata scalar typing, create --json nano timestamps (#6053)
* fix(metadata): restore v1.2.2 scalar typing for --set-metadata values

8ebd53e88 moved the CLI's metadata-edit helpers into
internal/storage/metadata.go and, in the move, replaced v1.2.2's
toJSONValue inference with a MetadataEditValue that always json.Marshals
the value as a string. The intent was GH#4146 (a numeric-looking id or a
version like "1e3" came back as a JSON number, breaking map[string]string
Go consumers), but it silently changed the shipped CLI contract:
`bd update --set-metadata k=5` started storing "5" instead of 5. That
regression shipped only in the deprecated/superseded v1.2.1, never in
v1.2.2, and 1.3.0 would freeze it.

Restore v1.2.2's inference body-for-body inside MetadataEditValue, so the
parity claim stays checkable against `git show v1.2.2:cmd/bd/update.go`:
"null" is JSON null, "true"/"false" are booleans, a spelling that scans
as a float AND is valid JSON on its own is emitted as that literal
(5 -> 5, 1e3 -> 1e3, 0.50 -> 0.50, while 05, +5 and NaN stay strings),
and everything else is a string. Every --set-metadata caller funnels
through this one function: embedded (cmd/bd/update.go ->
storage.ApplyMetadataEdits), proxied (parseSetMetadataFlags) and the
update executor's []string path.

GH#4146's concern is served by the explicitly typed routes, which are
untouched: --metadata / --metadata-json on the CLI (MergeMetadataJSON)
and the typed set map on the HTTP/Go path (applyTypedMetadataEdits).

No data migration: a "5" written by an in-window build is
indistinguishable from a string a user set intentionally through the
typed paths, so normalizing stored metadata would corrupt intended data.
Re-running the same --set-metadata k=5 retypes any given key.

Tests: new table in internal/storage/metadata_edit_value_test.go pinning
the v1.2.2 matrix plus an ApplyMetadataEdits end-to-end; the tests that
pinned the string-always behavior are flipped (domain/db mergeops suite,
update_lifecycle patch mapping, cmd/bd toJSONValue table) and the
embedded + proxied CLI suites now assert a stored JSON number. The
contract corpus is regenerated: its update/list/ready goldens run
`--set-metadata phase=2`, so `"phase": "2"` becomes `"phase": 2` and
nothing else moves.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(create): echo full-precision timestamps from bd create, not the DATETIME(0) re-read

b92442d1a routed `bd create` through issueops.Lifecycle, whose executors
build their result by re-reading the row they just wrote
(HydrateIssueOperationResult -> GetIssueInTx). created_at/updated_at are
DATETIME(0) columns, so that snapshot comes back at whole-second
precision and cmd/bd/create.go echoes it. v1.2.2 returned the caller's
own in-memory struct, which PrepareIssueForInsert stamps with
time.Now().UTC() including nanoseconds, so `bd create --json` used to
print e.g. 2026-08-28T12:34:56.789012345Z. Agents that create several
issues in a burst order them by exactly that fraction; rounded to the
second they all tie.

Restore the echo with OverlayCreateTimestamps: after hydration, put back
the created_at/updated_at (and closed_at, when the write set one) the
INSERT actually sent. Everything else on the snapshot stays DB-truth,
which is the facade's contract — only create, and only these fields.

Applied at every create body, not just the two the CLI reaches:
issueops.ExecuteCreate and ExecuteCreateBatch behind the dolt and
embedded-dolt stores, and the unit-of-work provider's own Create,
CreateBatch and batch-apply create item, which is what the proxied server
and POST /v0/beads/issues run on. Fixing only the shared executors would
have left the two bodies disagreeing about the same promise.

What is NOT changed, because it is not a regression: `bd show --json` and
`bd list --json` answered whole seconds in v1.2.2 too — they read the
column — and update/close/reopen re-read after writing there as well.
Widening the columns to DATETIME(6) would give reads sub-second times
too, but that is a schema migration on user Dolt DBs and touches paths
that deliberately compare at second precision; it is a 1.4 change.

The accepted skew, which predates this and stays: the engine ROUNDS to
the column rather than truncating, so a later read of the same row can
sit up to half a second either side of the create echo.

Tests: two new conformance cases, run on all three backends —
RunLifecycleCreateEchoesSubSecondTimestamps (a caller-supplied
nanosecond stamp must survive to the result exactly; the auto-stamped arm
stays a bounded smoke check, since requiring a non-zero fraction off the
clock is flaky by a billionth) and RunBatchCreatorEchoesSubSecondTimestamps
(per item, since both bodies build the result one snapshot at a time).
Plus a cmd/bd embedded test asserting `bd create --json` prints a
fractional part, and one httpapi assertion that the wire does not round
the role's snapshot on the way out. All four fail on the pre-fix tree.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(httpapi,types)!: revision / expected_version tokens are opaque JSON strings

The optimistic-concurrency token is minted by freshRowLock over the FULL
int64 range (crypto-random, non-zero) and published on the wire as a JSON
number: `revision` on responses, `expected_version` on guarded requests.
A JSON number does not survive a consumer that decodes into an IEEE-754
double — JavaScript's JSON.parse, Go's `any`, Python's `float`, jq. Live
tokens run past 5e17, where a double's ulp is already 64, so such a
client reads back a value NEAR the token, echoes that as its guard, and
earns a 409 against a row nobody else touched. The spec already carried
"DECODE IT AS A 64-BIT INTEGER" paragraphs telling clients to work around
this; that is a workaround for a wire type that should not have been a
number.

Emit and accept the token as a decimal STRING instead. It is documented
as opaque and EQUALITY-ONLY — compare it, never order or interpret it —
and a string round-trips exactly in every JSON consumer. It also leaves a
future backend free to mint a token that is not an int64 at all.

Internals are untouched: freshRowLock, the row_lock BIGINT column, its
migration, types.Issue.RowVersion and the ExpectedVersion *int64 guards
on the issueops requests all stay int64. Only the wire projection moves,
through the one spelling of the encoding — types.RevisionToken and
types.ParseRevisionToken.

STRICT STRING ONLY, with no transitional number-or-string acceptance.
This API already refuses unknown members by name and keeps one spelling
of the guard, and a number is precisely the shape a double-based client
has already rounded before it left the client — accepting it would
preserve the defect. A numeric guard is a 400 naming the member.

Chosen over clamping freshRowLock to 53 bits: a clamp does not fix rows
already minted with full-range tokens by in-window builds, so a JS
consumer reading one still rounds past 2^53 — repairing that would need a
row_lock normalization sweep over issues and wisps, a migration days
before a tag.

Surface: types.IssueDetails.Revision (what `bd show --json` prints and
GET /v0/beads/issues/{id} returns), the five hand-assigned httpapi
response fields, applyVersionGuardMember (now the reader for the batch
update item too, ahead of its typed decode, so a mistyped token still
earns a 400 naming the member), Problem.expected_version, and 14 OpenAPI
members regenerated through `make api-gen`. actual_version goes with them
— it is documented as "the `revision` the row was found holding", so
leaving it an integer would make the expected/actual pair disagree about
its own type; it is declared but never populated, so nothing changes
behaviorally.

Nothing shipped in a tagged release ever carried this member: v1.2.2 has
no internal/httpapi at all and no `revision` anywhere on the wire, so the
whole surface is in-window and can still be changed compatibly. Legacy
migration-0054 rows read as the string "0" with the same CAS semantics.

Corpus goldens are UNCHANGED: the canonicalizer already replaced any
`revision` value with the string "<REVISION>" whatever its JSON type.

Tests: types-level pins that the marshaled member matches `"revision":
"-?\d+"` and that RevisionToken/ParseRevisionToken round-trip MinInt64,
MaxInt64 and 2^53+1, plus a JS-realistic decode of 2^53+1 with a float64
control proving the token really is one a number would corrupt; httpapi
refusal tests for a numeric guard on update, close, reopen, delete and
both batch item kinds; a 409 echo asserted as the string; and the proxied
serve integration tests now splice the response's own token back in
verbatim rather than re-rendering a parsed one.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-29 05:20:27 +00:00
..
testdata/corpus fix(contracts): JSON contract fixes before 1.3.0 freezes them — string revision tokens, --set-metadata scalar typing, create --json nano timestamps (#6053) 2026-08-29 05:20:27 +00:00
assignee_test.go test(protocol): pin data-model + ready-front production-scar clauses (wy-nzybu) 2026-07-13 09:46:16 -07:00
blocked_status_test.go feat(test): parallelize protocol tests for 3x speedup (bd-dgp) 2026-02-27 20:04:00 -08:00
blocked_test.go feat(test): parallelize protocol tests for 3x speedup (bd-dgp) 2026-02-27 20:04:00 -08:00
blocking_semantics_test.go feat(test): parallelize protocol tests for 3x speedup (bd-dgp) 2026-02-27 20:04:00 -08:00
canonicalize_test.go test(protocol): make corpus determinism pure (bd-qq1qn) (#5281) 2026-08-02 07:14:30 -07:00
CATALOG.md Merge remote-tracking branch 'upstream/main' into pr-4232-fix 2026-07-13 20:43:10 -07:00
child_id_test.go test(protocol): pin data-model + ready-front production-scar clauses (wy-nzybu) 2026-07-13 09:46:16 -07:00
children_test.go fix(cli): implement children pretty and defer reason 2026-06-13 21:22:38 -07:00
close_guard_test.go feat(test): parallelize protocol tests for 3x speedup (bd-dgp) 2026-02-27 20:04:00 -08:00
comments_test.go feat(test): parallelize protocol tests for 3x speedup (bd-dgp) 2026-02-27 20:04:00 -08:00
corpus.go fix(contracts): JSON contract fixes before 1.3.0 freezes them — string revision tokens, --set-metadata scalar typing, create --json nano timestamps (#6053) 2026-08-29 05:20:27 +00:00
corpus_test.go test(protocol): make corpus determinism pure (bd-qq1qn) (#5281) 2026-08-02 07:14:30 -07:00
defer_test.go fix(cli): implement children pretty and defer reason 2026-06-13 21:22:38 -07:00
dep_identity_test.go test(protocol): pin data-model + ready-front production-scar clauses (wy-nzybu) 2026-07-13 09:46:16 -07:00
errors_contract_test.go test(protocol): pin §E/§M/§V conformance clauses at the CLI level (wy-ge2h8) 2026-07-13 10:30:24 -07:00
exit_codes_init_test.go test(protocol): pin §E/§M/§V conformance clauses at the CLI level (wy-ge2h8) 2026-07-13 10:30:24 -07:00
exit_codes_test.go feat(test): parallelize protocol tests for 3x speedup (bd-dgp) 2026-02-27 20:04:00 -08:00
helpers_test.go feat(storage): refuse test DBs on production dolt servers (AD-01) (#3632) 2026-07-24 01:28:51 -07:00
input_validation_test.go feat(test): parallelize protocol tests for 3x speedup (bd-dgp) 2026-02-27 20:04:00 -08:00
interchange_test.go test(protocol): pin the §J interchange clauses; fix the bd import header gap (wy-ltox1) 2026-07-13 11:20:06 -07:00
json_contract_test.go fix(show): flag comment_count as omitted when comments are not streamed (#4865) 2026-07-25 16:16:41 -07:00
lease_claim_test.go test: fix red main — init-cancel E2E deadline + reclaim JSON assertion (#5039) 2026-07-25 10:10:18 -07:00
lifecycle_test.go feat(test): parallelize protocol tests for 3x speedup (bd-dgp) 2026-02-27 20:04:00 -08:00
memory_contract_test.go test(protocol): pin §E/§M/§V conformance clauses at the CLI level (wy-ge2h8) 2026-07-13 10:30:24 -07:00
preservation_test.go test(protocol): realign show --json contract tests with count-only payload (wy-017ry) 2026-07-13 10:08:34 -07:00
ready_front_test.go test: make ready ordering setup deterministic (bd-y9cjq) (#5238) 2026-08-01 09:55:11 -07:00
roundtrip_test.go test(protocol): realign show --json contract tests with count-only payload (wy-017ry) 2026-07-13 10:08:34 -07:00
stale_test.go feat(test): parallelize protocol tests for 3x speedup (bd-dgp) 2026-02-27 20:04:00 -08:00
status_validation_test.go feat(test): parallelize protocol tests for 3x speedup (bd-dgp) 2026-02-27 20:04:00 -08:00
versioning_contract_test.go test(protocol): pin §E/§M/§V conformance clauses at the CLI level (wy-ge2h8) 2026-07-13 10:30:24 -07:00
wp4_helpers_test.go test(protocol): pin §E/§M/§V conformance clauses at the CLI level (wy-ge2h8) 2026-07-13 10:30:24 -07:00