diff --git a/backend/conformance/batch_creator_contract.go b/backend/conformance/batch_creator_contract.go index b0032ec38..0b48334f0 100644 --- a/backend/conformance/batch_creator_contract.go +++ b/backend/conformance/batch_creator_contract.go @@ -5,6 +5,7 @@ import ( "errors" "reflect" "testing" + "time" "github.com/steveyegge/beads/internal/storage" "github.com/steveyegge/beads/internal/types" @@ -539,6 +540,46 @@ func RunBatchCreatorDoesNotMutateTheCallerRequest(t *testing.T, ctx context.Cont } } +// RunBatchCreatorEchoesSubSecondTimestamps is the batch half of +// RunLifecycleCreateEchoesSubSecondTimestamps: every entry of a batch result +// carries the timestamps its write sent, at full precision, not the whole +// seconds the DATETIME(0) columns answer a re-read with. +// +// PER ITEM, because both bodies build the result one snapshot at a time and a +// fix applied to the first item only would still pass a check on result[0]. +func RunBatchCreatorEchoesSubSecondTimestamps(t *testing.T, ctx context.Context, fixture BatchCreatorFixture) { + t.Helper() + first := time.Date(2019, 3, 4, 5, 6, 7, 123456789, time.UTC) + second := time.Date(2020, 4, 5, 6, 7, 8, 246813579, time.UTC) + request := publicops.CreateBatchRequest{ + Actor: "batch-writer", + Items: []publicops.BatchCreateItem{ + batchCreatorItem(&types.Issue{Title: "nano first", Priority: 2, IssueType: types.TypeTask, CreatedAt: first, UpdatedAt: first}), + batchCreatorItem(&types.Issue{Title: "nano second", Priority: 2, IssueType: types.TypeTask, CreatedAt: second, UpdatedAt: second}), + }, + } + want := []time.Time{first, second} + result, err := fixture.BatchCreator.CreateBatch(ctx, request) + if err != nil { + t.Fatalf("CreateBatch with sub-second timestamps: %v", err) + } + if len(result.Issues) != len(want) { + t.Fatalf("CreateBatch returned %d issues for %d items", len(result.Issues), len(want)) + } + for i, issue := range result.Issues { + if issue == nil { + t.Fatalf("CreateBatch result issue %d is nil", i) + } + if !issue.CreatedAt.Equal(want[i]) { + t.Errorf("result issue %d created_at = %v, want %v exactly — a batch echo rounded to the second cannot order same-second creates", + i, issue.CreatedAt.UTC(), want[i]) + } + if !issue.UpdatedAt.Equal(want[i]) { + t.Errorf("result issue %d updated_at = %v, want %v exactly", i, issue.UpdatedAt.UTC(), want[i]) + } + } +} + // batchCreatorItem is the item every case builds, so a case names only the // fields it is about. func batchCreatorItem(issue *types.Issue) publicops.BatchCreateItem { diff --git a/backend/conformance/lifecycle_create_contract.go b/backend/conformance/lifecycle_create_contract.go index 831974df7..ca906424a 100644 --- a/backend/conformance/lifecycle_create_contract.go +++ b/backend/conformance/lifecycle_create_contract.go @@ -565,6 +565,79 @@ func assertLifecycleCreateMembers(t *testing.T, id, label string, issue *types.I } } +// RunLifecycleCreateEchoesSubSecondTimestamps pins that a create RESULT carries +// the timestamps the write actually sent, at full precision, rather than the +// whole seconds a read of the row answers with. +// +// created_at/updated_at are DATETIME(0) columns, so any snapshot built by +// re-reading the row it just wrote comes back rounded. That is fine for every +// read verb — show and list have always answered whole seconds — but create is +// different: its echo is the ONLY record a caller has of the instant the row was +// written, and agents order same-second creates by it. A backend that hydrates +// its create result and stops there silently loses that ordering, which is +// exactly the regression this case exists for. +// +// THE PRECISION PIN IS THE EXPLICIT ARM, not the auto-stamped one. A create that +// names no time is stamped from the clock, and whether that stamp happens to +// carry a non-zero fraction is not something a test can require without being +// flaky by a billionth; a caller-supplied time with nanoseconds in it is +// deterministic, and PrepareIssueForInsert preserves a non-zero input. The +// auto-stamp arm is kept as a bounded smoke check that the overlay did not +// replace the stamp with something unrelated. +// +// The stored ROW is deliberately NOT asserted here. What it rounds to is the +// column's business, and a later widening to DATETIME(6) must not have to edit +// this case. +func RunLifecycleCreateEchoesSubSecondTimestamps(t *testing.T, ctx context.Context, fixture LifecycleCreateFixture) { + t.Helper() + + id := fixture.IssuePrefix + "-lcc-nanoecho" + createdAt := time.Date(2019, 3, 4, 5, 6, 7, 123456789, time.UTC) + updatedAt := time.Date(2019, 3, 4, 5, 6, 8, 987654321, time.UTC) + created, err := fixture.Lifecycle.Create(ctx, publicops.CreateRequest{ + Actor: "writer", + ForceIDPrefix: true, + Issue: &types.Issue{ + ID: id, Title: "sub-second echo", Status: types.StatusOpen, Priority: 2, IssueType: types.TypeTask, + CreatedAt: createdAt, UpdatedAt: updatedAt, + }, + }) + if err != nil { + t.Fatalf("create %s with sub-second timestamps: %v", id, err) + } + if created.Issue == nil { + t.Fatalf("create %s returned no issue", id) + } + if !created.Issue.CreatedAt.Equal(createdAt) { + t.Errorf("%s create result created_at = %v, want %v exactly — the echo is the caller's only record of when the row was written, and rounding it to the second makes same-second creates unorderable", + id, created.Issue.CreatedAt.UTC(), createdAt) + } + if !created.Issue.UpdatedAt.Equal(updatedAt) { + t.Errorf("%s create result updated_at = %v, want %v exactly", id, created.Issue.UpdatedAt.UTC(), updatedAt) + } + + // The auto-stamped arm: no precision requirement, only that the overlay + // still hands back a stamp from this call rather than a stale or zero one. + stamped := fixture.IssuePrefix + "-lcc-nanoauto" + lower := time.Now().UTC().Add(-lifecycleCreateClockSlack) + auto, err := fixture.Lifecycle.Create(ctx, publicops.CreateRequest{ + Actor: "writer", + ForceIDPrefix: true, + Issue: lifecycleCreateIssue(stamped), + }) + if err != nil { + t.Fatalf("create %s without timestamps: %v", stamped, err) + } + upper := time.Now().UTC().Add(lifecycleCreateClockSlack) + if auto.Issue == nil { + t.Fatalf("create %s returned no issue", stamped) + } + echoed := auto.Issue.CreatedAt.UTC() + if echoed.Before(lower) || echoed.After(upper) { + t.Errorf("%s create result created_at = %v, want a stamp from this call between %v and %v", stamped, echoed, lower, upper) + } +} + // lifecycleCreateClockSlack widens the window the auto-stamp arm allows around a // creation time the implementation wrote from its own clock. Every backend here // stamps in Go, in this process, so the two clocks are the same one; the slack diff --git a/backend/conformance/role_bundle_cases.go b/backend/conformance/role_bundle_cases.go index fa457a011..2169bbe6a 100644 --- a/backend/conformance/role_bundle_cases.go +++ b/backend/conformance/role_bundle_cases.go @@ -94,6 +94,7 @@ var roleContractCases = []roleContract{ RunBatchCreatorRecordsOneHistoryEntry, RunBatchCreatorRecordsNoHistoryForAnEphemeralBatch, RunBatchCreatorDoesNotMutateTheCallerRequest, + RunBatchCreatorEchoesSubSecondTimestamps, ), roleCases("BlockingAnnotator", "BlockingAnnotator()", oncePerRole, @@ -412,6 +413,7 @@ var roleContractCases = []roleContract{ RunLifecycleCreateRefusesAForeignIDPrefix, RunLifecycleCreateInheritsParentLabels, RunLifecycleCreateWritesEveryScalarField, + RunLifecycleCreateEchoesSubSecondTimestamps, ), roleCases("LifecycleUpdate", "IssueLifecycle()", oncePerRole, diff --git a/cmd/bd/create_timestamp_precision_embedded_test.go b/cmd/bd/create_timestamp_precision_embedded_test.go new file mode 100644 index 000000000..b53e40f49 --- /dev/null +++ b/cmd/bd/create_timestamp_precision_embedded_test.go @@ -0,0 +1,121 @@ +//go:build cgo + +package main + +import ( + "encoding/json" + "os" + "strings" + "testing" + "time" +) + +// TestEmbeddedCreateJSONEchoesSubSecondTimestamps pins that `bd create --json` +// prints the instant the row was written, fraction included. +// +// created_at is a DATETIME(0) column, so anything that renders a create by +// re-reading the row it just wrote prints whole seconds. `bd create --json` has +// never done that: it echoes the stamp the write carried, and agents that create +// several issues in a burst order them by exactly that fraction. A build that +// echoed the re-read made every same-second create tie. +// +// THE ASSERTION IS THAT A FRACTION IS THERE AT ALL, across two creates. A +// truncating build prints a whole second every time, so it fails on the first +// one; a correct build prints a whole second only when the clock lands exactly +// on a second boundary, which is a billion-to-one per create and so a billion +// billion-to-one across the pair. Note that "two creates tie" is NOT usable as +// the assertion here even though it is the property that matters: each create is +// a subprocess that boots embedded Dolt, so consecutive runs are seconds apart +// and would not tie even when truncated. The executor-level proof of the tie +// lives in conformance.RunLifecycleCreateEchoesSubSecondTimestamps. +func TestEmbeddedCreateJSONEchoesSubSecondTimestamps(t *testing.T) { + if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" { + t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt create tests") + } + t.Parallel() + + bd := buildEmbeddedBD(t) + dir, _, _ := bdInit(t, bd, "--prefix", "cts") + + first := createdAtEcho(t, bd, dir, "first issue") + second := createdAtEcho(t, bd, dir, "second issue") + + firstAt := parseRFC3339Nano(t, "first", first.createdAt) + parseRFC3339Nano(t, "second", second.createdAt) + + fractional := false + for _, echo := range []createEcho{first, second} { + for _, member := range []struct{ name, value string }{ + {"created_at", echo.createdAt}, + {"updated_at", echo.updatedAt}, + } { + at := parseRFC3339Nano(t, echo.id+" "+member.name, member.value) + if at.Nanosecond() != 0 { + fractional = true + } + } + } + if !fractional { + t.Errorf("no timestamp `bd create --json` echoed across two creates carries a sub-second part "+ + "(%s created_at=%q updated_at=%q, %s created_at=%q updated_at=%q); the echo is being rounded to the "+ + "DATETIME(0) column, which is what makes same-second creates unorderable", + first.id, first.createdAt, first.updatedAt, second.id, second.createdAt, second.updatedAt) + } + + // The echo still names the row it created. It is not the SAME text: the + // column is DATETIME(0) and the engine ROUNDS to it rather than truncating, + // so a read can land up to half a second either side of the echo. That skew + // is v1.2.2 behavior and stays — `bd show` and `bd list` answer whole + // seconds, as they always have. What must hold is that the two name one + // instant, which a second of slack states without pinning either the digits + // or the rounding mode. + shown := bdShow(t, bd, dir, first.id) + if skew := shown.CreatedAt.UTC().Sub(firstAt.UTC()); skew > time.Second || skew < -time.Second { + t.Errorf("%s: create echoed created_at %v but show reports %v (%v apart); the two must name the same instant, "+ + "give or take the second-granular column", + first.id, firstAt, shown.CreatedAt.UTC(), skew) + } +} + +type createEcho struct { + id string + createdAt string + updatedAt string +} + +// createdAtEcho runs `bd create --json` and reads the timestamps as the RAW +// wire strings, because the defect is about the text a consumer parses: a +// decode into time.Time would accept both spellings silently. +func createdAtEcho(t *testing.T, bd, dir, title string) createEcho { + t.Helper() + out, err := bdRunWithFlockRetry(t, bd, dir, "create", "--json", title) + if err != nil { + t.Fatalf("bd create --json %q: %v\n%s", title, err, out) + } + s := string(out) + start := strings.Index(s, "{") + if start < 0 { + t.Fatalf("no JSON object in `bd create --json` output:\n%s", s) + } + var raw struct { + ID string `json:"id"` + CreatedAt string `json:"created_at"` + UpdatedAt string `json:"updated_at"` + } + if err := json.NewDecoder(strings.NewReader(s[start:])).Decode(&raw); err != nil { + t.Fatalf("parse `bd create --json` output: %v\nraw: %s", err, s[start:]) + } + if raw.ID == "" { + t.Fatalf("`bd create --json` echoed no id:\n%s", s) + } + return createEcho{id: raw.ID, createdAt: raw.CreatedAt, updatedAt: raw.UpdatedAt} +} + +func parseRFC3339Nano(t *testing.T, label, value string) time.Time { + t.Helper() + parsed, err := time.Parse(time.RFC3339Nano, value) + if err != nil { + t.Fatalf("%s created_at %q does not parse as RFC3339Nano: %v", label, value, err) + } + return parsed +} diff --git a/cmd/bd/metadata_edits_test.go b/cmd/bd/metadata_edits_test.go index fe1583c76..7967ae682 100644 --- a/cmd/bd/metadata_edits_test.go +++ b/cmd/bd/metadata_edits_test.go @@ -91,8 +91,8 @@ func TestApplyMetadataEdits_NumericValue(t *testing.T) { if err := json.Unmarshal(result, &data); err != nil { t.Fatalf("unmarshal: %v", err) } - if string(data["story_points"]) != `"5"` { - t.Errorf("expected \"5\", got %s", data["story_points"]) + if string(data["story_points"]) != `5` { + t.Errorf("expected the JSON number 5, got %s", data["story_points"]) } } @@ -106,8 +106,8 @@ func TestApplyMetadataEdits_BoolValue(t *testing.T) { if err := json.Unmarshal(result, &data); err != nil { t.Fatalf("unmarshal: %v", err) } - if string(data["urgent"]) != `"true"` { - t.Errorf("expected \"true\", got %s", data["urgent"]) + if string(data["urgent"]) != `true` { + t.Errorf("expected the JSON boolean true, got %s", data["urgent"]) } } @@ -121,8 +121,8 @@ func TestApplyMetadataEdits_NullValue(t *testing.T) { if err := json.Unmarshal(result, &data); err != nil { t.Fatalf("unmarshal: %v", err) } - if string(data["cleared"]) != `"null"` { - t.Errorf("expected \"null\", got %s", data["cleared"]) + if string(data["cleared"]) != `null` { + t.Errorf("expected JSON null, got %s", data["cleared"]) } } @@ -199,8 +199,8 @@ func TestApplyMetadataEdits_MultipleSetFlags(t *testing.T) { if string(data["sprint"]) != `"Q1"` { t.Errorf("expected \"Q1\", got %s", data["sprint"]) } - if string(data["priority"]) != `"2"` { - t.Errorf("expected \"2\", got %s", data["priority"]) + if string(data["priority"]) != `2` { + t.Errorf("expected the JSON number 2, got %s", data["priority"]) } } @@ -306,15 +306,15 @@ func TestToJSONValue(t *testing.T) { expected string }{ {"hello", `"hello"`}, - {"42", `"42"`}, - {"3.14", `"3.14"`}, - {"true", `"true"`}, - {"false", `"false"`}, - {"null", `"null"`}, + {"42", `42`}, + {"3.14", `3.14`}, + {"true", `true`}, + {"false", `false`}, + {"null", `null`}, {"", `""`}, {"hello world", `"hello world"`}, - {"0", `"0"`}, - {"-1", `"-1"`}, + {"0", `0`}, + {"-1", `-1`}, } for _, tt := range tests { t.Run(tt.input, func(t *testing.T) { diff --git a/cmd/bd/protocol/corpus.go b/cmd/bd/protocol/corpus.go index 111d828a7..dce3b1ef7 100644 --- a/cmd/bd/protocol/corpus.go +++ b/cmd/bd/protocol/corpus.go @@ -280,9 +280,11 @@ func canonValue(v any) any { // Replace per-write-random token values (the guarded-write revision / // row_lock) with a placeholder: pin that bd show exposes a revision // field, not its nondeterministic value. Unlike the provenance keys - // above this is unconditional — the value is a JSON number, not a - // string — but it stays a bare-key match, so keep the scope caveat in - // mind (see volatileValueKeys). + // above this is unconditional — the value is replaced whatever its + // JSON type, so the placeholder held when the token was a number and + // still holds now that it is a decimal string — but it stays a + // bare-key match, so keep the scope caveat in mind (see + // volatileValueKeys). if ph, ok := volatileValueKeys[k]; ok { t[k] = ph continue diff --git a/cmd/bd/protocol/testdata/corpus/envelope/list.json b/cmd/bd/protocol/testdata/corpus/envelope/list.json index ada8736aa..1daaf428a 100644 --- a/cmd/bd/protocol/testdata/corpus/envelope/list.json +++ b/cmd/bd/protocol/testdata/corpus/envelope/list.json @@ -43,7 +43,7 @@ "corpus-label" ], "metadata": { - "phase": "2" + "phase": 2 }, "owner": "test@protocol.test", "priority": 0, diff --git a/cmd/bd/protocol/testdata/corpus/envelope/ready.json b/cmd/bd/protocol/testdata/corpus/envelope/ready.json index ada8736aa..1daaf428a 100644 --- a/cmd/bd/protocol/testdata/corpus/envelope/ready.json +++ b/cmd/bd/protocol/testdata/corpus/envelope/ready.json @@ -43,7 +43,7 @@ "corpus-label" ], "metadata": { - "phase": "2" + "phase": 2 }, "owner": "test@protocol.test", "priority": 0, diff --git a/cmd/bd/protocol/testdata/corpus/envelope/update.json b/cmd/bd/protocol/testdata/corpus/envelope/update.json index 3a04ab63b..cf5ac889e 100644 --- a/cmd/bd/protocol/testdata/corpus/envelope/update.json +++ b/cmd/bd/protocol/testdata/corpus/envelope/update.json @@ -10,7 +10,7 @@ "corpus-label" ], "metadata": { - "phase": "2" + "phase": 2 }, "owner": "test@protocol.test", "priority": 0, diff --git a/cmd/bd/protocol/testdata/corpus/flat/list.json b/cmd/bd/protocol/testdata/corpus/flat/list.json index bd36a5b03..1caed738d 100644 --- a/cmd/bd/protocol/testdata/corpus/flat/list.json +++ b/cmd/bd/protocol/testdata/corpus/flat/list.json @@ -42,7 +42,7 @@ "corpus-label" ], "metadata": { - "phase": "2" + "phase": 2 }, "owner": "test@protocol.test", "priority": 0, diff --git a/cmd/bd/protocol/testdata/corpus/flat/ready.json b/cmd/bd/protocol/testdata/corpus/flat/ready.json index bd36a5b03..1caed738d 100644 --- a/cmd/bd/protocol/testdata/corpus/flat/ready.json +++ b/cmd/bd/protocol/testdata/corpus/flat/ready.json @@ -42,7 +42,7 @@ "corpus-label" ], "metadata": { - "phase": "2" + "phase": 2 }, "owner": "test@protocol.test", "priority": 0, diff --git a/cmd/bd/protocol/testdata/corpus/flat/update.json b/cmd/bd/protocol/testdata/corpus/flat/update.json index 649e19293..6d60adce5 100644 --- a/cmd/bd/protocol/testdata/corpus/flat/update.json +++ b/cmd/bd/protocol/testdata/corpus/flat/update.json @@ -9,7 +9,7 @@ "corpus-label" ], "metadata": { - "phase": "2" + "phase": 2 }, "owner": "test@protocol.test", "priority": 0, diff --git a/cmd/bd/protocol/testdata/corpus/manifest.json b/cmd/bd/protocol/testdata/corpus/manifest.json index 8c833360f..cbe1e1876 100644 --- a/cmd/bd/protocol/testdata/corpus/manifest.json +++ b/cmd/bd/protocol/testdata/corpus/manifest.json @@ -49,11 +49,11 @@ }, "envelope/list": { "cmd": "bd list --all --json", - "sha256": "9a06f84b6522a6ecfeb9290c0f1af6a89ac1f6e8c4ccb4318cb167a384d5bb90" + "sha256": "7317a1b51728df55aa64075f5099e3bf1cb90c14a0bbd900fdcb47824ef50d91" }, "envelope/ready": { "cmd": "bd ready --json", - "sha256": "9a06f84b6522a6ecfeb9290c0f1af6a89ac1f6e8c4ccb4318cb167a384d5bb90" + "sha256": "7317a1b51728df55aa64075f5099e3bf1cb90c14a0bbd900fdcb47824ef50d91" }, "envelope/reopen": { "cmd": "bd reopen --json corpus-closed", @@ -65,7 +65,7 @@ }, "envelope/update": { "cmd": "bd update corpus-root --json --priority 0 --add-label corpus-label --set-metadata phase=2 --description \"updated corpus root\"", - "sha256": "4abf4bd265741b310781019f1e4f35384af8470ffd7e2bef2017e7caeead15b2" + "sha256": "8f7693350a4e122e2bf38c4aa5c0439b50281b2bae4f2b18b437735c67e6db1d" }, "envelope/version": { "cmd": "bd version --json", @@ -117,11 +117,11 @@ }, "flat/list": { "cmd": "bd list --all --json", - "sha256": "6d7b3535591a4e85385a96cb02e220853d7e81f4212d4032d4567aa991418dae" + "sha256": "6a10f8d91e925c58515997cb76a4bb94caf3444925102df0247587353742ac0d" }, "flat/ready": { "cmd": "bd ready --json", - "sha256": "6d7b3535591a4e85385a96cb02e220853d7e81f4212d4032d4567aa991418dae" + "sha256": "6a10f8d91e925c58515997cb76a4bb94caf3444925102df0247587353742ac0d" }, "flat/reopen": { "cmd": "bd reopen --json corpus-closed", @@ -133,7 +133,7 @@ }, "flat/update": { "cmd": "bd update corpus-root --json --priority 0 --add-label corpus-label --set-metadata phase=2 --description \"updated corpus root\"", - "sha256": "77612a528e1f8f7944ede6e9cac476a37fb9009411502eb1501687d42928d7e0" + "sha256": "1d1f8e21df93df7a1885430fd804d2435cd3d7289cfcfcd1f4f511e241a8d805" }, "flat/version": { "cmd": "bd version --json", diff --git a/cmd/bd/serve_close_proxied_integration_test.go b/cmd/bd/serve_close_proxied_integration_test.go index d393b3dd2..9bb2d3249 100644 --- a/cmd/bd/serve_close_proxied_integration_test.go +++ b/cmd/bd/serve_close_proxied_integration_test.go @@ -7,7 +7,6 @@ import ( "fmt" "io" "net/http" - "strconv" "strings" "testing" ) @@ -376,12 +375,12 @@ func TestProxiedServerServeClose(t *testing.T) { } second := revisionOf(t, raw) if second == first { - t.Fatalf("revision = %d after a second write; a write that does not move the token makes every guard vacuous", second) + t.Fatalf("revision = %q after a second write; a write that does not move the token makes every guard vacuous", second) } // The stale close. Nothing is written, and the 409 names the member. status, problem := sp.closeIssue(t, issue.ID, - `{"actor":"http-agent","reason":"never","expected_version":`+strconv.FormatInt(first, 10)+`}`) + `{"actor":"http-agent","reason":"never","expected_version":`+revisionGuard(first)+`}`) if status != http.StatusConflict { t.Fatalf("stale close: status = %d, want 409: %v", status, problem) } @@ -396,7 +395,7 @@ func TestProxiedServerServeClose(t *testing.T) { // about whether this is still the row the caller read, which force says // nothing about. status, problem = sp.closeIssue(t, issue.ID, - `{"actor":"http-agent","force":true,"expected_version":`+strconv.FormatInt(first, 10)+`}`) + `{"actor":"http-agent","force":true,"expected_version":`+revisionGuard(first)+`}`) if status != http.StatusConflict { t.Fatalf("forced stale close: status = %d, want 409 — force bypasses policy, never a precondition: %v", status, problem) } @@ -406,13 +405,13 @@ func TestProxiedServerServeClose(t *testing.T) { // The fresh guard lands, and answers with the token the close minted. status, raw = sp.closeIssueRaw(t, issue.ID, - `{"actor":"http-agent","reason":"shipped","expected_version":`+strconv.FormatInt(second, 10)+`}`) + `{"actor":"http-agent","reason":"shipped","expected_version":`+revisionGuard(second)+`}`) if status != http.StatusOK { t.Fatalf("guarded close: status = %d, want 200: %s", status, raw) } closed := revisionOf(t, raw) if closed == second { - t.Errorf("revision = %d after a close that wrote; the token did not move", closed) + t.Errorf("revision = %q after a close that wrote; the token did not move", closed) } if shown := bdProxiedShow(t, bd, p.dir, issue.ID); string(shown.Status) != "closed" { t.Fatalf("the guarded close did not land: status %q", shown.Status) @@ -424,7 +423,7 @@ func TestProxiedServerServeClose(t *testing.T) { // itself has already invalidated — which is what lets a client read // `already_closed` as "and nothing has happened here since". status, problem = sp.closeIssue(t, issue.ID, - `{"actor":"http-agent","expected_version":`+strconv.FormatInt(second, 10)+`}`) + `{"actor":"http-agent","expected_version":`+revisionGuard(second)+`}`) if status != http.StatusConflict { t.Fatalf("guarded re-close with a pre-close token: status = %d, want 409: %v", status, problem) } @@ -440,13 +439,13 @@ func TestProxiedServerServeClose(t *testing.T) { } afterReplay := revisionOf(t, raw) if afterReplay != closed { - t.Errorf("revision = %d after an idempotent re-close, want the unchanged %d: a replay that writes nothing must not move the token", + t.Errorf("revision = %q after an idempotent re-close, want the unchanged %q: a replay that writes nothing must not move the token", afterReplay, closed) } // The reopen's own guard, on the mirror. Stale first. status, problem = sp.reopenIssue(t, issue.ID, - `{"actor":"http-agent","expected_version":`+strconv.FormatInt(second, 10)+`}`) + `{"actor":"http-agent","expected_version":`+revisionGuard(second)+`}`) if status != http.StatusConflict { t.Fatalf("stale reopen: status = %d, want 409: %v", status, problem) } @@ -460,12 +459,12 @@ func TestProxiedServerServeClose(t *testing.T) { // And the loop closes: the token the last successful write answered // with is the one that lands. status, raw = sp.reopenIssueRaw(t, issue.ID, - `{"actor":"http-agent","expected_version":`+strconv.FormatInt(afterReplay, 10)+`}`) + `{"actor":"http-agent","expected_version":`+revisionGuard(afterReplay)+`}`) if status != http.StatusOK { t.Fatalf("guarded reopen: status = %d, want 200: %s", status, raw) } if reopened := revisionOf(t, raw); reopened == afterReplay { - t.Errorf("revision = %d after a reopen that wrote; the token did not move", reopened) + t.Errorf("revision = %q after a reopen that wrote; the token did not move", reopened) } if shown := bdProxiedShow(t, bd, p.dir, issue.ID); string(shown.Status) != "open" || shown.CloseReason != "" { t.Errorf("the guarded reopen did not land: status %q reason %q", shown.Status, shown.CloseReason) diff --git a/cmd/bd/serve_delete_proxied_integration_test.go b/cmd/bd/serve_delete_proxied_integration_test.go index 6755c88cc..4118fe756 100644 --- a/cmd/bd/serve_delete_proxied_integration_test.go +++ b/cmd/bd/serve_delete_proxied_integration_test.go @@ -6,7 +6,6 @@ import ( "encoding/json" "io" "net/http" - "strconv" "strings" "testing" ) @@ -90,10 +89,10 @@ func TestProxiedServerServeDelete(t *testing.T) { } second := revisionOf(t, raw) if second == first { - t.Fatalf("revision = %d after a second write; a token that does not move makes the guard vacuous", second) + t.Fatalf("revision = %q after a second write; a token that does not move makes the guard vacuous", second) } - status, raw = sp.deleteIssues(t, `{"ids":["`+issue.ID+`"],"actor":"http-agent","expected_version":`+strconv.FormatInt(first, 10)+`}`) + status, raw = sp.deleteIssues(t, `{"ids":["`+issue.ID+`"],"actor":"http-agent","expected_version":`+revisionGuard(first)+`}`) if status != http.StatusConflict { t.Fatalf("stale delete: status = %d, want 409: %s", status, raw) } @@ -108,7 +107,7 @@ func TestProxiedServerServeDelete(t *testing.T) { // to do about OTHER beads; neither says the bead named is still the one // the caller read. for _, flags := range []string{`"force":true`, `"cascade":true`, `"force":true,"cascade":true`} { - status, raw = sp.deleteIssues(t, `{"ids":["`+issue.ID+`"],`+flags+`,"expected_version":`+strconv.FormatInt(first, 10)+`}`) + status, raw = sp.deleteIssues(t, `{"ids":["`+issue.ID+`"],`+flags+`,"expected_version":`+revisionGuard(first)+`}`) if status != http.StatusConflict { t.Fatalf("stale delete with %s: status = %d, want 409: %s", flags, status, raw) } @@ -118,14 +117,14 @@ func TestProxiedServerServeDelete(t *testing.T) { // A DRY RUN REFUSES WHERE THE REAL RUN WOULD, which is the whole value // of previewing a guarded delete: a clean preview means the real request // will not stop half-explained. - status, raw = sp.deleteIssues(t, `{"ids":["`+issue.ID+`"],"dry_run":true,"expected_version":`+strconv.FormatInt(first, 10)+`}`) + status, raw = sp.deleteIssues(t, `{"ids":["`+issue.ID+`"],"dry_run":true,"expected_version":`+revisionGuard(first)+`}`) if status != http.StatusConflict { t.Fatalf("stale dry run: status = %d, want 409: %s", status, raw) } stillThere(t, bd, p.dir, issue.ID) // And the fresh token lands. - status, raw = sp.deleteIssues(t, `{"ids":["`+issue.ID+`"],"actor":"http-agent","expected_version":`+strconv.FormatInt(second, 10)+`}`) + status, raw = sp.deleteIssues(t, `{"ids":["`+issue.ID+`"],"actor":"http-agent","expected_version":`+revisionGuard(second)+`}`) if status != http.StatusOK { t.Fatalf("guarded delete: status = %d, want 200: %s", status, raw) } @@ -149,7 +148,7 @@ func TestProxiedServerServeDelete(t *testing.T) { a := bdProxiedCreate(t, bd, p.dir, "arity a", "-p", "2") b := bdProxiedCreate(t, bd, p.dir, "arity b", "-p", "2") - status, raw := sp.deleteIssues(t, `{"ids":["`+a.ID+`","`+b.ID+`"],"expected_version":41}`) + status, raw := sp.deleteIssues(t, `{"ids":["`+a.ID+`","`+b.ID+`"],"expected_version":"41"}`) if status != http.StatusBadRequest { t.Fatalf("status = %d, want 400: %s", status, raw) } @@ -183,7 +182,7 @@ func TestProxiedServerServeDelete(t *testing.T) { token := revisionOf(t, raw) status, raw = sp.deleteIssues(t, - `{"ids":["`+issue.ID+`","`+issue.ID+`"],"actor":"http-agent","expected_version":`+strconv.FormatInt(token, 10)+`}`) + `{"ids":["`+issue.ID+`","`+issue.ID+`"],"actor":"http-agent","expected_version":`+revisionGuard(token)+`}`) if status != http.StatusOK { t.Fatalf("status = %d, want 200 — duplicates collapse to one bead: %s", status, raw) } @@ -194,7 +193,7 @@ func TestProxiedServerServeDelete(t *testing.T) { // be stale about, so the caller is told about the typo rather than about a // version it cannot check. t.Run("an absent id outranks the guard", func(t *testing.T) { - status, raw := sp.deleteIssues(t, `{"ids":["bd-nosuchbead"],"expected_version":41}`) + status, raw := sp.deleteIssues(t, `{"ids":["bd-nosuchbead"],"expected_version":"41"}`) if status != http.StatusNotFound { t.Fatalf("status = %d, want 404: %s", status, raw) } diff --git a/cmd/bd/serve_read_revision_proxied_integration_test.go b/cmd/bd/serve_read_revision_proxied_integration_test.go index 18d864c23..c1d96a487 100644 --- a/cmd/bd/serve_read_revision_proxied_integration_test.go +++ b/cmd/bd/serve_read_revision_proxied_integration_test.go @@ -6,7 +6,6 @@ import ( "encoding/json" "io" "net/http" - "strconv" "testing" ) @@ -74,13 +73,13 @@ func TestProxiedServerServeReadRevision(t *testing.T) { // mean the handler published a field it never filled in rather than // the row's value — the one failure that a legacy-zero row makes // otherwise indistinguishable from success. - if read == 0 { - t.Fatalf("revision = 0 on a row this test just created; the token was not read off the row: %s", raw) + if read == "0" { + t.Fatalf("revision = \"0\" on a row this test just created; the token was not read off the row: %s", raw) } // The guard the read sourced. It lands, which is half the claim. writeStatus, written := sp.updateIssueRaw(t, issue.ID, - `{"actor":"http-agent","expected_version":`+strconv.FormatInt(read, 10)+`,"patch":{"title":"guarded by a read"}}`) + `{"actor":"http-agent","expected_version":`+revisionGuard(read)+`,"patch":{"title":"guarded by a read"}}`) if writeStatus != http.StatusOK { t.Fatalf("guarded write: status = %d, want 200: %s", writeStatus, written) } @@ -95,14 +94,14 @@ func TestProxiedServerServeReadRevision(t *testing.T) { // diverged from here on. wrote := revisionOf(t, written) if wrote == read { - t.Fatalf("revision = %d after a write; a write that does not move the token makes every guard vacuous", wrote) + t.Fatalf("revision = %q after a write; a write that does not move the token makes every guard vacuous", wrote) } reStatus, reRaw := sp.getIssueRaw(t, issue.ID) if reStatus != http.StatusOK { t.Fatalf("re-read: status = %d, want 200: %s", reStatus, reRaw) } if reRead := revisionOf(t, reRaw); reRead != wrote { - t.Errorf("the read answers %d and the write answered %d; the two must be one token", reRead, wrote) + t.Errorf("the read answers %q and the write answered %q; the two must be one token", reRead, wrote) } // THE OTHER HALF: a concurrent actor moves the row, and the token the @@ -117,7 +116,7 @@ func TestProxiedServerServeReadRevision(t *testing.T) { } conflictStatus, problem := sp.updateIssue(t, issue.ID, - `{"actor":"http-agent","expected_version":`+strconv.FormatInt(wrote, 10)+`,"patch":{"title":"never"}}`) + `{"actor":"http-agent","expected_version":`+revisionGuard(wrote)+`,"patch":{"title":"never"}}`) if conflictStatus != http.StatusConflict { t.Fatalf("stale guard: status = %d, want 409: %v", conflictStatus, problem) } @@ -139,7 +138,7 @@ func TestProxiedServerServeReadRevision(t *testing.T) { } fresh := revisionOf(t, freshRaw) retryStatus, retry := sp.updateIssue(t, issue.ID, - `{"actor":"http-agent","expected_version":`+strconv.FormatInt(fresh, 10)+`,"patch":{"title":"retried"}}`) + `{"actor":"http-agent","expected_version":`+revisionGuard(fresh)+`,"patch":{"title":"retried"}}`) if retryStatus != http.StatusOK { t.Fatalf("the retry: status = %d, want 200: %v", retryStatus, retry) } @@ -164,7 +163,7 @@ func TestProxiedServerServeReadRevision(t *testing.T) { read := revisionOf(t, raw) closeStatus, closed := sp.closeIssueRaw(t, issue.ID, - `{"actor":"http-agent","expected_version":`+strconv.FormatInt(read, 10)+`}`) + `{"actor":"http-agent","expected_version":`+revisionGuard(read)+`}`) if closeStatus != http.StatusOK { t.Fatalf("guarded close: status = %d, want 200: %s", closeStatus, closed) } @@ -180,7 +179,7 @@ func TestProxiedServerServeReadRevision(t *testing.T) { t.Fatalf("read after close: status = %d, want 200: %s", afterStatus, afterRaw) } if got, want := revisionOf(t, afterRaw), revisionOf(t, closed); got != want { - t.Errorf("the read answers %d and the close answered %d; the two must be one token", got, want) + t.Errorf("the read answers %q and the close answered %q; the two must be one token", got, want) } }) @@ -199,9 +198,9 @@ func TestProxiedServerServeReadRevision(t *testing.T) { t.Fatalf("GET wisp: status = %d, want 200: %s", status, raw) } var body struct { - ID string `json:"id"` - Ephemeral bool `json:"ephemeral"` - Revision *int64 `json:"revision"` + ID string `json:"id"` + Ephemeral bool `json:"ephemeral"` + Revision *string `json:"revision"` } if err := json.Unmarshal(raw, &body); err != nil { t.Fatalf("decode wisp detail %q: %v", raw, err) @@ -212,8 +211,9 @@ func TestProxiedServerServeReadRevision(t *testing.T) { if body.Revision == nil { t.Fatalf("the wisp detail carries no `revision`: %s", raw) } - if *body.Revision == 0 { - t.Errorf("revision = 0 on a wisp this test just created; the fallback read the wrong plane's token: %s", raw) + if *body.Revision == "0" { + t.Errorf("revision = %q on a wisp this test just created; the fallback read the wrong plane's token: %s", + *body.Revision, raw) } }) } diff --git a/cmd/bd/serve_update_proxied_integration_test.go b/cmd/bd/serve_update_proxied_integration_test.go index fc17ae02c..bb59a0553 100644 --- a/cmd/bd/serve_update_proxied_integration_test.go +++ b/cmd/bd/serve_update_proxied_integration_test.go @@ -54,22 +54,25 @@ func (sp *serveProcess) updateIssue(t *testing.T, id, body string) (int, map[str return status, m } -// revisionOf decodes the `revision` token as the 64-BIT INTEGER the document -// declares it to be, which is the whole reason this reads the raw bytes. +// revisionOf decodes the `revision` token as the decimal STRING the document +// declares it to be, and hands it back unparsed — which is exactly what a +// client is supposed to do with it. // -// Decoding it into an `any` yields a float64, and live tokens run past 5e17 -// where a float64's ulp is already 64 — so the value that comes back is NEAR -// the token and is not it, and a guard composed from it is refused against a -// row nothing else touched. That is not hypothetical: it is how the first -// version of the case below failed. +// It reads the raw bytes rather than going through an `any`, and that is still +// the point: `any` would hand back the string's text now, but it handed back a +// float64 when the member was a number, and live tokens run past 5e17 where a +// float64's ulp is already 64 — so the value that came back was NEAR the token +// and was not it, and a guard composed from it was refused against a row +// nothing else touched. That is not hypothetical: it is how the first version +// of the case below failed, and it is why the member is a string. // // NEVER ORDER IT AND NEVER COMPUTE ONE. The token is opaque and compared for // EQUALITY alone, so "the previous revision" is not `revision - 1`; it is the // value an earlier write answered with, which is what the case below uses. -func revisionOf(t *testing.T, raw []byte) int64 { +func revisionOf(t *testing.T, raw []byte) string { t.Helper() var body struct { - Revision *int64 `json:"revision"` + Revision *string `json:"revision"` } if err := json.Unmarshal(raw, &body); err != nil { t.Fatalf("decode revision from %q: %v", raw, err) @@ -80,6 +83,11 @@ func revisionOf(t *testing.T, raw []byte) int64 { return *body.Revision } +// revisionGuard spells a token as the JSON member a request carries, quotes and +// all, so a case composes its guard by splicing the response's own value in +// rather than by re-rendering a parsed one. +func revisionGuard(token string) string { return strconv.Quote(token) } + func TestProxiedServerServeUpdate(t *testing.T) { requireSharedProxiedServer(t) t.Parallel() @@ -393,11 +401,11 @@ func TestProxiedServerServeUpdate(t *testing.T) { } second := revisionOf(t, concurrent) if second == first { - t.Fatalf("revision = %d after a second write; a write that does not move the token makes every guard vacuous", second) + t.Fatalf("revision = %q after a second write; a write that does not move the token makes every guard vacuous", second) } conflictStatus, problem := sp.updateIssue(t, issue.ID, - `{"actor":"http-agent","expected_version":`+strconv.FormatInt(first, 10)+`,"patch":{"title":"never"}}`) + `{"actor":"http-agent","expected_version":`+revisionGuard(first)+`,"patch":{"title":"never"}}`) if conflictStatus != http.StatusConflict { t.Fatalf("stale guard: status = %d, want 409: %v", conflictStatus, problem) } @@ -414,7 +422,7 @@ func TestProxiedServerServeUpdate(t *testing.T) { // The loop closes: re-read the token the last write answered with and // the guarded write lands. freshStatus, fresh := sp.updateIssue(t, issue.ID, - `{"actor":"http-agent","expected_version":`+strconv.FormatInt(second, 10)+`,"patch":{"title":"guarded"}}`) + `{"actor":"http-agent","expected_version":`+revisionGuard(second)+`,"patch":{"title":"guarded"}}`) if freshStatus != http.StatusOK { t.Fatalf("guarded update: status = %d, want 200: %v", freshStatus, fresh) } diff --git a/cmd/bd/show_details_json_test.go b/cmd/bd/show_details_json_test.go index 5992a23e3..0b47649bc 100644 --- a/cmd/bd/show_details_json_test.go +++ b/cmd/bd/show_details_json_test.go @@ -67,11 +67,16 @@ func TestShowJSONDetailsCarryTheRevisionToken(t *testing.T) { token int64 want string }{ - {"a mutated row", 123456789, `"revision":123456789`}, + {"a mutated row", 123456789, `"revision":"123456789"`}, // 0 is the migration-0054 backfill token, a legitimate CAS value a // guarded client must be able to read. No omitempty, so it is emitted - // rather than standing in for "this producer has no token". - {"a legacy un-mutated row", 0, `"revision":0`}, + // rather than standing in for "this producer has no token", and it is + // the STRING "0" rather than the number. + {"a legacy un-mutated row", 0, `"revision":"0"`}, + // The token this spelling exists for: 2^53+1 is the smallest int64 a + // double-based `jq`/JavaScript consumer of `bd show --json` cannot + // hold. + {"a token past 2^53", 9007199254740993, `"revision":"9007199254740993"`}, } { t.Run(tc.name, func(t *testing.T) { details := types.NewIssueDetails(types.Issue{ diff --git a/cmd/bd/update.go b/cmd/bd/update.go index 9c0d0be84..a52369359 100644 --- a/cmd/bd/update.go +++ b/cmd/bd/update.go @@ -790,7 +790,8 @@ func optionalTimeField(value any) (issueops.Field[*time.Time], bool) { // parseSetMetadataFlags splits --set-metadata key=value pairs, matching // storage.ApplyMetadataEdits' parsing so the CLI contract is unchanged. Values -// are always stored as JSON strings (GH#4146). +// are typed by storage.MetadataEditValue, which infers null/bool/number from +// the spelling and falls back to a string. func parseSetMetadataFlags(flags []string) (map[string]json.RawMessage, error) { set := make(map[string]json.RawMessage, len(flags)) for _, flag := range flags { @@ -917,9 +918,10 @@ func applyMetadataEdits(existing json.RawMessage, setFlags, unsetFlags []string) return storage.ApplyMetadataEdits(existing, setFlags, unsetFlags) } -// toJSONValue stores a CLI metadata value as a JSON string. -// Previous behavior inferred types (numbers, booleans) from content, -// which silently broke map[string]string round-trips (GH#4146). +// toJSONValue converts a CLI metadata value to its most appropriate JSON +// representation: numbers, booleans and null keep their type, everything else +// becomes a JSON string. +// Thin alias over the shared storage helper (also used in-transaction by issueops). func toJSONValue(s string) json.RawMessage { return storage.MetadataEditValue(s) } diff --git a/cmd/bd/update_embedded_test.go b/cmd/bd/update_embedded_test.go index 688cb40a2..0ce5ee9d2 100644 --- a/cmd/bd/update_embedded_test.go +++ b/cmd/bd/update_embedded_test.go @@ -259,6 +259,7 @@ func TestEmbeddedUpdate(t *testing.T) { "--await-id", "run-123", "--due", "2099-01-15", "--set-metadata", "team=platform", + "--set-metadata", "score=99", "--unset-metadata", "remove", "--no-history", ) @@ -310,6 +311,11 @@ func TestEmbeddedUpdate(t *testing.T) { if metadata["team"] != "platform" { t.Errorf("metadata team = %v, want platform", metadata["team"]) } + // --set-metadata infers scalar types (the v1.2.2 contract): 99 lands as a + // JSON number, not the string "99". + if metadata["score"] != float64(99) { + t.Errorf("metadata score = %#v, want the JSON number 99", metadata["score"]) + } if _, ok := metadata["remove"]; ok { t.Errorf("metadata still contains removed key: %v", metadata) } diff --git a/cmd/bd/update_lifecycle_test.go b/cmd/bd/update_lifecycle_test.go index 2811665da..7418e752e 100644 --- a/cmd/bd/update_lifecycle_test.go +++ b/cmd/bd/update_lifecycle_test.go @@ -269,7 +269,7 @@ func TestBuildUpdatePatchMapsSupportedFields(t *testing.T) { updates: map[string]any{storageissueops.OpSetMetadata: []string{"one=value", "two=42"}}, want: issueops.IssuePatch{Metadata: issueops.MetadataPatch{Set: map[string]json.RawMessage{ "one": json.RawMessage(`"value"`), - "two": json.RawMessage(`"42"`), + "two": json.RawMessage(`42`), }}}, }, { diff --git a/cmd/bd/update_proxied_integration_test.go b/cmd/bd/update_proxied_integration_test.go index 298f1bc82..da954fd18 100644 --- a/cmd/bd/update_proxied_integration_test.go +++ b/cmd/bd/update_proxied_integration_test.go @@ -706,8 +706,8 @@ func TestProxiedServerUpdate2(t *testing.T) { if got["tier"] != "gold" { t.Errorf("metadata[tier]: got %v, want %q", got["tier"], "gold") } - if got["score"] != "99" { - t.Errorf("metadata[score]: got %v, want %q (--set-metadata always stores string values)", got["score"], "99") + if got["score"] != float64(99) { + t.Errorf("metadata[score]: got %#v, want the JSON number 99 (--set-metadata infers scalar types)", got["score"]) } }) diff --git a/docs/reference/json-schema.md b/docs/reference/json-schema.md index 90550e510..c21170240 100644 --- a/docs/reference/json-schema.md +++ b/docs/reference/json-schema.md @@ -197,8 +197,9 @@ change here is a breaking wire change). Same required fields as list items, plus: - `description` (string) - `acceptance_criteria` (string) -- `revision` (number): guarded-write optimistic-concurrency token; always - present, including a legacy `0` +- `revision` (string): guarded-write optimistic-concurrency token, an opaque + decimal string compared by equality and echoed back verbatim; always present, + including a legacy `"0"` - `dependencies` (object[]): Full dependency records - `comments` (object[]): Comment thread — present only with `--include-comments`; the default response returns `comment_count` only (count-only, be-ijck6q) diff --git a/internal/httpapi/apigen/types.gen.go b/internal/httpapi/apigen/types.gen.go index 75b256751..fd5d3a14f 100644 --- a/internal/httpapi/apigen/types.gen.go +++ b/internal/httpapi/apigen/types.gen.go @@ -387,8 +387,8 @@ type ApplyCloseItem struct { // // THERE IS DELIBERATELY NO `expected_status` HERE. A close is idempotent — re-closing a closed issue is `changed: false` — so a guard spelled to refuse an already-closed row is asking for a REFUSAL where this verb answers with a no-op. That belongs on an `update` item whose `patch.status` crosses into the done category. // - // DECODE IT AS A 64-BIT INTEGER, on `ApplyUpdateItem.expected_version`'s terms, including its note that a corrupted token here costs the whole plan. - ExpectedVersion *int64 `json:"expected_version,omitempty"` + // IT IS A STRING, and it must be the `revision` string a response carried, verbatim. A JSON number — or any other type — is a `400` naming this member. The token spans the FULL 64-bit range, so a number would be rounded past 2^53 by an IEEE-754-double parser and the guard would miss a row nothing else touched; a string round-trips exactly in every consumer. + ExpectedVersion *string `json:"expected_version,omitempty"` // Force Bypasses close policy — the open-children refusal and the live-blocker refusal — and nothing else. // @@ -583,8 +583,8 @@ type ApplyItemResult struct { // // It is ALWAYS PRESENT, including as 0. Zero is a real value — a legacy row backfilled and not mutated since — and a `dep_add` is 0 too, because an edge acts on no single row's version. An absent member would be ambiguous between the two. // - // DECODE IT AS A 64-BIT INTEGER, for the reason `UpdateIssueRequest.expected_version` spells out: an IEEE-754-double parser corrupts it silently, and the corruption only shows up as a `precondition_failed` on the NEXT request. This member is the one every other `revision` on the surface is spelled against, so the warning belongs here most of all — a client that reads it through a lossy parser here carries the damage into every guard it composes. - Revision int64 `json:"revision"` + // IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or `"0"` for a legacy migration-0054 row. Send it back verbatim as an `expected_version`; do not parse it into a number. A JSON number would not survive the trip: the token spans the FULL 64-bit range, and an IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's `float` — rounds anything past 2^53 to a value NEAR the token that is not it, so a guard composed from it is refused against a row nothing else touched. A string round-trips exactly in every consumer. + Revision string `json:"revision"` } // ApplyItemResultKind Echoes the item's kind, so a caller walking the results does not have to walk the request alongside them. @@ -704,8 +704,8 @@ type ApplyUpdateItem struct { // // `expected_status` and `expected_assignee` carry no such rule, because a caller CAN know what its own earlier item set them to. // - // DECODE IT AS A 64-BIT INTEGER, for the reason `UpdateIssueRequest.expected_version` spells out. It bites harder here than anywhere else on the surface: a corrupted token refuses the WHOLE plan rather than one write, so a client with a lossy parser loses every item of every batch it guards. - ExpectedVersion *int64 `json:"expected_version,omitempty"` + // IT IS A STRING, and it must be the `revision` string a response carried, verbatim. A JSON number — or any other type — is a `400` naming this member. The token spans the FULL 64-bit range, so a number would be rounded past 2^53 by an IEEE-754-double parser and the guard would miss a row nothing else touched; a string round-trips exactly in every consumer. + ExpectedVersion *string `json:"expected_version,omitempty"` // ForceAssigneeTransfer Bypasses ONLY a genuine transfer away from a live foreign in-progress owner. Reasserting the exact current assignee is idempotent and needs no force. It requires `patch.assignee` — a request setting it without one is a `400` — and it must be false when `expected_assignee` is sent. ForceAssigneeTransfer *bool `json:"force_assignee_transfer,omitempty"` @@ -872,10 +872,10 @@ type CloseIssueRequest struct { // // IT IS CHECKED BEFORE THE IDEMPOTENT RE-CLOSE, which is the one place this guard differs from the update's. A re-close of a row somebody else has moved since the caller read it is a `409` and not the 200-with-`already_closed` the same body earns without a guard: a replay whose premise has expired is a refusal the caller wants to see, and it is the only way `already_closed` can be trusted as "nothing has happened here since". // - // The token is the `revision` this operation's own response carries. Compose the next expectation from the value a write ANSWERED with, never from a number the client incremented itself: the token is OPAQUE and compared for equality alone, so it has no predecessor a client can compute. A first guarded close seeds itself from `GET /v0/beads/issues/{id}`'s `revision` — the read that sources a guard — or, for a chain already mid-flight, from an unguarded lifecycle write or `POST /v0/beads/issues:batchApply`'s `ApplyItemResult.revision`. + // The token is the `revision` this operation's own response carries. Compose the next expectation from the value a write ANSWERED with, never from one the client composed itself: the token is OPAQUE and compared for equality alone, so it has no predecessor a client can compute. A first guarded close seeds itself from `GET /v0/beads/issues/{id}`'s `revision` — the read that sources a guard — or, for a chain already mid-flight, from an unguarded lifecycle write or `POST /v0/beads/issues:batchApply`'s `ApplyItemResult.revision`. // - // DECODE IT AS A 64-BIT INTEGER, for the reason `UpdateIssueRequest.expected_version` spells out: an IEEE-754-double parser corrupts it silently, and the corruption only surfaces as a `precondition_failed` on the NEXT request. - ExpectedVersion *int64 `json:"expected_version,omitempty"` + // IT IS A STRING, and it must be the `revision` string a response carried, verbatim. A JSON number — or any other type — is a `400` naming this member. The token spans the FULL 64-bit range, so a number would be rounded past 2^53 by an IEEE-754-double parser and the guard would miss a row nothing else touched; a string round-trips exactly in every consumer. + ExpectedVersion *string `json:"expected_version,omitempty"` // Force Bypass close policy — the open-children refusal and the live-blocker refusal — and nothing else. The refusals are the ROLE's, so this endpoint cannot skip a guard by forgetting one exists. A forced close still reports `open_children`. // @@ -904,8 +904,8 @@ type CloseIssueResponse struct { // // It is here because `expected_version` is: a guard whose token no response carries is a guard a caller cannot fill, and a close-then-reopen or close-then-delete chain has to compose its next expectation from the value the close ANSWERED with. An idempotent re-close carries one too — the row still has a version, and a caller that guarded a replay needs the token whether or not the replay wrote. // - // DECODE IT AS A 64-BIT INTEGER, for the reason `UpdateIssueResponse.revision` spells out. - Revision int64 `json:"revision"` + // IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or `"0"` for a legacy migration-0054 row. Send it back verbatim as an `expected_version`; do not parse it into a number. A JSON number would not survive the trip: the token spans the FULL 64-bit range, and an IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's `float` — rounds anything past 2^53 to a value NEAR the token that is not it, so a guard composed from it is refused against a row nothing else touched. A string round-trips exactly in every consumer. + Revision string `json:"revision"` } // CloseOutcome What happened to ONE requested item. @@ -1173,8 +1173,10 @@ type DeleteIssuesRequest struct { // // IT GUARDS LIFECYCLE STATE, NOT THE GRAPH. The token is reminted by status, assignee and started-at writes and deliberately not by label, dependency or rename writes, so a match does not promise the bead's edges are the ones you saw. // - // The token is the `revision` a lifecycle write answers with, and the one `GET /v0/beads/issues/{id}` publishes — which is where a delete guard should seed itself, since reading the bead before erasing it is the only way to be sure it is the bead you meant. DECODE IT AS A 64-BIT INTEGER, for the reason `UpdateIssueRequest.expected_version` spells out. - ExpectedVersion *int64 `json:"expected_version,omitempty"` + // The token is the `revision` a lifecycle write answers with, and the one `GET /v0/beads/issues/{id}` publishes — which is where a delete guard should seed itself, since reading the bead before erasing it is the only way to be sure it is the bead you meant. + // + // IT IS A STRING, and it must be the `revision` string a response carried, verbatim. A JSON number — or any other type — is a `400` naming this member. The token spans the FULL 64-bit range, so a number would be rounded past 2^53 by an IEEE-754-double parser and the guard would miss a row nothing else touched; a string round-trips exactly in every consumer. + ExpectedVersion *string `json:"expected_version,omitempty"` // Force Delete the named beads and leave their dependents ORPHANED, reported in `orphaned`. Without it and without `cascade`, a named bead with a dependent the request did not name is refused. // @@ -1463,7 +1465,9 @@ type Problem struct { // PRESENT ONLY WHERE THE REFUSING OPERATION CAN REPORT IT. An all-or-nothing operation rolls its transaction back, so a value read after the fact would describe a row the refusal never saw; where the role behind an operation does not carry the observed value, this member is omitted rather than reconstructed. Its absence therefore means "this server cannot tell you what it found", never "it found zero". // // NO v0 OPERATION EMITS IT TODAY, nor `actual_status` or `actual_assignee`. Every operation that publishes a guard refuses all-or-nothing, and none of the roles behind them carries the observed value out of the rolled-back transaction. The three members are declared so that an operation whose role CAN report what it found is an addition rather than a wire change — a client must not wait for them, and must never read their absence as a value. - ActualVersion *int64 `json:"actual_version,omitempty"` + // + // IT IS A STRING, and it must be the `revision` string a response carried, verbatim. A JSON number — or any other type — is a `400` naming this member. The token spans the FULL 64-bit range, so a number would be rounded past 2^53 by an IEEE-754-double parser and the guard would miss a row nothing else touched; a string round-trips exactly in every consumer. + ActualVersion *string `json:"actual_version,omitempty"` // Assignee With `already_claimed`: the actor currently holding the issue, read inside the transaction that refused. // @@ -1499,7 +1503,9 @@ type Problem struct { // ExpectedVersion With `precondition_failed`: the row `revision` the request guarded on, echoed from the request itself. // // THE EXPECTED/ACTUAL PAIRS ARE SPLIT BY TYPE rather than carried as one polymorphic `expected`/`actual`, and the reason is this document's: a member that is "a version or a status or an assignee" is a schema alternation, and no composition keyword is available to spell one here (see `ApplyItem`). Three typed pairs cost three member names and are readable by a generated client without a cast. - ExpectedVersion *int64 `json:"expected_version,omitempty"` + // + // IT IS A STRING, and it must be the `revision` string a response carried, verbatim. A JSON number — or any other type — is a `400` naming this member. The token spans the FULL 64-bit range, so a number would be rounded past 2^53 by an IEEE-754-double parser and the guard would miss a row nothing else touched; a string round-trips exactly in every consumer. + ExpectedVersion *string `json:"expected_version,omitempty"` // Floor With `events_journal_truncated`: the lowest seq still retained, or `head + 1` when the journal retains nothing at all. Resuming from `floor - 1` continues with a known, explicit gap. Floor *int64 `json:"floor,omitempty"` @@ -1655,12 +1661,12 @@ type ReleaseIssueResponse struct { // Issue A tracked work item. Property semantics documented here apply to every schema that repeats them below. Issue Issue `json:"issue"` - // Revision The row's optimistic-concurrency token AFTER the release, spelled the way `UpdateIssueResponse.revision` spells it and carrying the same promise: a read-modify-write loop composes its next `expected_version` from THIS value, never from a number it incremented itself. + // Revision The row's optimistic-concurrency token AFTER the release, spelled the way `UpdateIssueResponse.revision` spells it and carrying the same promise: a read-modify-write loop composes its next `expected_version` from THIS value, never from one it composed itself. // // A release REMINTS the token by design, so a caller that guarded a following write on a version it read BEFORE the release will miss. That is the point — a concurrent reclaim or close conflicts rather than silently merging — and this member is how the caller stays in step. // - // DECODE IT AS A 64-BIT INTEGER, for the reason `UpdateIssueRequest.expected_version` spells out: an IEEE-754-double parser corrupts it silently, and the corruption only shows up as a `precondition_failed` on the NEXT request. - Revision int64 `json:"revision"` + // IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or `"0"` for a legacy migration-0054 row. Send it back verbatim as an `expected_version`; do not parse it into a number. A JSON number would not survive the trip: the token spans the FULL 64-bit range, and an IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's `float` — rounds anything past 2^53 to a value NEAR the token that is not it, so a guard composed from it is refused against a row nothing else touched. A string round-trips exactly in every consumer. + Revision string `json:"revision"` } // RememberRequest What to remember, and optionally under what key. @@ -1727,8 +1733,10 @@ type ReopenIssueRequest struct { // // IT IS CHECKED BEFORE THE NON-DONE NO-OP, the mirror of the close's check-before-the-idempotent-re-close, and for the same reason: a reopen of a row somebody else has moved is a `409` rather than the 200-with-`already_open` the same body earns unguarded, which is what lets `already_open` be read as "nothing has happened here since". // - // The token is the `revision` this operation's own response carries; compose the next expectation from a value a write ANSWERED with and never from one the client computed. DECODE IT AS A 64-BIT INTEGER, for the reason `UpdateIssueRequest.expected_version` spells out. - ExpectedVersion *int64 `json:"expected_version,omitempty"` + // The token is the `revision` this operation's own response carries; compose the next expectation from a value a write ANSWERED with and never from one the client computed. + // + // IT IS A STRING, and it must be the `revision` string a response carried, verbatim. A JSON number — or any other type — is a `400` naming this member. The token spans the FULL 64-bit range, so a number would be rounded past 2^53 by an IEEE-754-double parser and the guard would miss a row nothing else touched; a string round-trips exactly in every consumer. + ExpectedVersion *string `json:"expected_version,omitempty"` // Reason Why the issue is being reopened. Recorded on the `reopened` EVENT this move records — not on a field of the issue, and not carried in the response, so a caller that wants it back reads the issue's events. Refused for control characters, and bounded by what the column holds rather than by the number above. Reason *string `json:"reason,omitempty"` @@ -1743,7 +1751,9 @@ type ReopenIssueResponse struct { Issue Issue `json:"issue"` // Revision The row's optimistic-concurrency token AFTER this reopen, spelled the way `CloseIssueResponse.revision` spells it and here for the same reason: a recovery flow that reopens and then re-closes composes its next `expected_version` from this value. DECODE IT AS A 64-BIT INTEGER. - Revision int64 `json:"revision"` + // + // IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or `"0"` for a legacy migration-0054 row. Send it back verbatim as an `expected_version`; do not parse it into a number. A JSON number would not survive the trip: the token spans the FULL 64-bit range, and an IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's `float` — rounds anything past 2^53 to a value NEAR the token that is not it, so a guard composed from it is refused against a row nothing else touched. A string round-trips exactly in every consumer. + Revision string `json:"revision"` } // SetSettingRequest What to store under the key the path names. The key is not a member here: it has one spelling, and a body carrying it too would give one request two anchors and a question about what to do when they disagree. @@ -1909,10 +1919,10 @@ type UpdateIssueRequest struct { // ExpectedVersion Requires the row's revision to equal this value before the patch. A miss refuses the WHOLE request with `409 precondition_failed` and writes nothing — `ApplyUpdateItem.expected_version`'s contract, on the operation that patches one row. // - // The token is the `revision` this operation's own response carries, and the same one `GET /v0/beads/issues/{id}` publishes — which is where a first guarded write seeds itself, rather than from an unguarded one or from `POST /v0/beads/issues:batchApply`'s `ApplyItemResult.revision`. Compose the next expectation from the value the write ANSWERED with, never from a number the client incremented itself: the token is OPAQUE and compared for equality alone, so it has no predecessor a client can compute. + // The token is the `revision` this operation's own response carries, and the same one `GET /v0/beads/issues/{id}` publishes — which is where a first guarded write seeds itself, rather than from an unguarded one or from `POST /v0/beads/issues:batchApply`'s `ApplyItemResult.revision`. Compose the next expectation from the value the write ANSWERED with, never from one the client composed itself: the token is OPAQUE and compared for equality alone, so it has no predecessor a client can compute. // - // DECODE IT AS A 64-BIT INTEGER. Live tokens run past 5e17, where an IEEE-754 double's ulp is already 64, so a parser that decodes JSON numbers as doubles — JavaScript's `JSON.parse`, Go's `any`, Python's `float` — hands back a value NEAR the token that is not it, and the guard is refused against a row nothing else touched. - ExpectedVersion *int64 `json:"expected_version,omitempty"` + // IT IS A STRING, and it must be the `revision` string a response carried, verbatim. A JSON number — or any other type — is a `400` naming this member. The token spans the FULL 64-bit range, so a number would be rounded past 2^53 by an IEEE-754-double parser and the guard would miss a row nothing else touched; a string round-trips exactly in every consumer. + ExpectedVersion *string `json:"expected_version,omitempty"` // ForceAssigneeTransfer Bypasses ONLY a genuine transfer away from a live foreign in-progress owner. Reasserting the exact current assignee is idempotent and needs no force. It requires `patch.assignee` — a request setting it without one is a `400` — and it must be false when `expected_assignee` is sent. ForceAssigneeTransfer *bool `json:"force_assignee_transfer,omitempty"` @@ -1940,8 +1950,8 @@ type UpdateIssueResponse struct { // // It is here because `expected_version` is: a guard whose token no response carries is a guard a caller cannot fill. A read-modify-write loop composes its next expectation from THIS value and never from a number it incremented itself, for the reason `compareAndSetMetadata` gives about a value the store renormalizes. `GET /v0/beads/issues/{id}`'s `revision` is the read that publishes the same token, and this member agrees with it. // - // DECODE IT AS A 64-BIT INTEGER, for the reason `UpdateIssueRequest.expected_version` spells out: an IEEE-754-double parser corrupts it silently, and the corruption only shows up as a `precondition_failed` on the NEXT request. - Revision int64 `json:"revision"` + // IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or `"0"` for a legacy migration-0054 row. Send it back verbatim as an `expected_version`; do not parse it into a number. A JSON number would not survive the trip: the token spans the FULL 64-bit range, and an IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's `float` — rounds anything past 2^53 to a value NEAR the token that is not it, so a guard composed from it is refused against a row nothing else touched. A string round-trips exactly in every consumer. + Revision string `json:"revision"` } // IssueID defines model for IssueID. diff --git a/internal/httpapi/batch_apply.go b/internal/httpapi/batch_apply.go index a62cddd20..f1558775b 100644 --- a/internal/httpapi/batch_apply.go +++ b/internal/httpapi/batch_apply.go @@ -421,6 +421,15 @@ func applyUpdateItem(prefix string, encoded json.RawMessage, raw map[string]json if offender, unknown := unknownMember(raw, applyUpdateItemMembers); unknown { return nil, applyUnknownMember(prefix, offender, applyUpdateItemMembers) } + // The guard is read BEFORE the whole-item decode, and through the same + // reader every other operation uses. It is the one member of this item whose + // wire type is not its Go type — a decimal string standing for an int64 — + // so letting the struct decode reach it first would answer a mistyped token + // with the item-level "wrong JSON type" instead of a 400 naming the member. + expectedVersion, res := applyVersionGuardMember(raw, prefix) + if res != nil { + return nil, res + } var wire apigen.ApplyUpdateItem if err := json.Unmarshal(encoded, &wire); err != nil { res := InvalidArgument(applyParam(prefix, ""), ReasonInvalidValue, "an `update` member carries the wrong JSON type") @@ -447,7 +456,7 @@ func applyUpdateItem(prefix string, encoded json.RawMessage, raw map[string]json return nil, res } - item := &issueops.UpdateItem{Target: target, Patch: patch, ExpectedVersion: wire.ExpectedVersion} + item := &issueops.UpdateItem{Target: target, Patch: patch, ExpectedVersion: expectedVersion} if wire.ExpectedStatus != nil { status := issueops.Status(*wire.ExpectedStatus) item.ExpectedStatus = &status @@ -842,7 +851,7 @@ func applyBatchResponse(result issueops.ApplyBatchResult) apigen.ApplyBatchRespo Kind: apigen.ApplyItemResultKind(item.Kind), IssueId: item.IssueID, Changed: item.Changed, - Revision: item.RowVersion, + Revision: types.RevisionToken(item.RowVersion), } if item.DependsOnID != "" { dependsOn := item.DependsOnID @@ -1219,15 +1228,21 @@ func applyBoolMember(raw map[string]json.RawMessage, prefix, member string) (boo return *value, nil } -// applyVersionGuardMember is the family's int64 reader, and it names the member -// itself rather than taking one. +// applyVersionGuardMember is the family's revision-token reader, and it names +// the member itself rather than taking one. // // Its siblings above are generic because they read many members; this one has -// read exactly one on every operation that has ever published a 64-bit member — -// the row-version guard — so the member name lives in the function instead of -// at five call sites that could disagree about how to spell it. A second int64 -// member would re-generalize it, which is a two-line change and not a reason to -// carry a parameter nothing varies. +// read exactly one on every operation that publishes a row-version guard, so the +// member name lives in the function instead of at five call sites that could +// disagree about how to spell it. +// +// THE TOKEN IS A STRING ON THE WIRE AND AN int64 INSIDE. It is opaque and +// equality-only, and it spans the full int64 range, which a JSON number does not +// survive in an IEEE-754-double parser; responses emit it as a decimal string +// (types.RevisionToken) and this is where it comes back. STRING ONLY, with no +// number-or-string transitional spelling: this API refuses unknown members by +// name and keeps one spelling of the guard, and a numeric token accepted here +// would be a value the client rounded before it ever reached the server. // // prefix stays, because a batch item's guard is reported qualified by the item // that carried it where a single operation's is spelled bare. @@ -1236,13 +1251,20 @@ func applyVersionGuardMember(raw map[string]json.RawMessage, prefix string) (*in if !ok { return nil, nil } - var value *int64 - if err := json.Unmarshal(encoded, &value); err != nil || value == nil { + refuse := func() (*int64, *Result) { res := InvalidArgument(prefix+expectedVersionMember, ReasonInvalidValue, - "`"+expectedVersionMember+"` must be an integer") + "`"+expectedVersionMember+"` must be a string: the `revision` token a response carried, echoed verbatim") return nil, &res } - return value, nil + var value *string + if err := json.Unmarshal(encoded, &value); err != nil || value == nil { + return refuse() + } + parsed, err := types.ParseRevisionToken(*value) + if err != nil { + return refuse() + } + return &parsed, nil } // applyBoundedText applies the bounds a stored string carries wherever it is diff --git a/internal/httpapi/batch_apply_test.go b/internal/httpapi/batch_apply_test.go index b78e75ab3..52b6db015 100644 --- a/internal/httpapi/batch_apply_test.go +++ b/internal/httpapi/batch_apply_test.go @@ -81,7 +81,7 @@ func TestApplyBatchForwardsEveryLevelOfTheDocumentedBody(t *testing.T) { "estimated_minutes":null}}}, {"kind":"close","close":{ "target":{"id":"bd-7"},"reason":"done","session":"s-1","force":true, - "expected_version":42}}, + "expected_version":"42"}}, {"kind":"dep_add","dep_add":{ "source":{"key":"root"},"target":{"id":"bd-7"},"type":"waits-for", "metadata":{"gate":"any-children"}}} @@ -265,8 +265,8 @@ func TestApplyBatchAnswersWithTheLeanResult(t *testing.T) { if first["kind"] != "create" || first["issue_id"] != "bd-1" || first["changed"] != true { t.Errorf("items[0] = %v, want the item's kind, id and changed flag", first) } - if first["revision"] != float64(77) { - t.Errorf("items[0].revision = %v, want the row's token under the already-committed spelling", first["revision"]) + if first["revision"] != "77" { + t.Errorf("items[0].revision = %v, want the row's token as a decimal string", first["revision"]) } if _, present := first["issue"]; present { t.Error("items[0] carries a hydrated issue; the wire result is lean and the snapshot stops at the library boundary") @@ -280,8 +280,8 @@ func TestApplyBatchAnswersWithTheLeanResult(t *testing.T) { } // 0 is a real value — a legacy row, and every dep_add — so the member is // emitted rather than omitted, or a client could not tell the two apart. - if second["revision"] != float64(0) { - t.Errorf("items[1].revision = %v, want 0 emitted rather than omitted", second["revision"]) + if second["revision"] != "0" { + t.Errorf("items[1].revision = %v, want \"0\" emitted rather than omitted", second["revision"]) } } @@ -639,8 +639,8 @@ func TestApplyBatchReportsAPreconditionMissAsAConflict(t *testing.T) { err: itemErr(1, issueops.ItemUpdate, "root", "bd-1", issueops.ErrVersionMismatch), wantParam: "items[1].update.expected_version", assert: func(t *testing.T, body map[string]any) { - if body["expected_version"] != float64(42) { - t.Errorf("expected_version = %v, want the guard the request sent", body["expected_version"]) + if body["expected_version"] != "42" { + t.Errorf("expected_version = %v, want the guard the request sent, echoed as the string it arrived as", body["expected_version"]) } }, }, @@ -672,7 +672,7 @@ func TestApplyBatchReportsAPreconditionMissAsAConflict(t *testing.T) { resp := ts.claim(t, batchApplyPath, `{"actor":"alice","items":[ {"kind":"create","create":{"key":"root","title":"one"}}, {"kind":"update","update":{"target":{"id":"bd-1"}, - "expected_version":42,"expected_status":"open","expected_assignee":"bob", + "expected_version":"42","expected_status":"open","expected_assignee":"bob", "patch":{"title":"x"}}} ]}`) if resp.StatusCode != http.StatusConflict { @@ -713,6 +713,66 @@ func TestApplyBatchReportsAPreconditionMissAsAConflict(t *testing.T) { } } +// TestApplyBatchRefusesANumericVersionGuard pins the one spelling of the guard +// on the batch surface, on BOTH item kinds that carry it. +// +// `expected_version` is a decimal string, and a bare number is refused rather +// than coerced. There is no transitional number-or-string acceptance on purpose: +// a number is the shape a double-based client has ALREADY rounded by the time it +// leaves the client, so taking it would mean guarding on a token the server +// never minted and refusing a row nobody touched — the exact failure the string +// exists to remove. The update arm also pins the ORDER: the guard is read before +// the item's typed decode, so a mistyped token earns a 400 naming the member +// instead of the item-level "wrong JSON type". +func TestApplyBatchRefusesANumericVersionGuard(t *testing.T) { + for _, test := range []struct { + name string + item string + wantParam string + }{ + { + name: "update", + item: `{"kind":"update","update":{"target":{"id":"bd-1"},"expected_version":42,"patch":{"title":"x"}}}`, + wantParam: "items[0].update.expected_version", + }, + { + name: "update past 2^53", + item: `{"kind":"update","update":{"target":{"id":"bd-1"},"expected_version":9007199254740993,"patch":{"title":"x"}}}`, + wantParam: "items[0].update.expected_version", + }, + { + name: "close", + item: `{"kind":"close","close":{"target":{"id":"bd-1"},"expected_version":42}}`, + wantParam: "items[0].close.expected_version", + }, + { + name: "a string that is not a decimal token", + item: `{"kind":"update","update":{"target":{"id":"bd-1"},"expected_version":"forty-two","patch":{"title":"x"}}}`, + wantParam: "items[0].update.expected_version", + }, + } { + t.Run(test.name, func(t *testing.T) { + applier := &roleBatchApplier{} + ts := newApplyBatchServer(t, applier) + + resp := ts.claim(t, batchApplyPath, `{"actor":"alice","items":[`+test.item+`]}`) + if resp.StatusCode != http.StatusBadRequest { + t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + if body["code"] != string(CodeInvalidArgument) { + t.Errorf("code = %v, want %s", body["code"], CodeInvalidArgument) + } + if body["param"] != test.wantParam { + t.Errorf("param = %v, want %q — the refusal must name the member, not the item", body["param"], test.wantParam) + } + if calls := applier.requests(); len(calls) != 0 { + t.Errorf("%d batches reached the role; a malformed guard is refused before any database work", len(calls)) + } + }) + } +} + // TestApplyBatchMapsTheRolesTypedRefusalsOntoTheDocumentedCodes walks the rest // of the refusal table. Every branch reads a TYPED error rather than prose, // which is what lets a client stop substring-matching messages. diff --git a/internal/httpapi/close.go b/internal/httpapi/close.go index 23364f563..ea466dc57 100644 --- a/internal/httpapi/close.go +++ b/internal/httpapi/close.go @@ -76,7 +76,7 @@ func (s *Server) handleClose(w http.ResponseWriter, r *http.Request) { Issue: *result.Issue, AlreadyClosed: !result.Changed, OpenChildren: result.OpenChildren, - Revision: result.Issue.RowVersion, + Revision: types.RevisionToken(result.Issue.RowVersion), }) } diff --git a/internal/httpapi/close_test.go b/internal/httpapi/close_test.go index 5e701e24e..159c60358 100644 --- a/internal/httpapi/close_test.go +++ b/internal/httpapi/close_test.go @@ -549,9 +549,12 @@ const guardToken int64 = 9007199254740993 // never-written version 0. func guard(v int64) *int64 { return &v } -// revisionOf reads `revision` as the 64-BIT INTEGER the document declares, -// which is the whole reason it exists beside decodeBody: that helper decodes -// into `any`, and `any` is a float64. +// revisionOf reads `revision` as the decimal STRING the document declares and +// parses it back to the int64 the row holds. That is the whole reason it exists +// beside decodeBody: that helper decodes into `any`, which would take the string +// but hand back its text, and would silently have taken a float64 back when the +// member was a number — which is the corruption the string exists to prevent. +// Decoding into *string is what makes a number-typed member fail here. // // NEVER ORDER IT AND NEVER COMPUTE ONE. The token is opaque and compared for // equality alone, so "the previous revision" is not `revision - 1`; it is the @@ -560,7 +563,7 @@ func revisionOf(t *testing.T, resp *http.Response) int64 { t.Helper() raw := readAll(t, resp) var body struct { - Revision *int64 `json:"revision"` + Revision *string `json:"revision"` } if err := json.Unmarshal([]byte(raw), &body); err != nil { t.Fatalf("decode revision from %q: %v", raw, err) @@ -568,7 +571,11 @@ func revisionOf(t *testing.T, resp *http.Response) int64 { if body.Revision == nil { t.Fatalf("the response carries no `revision`: %s", raw) } - return *body.Revision + token, err := types.ParseRevisionToken(*body.Revision) + if err != nil { + t.Fatalf("`revision` %q is not a decimal token: %v", *body.Revision, err) + } + return token } // TestCloseForwardsTheVersionGuard: the member reaches the role as the POINTER @@ -584,8 +591,8 @@ func TestCloseForwardsTheVersionGuard(t *testing.T) { body string want *int64 }{ - {"a guard is forwarded", `{"actor":"alice","expected_version":9007199254740993}`, guard(guardToken)}, - {"the never-written version is a real guard", `{"actor":"alice","expected_version":0}`, guard(0)}, + {"a guard is forwarded", `{"actor":"alice","expected_version":"9007199254740993"}`, guard(guardToken)}, + {"the never-written version is a real guard", `{"actor":"alice","expected_version":"0"}`, guard(0)}, {"an absent guard stays nil", `{"actor":"alice"}`, nil}, } { t.Run(tc.name, func(t *testing.T) { @@ -664,7 +671,7 @@ func TestCloseRefusesAStaleGuard(t *testing.T) { lifecycle := &roleLifecycle{closeErr: fmt.Errorf("close bd-1: %w", issueops.ErrVersionMismatch)} ts := newCloseServer(t, lifecycle) - resp := ts.closeIssue(t, closePath, `{"actor":"alice","expected_version":9007199254740993}`) + resp := ts.closeIssue(t, closePath, `{"actor":"alice","expected_version":"9007199254740993"}`) if resp.StatusCode != http.StatusConflict { t.Fatalf("status = %d, want 409: %s", resp.StatusCode, readAll(t, resp)) } @@ -698,7 +705,7 @@ func TestCloseGuardOutranksClosePolicy(t *testing.T) { lifecycle := &roleLifecycle{closeErr: fmt.Errorf("close bd-1: %w", issueops.ErrVersionMismatch)} ts := newCloseServer(t, lifecycle) - resp := ts.closeIssue(t, closePath, `{"actor":"alice","expected_version":41,"force":false}`) + resp := ts.closeIssue(t, closePath, `{"actor":"alice","expected_version":"41","force":false}`) body := decodeBody(t, resp) if body["code"] != string(CodePreconditionFailed) { t.Errorf("code = %v, want %s: the role checks the version before policy and the wire must not reorder it", @@ -714,7 +721,7 @@ func TestCloseForceDoesNotBypassTheGuard(t *testing.T) { lifecycle := &roleLifecycle{closeResult: issueops.CloseResult{Issue: closedIssue("bd-1"), Changed: true}} ts := newCloseServer(t, lifecycle) - if resp := ts.closeIssue(t, closePath, `{"actor":"alice","force":true,"expected_version":41}`); resp.StatusCode != http.StatusOK { + if resp := ts.closeIssue(t, closePath, `{"actor":"alice","force":true,"expected_version":"41"}`); resp.StatusCode != http.StatusOK { t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) } got := lifecycle.closeRequests() @@ -726,11 +733,20 @@ func TestCloseForceDoesNotBypassTheGuard(t *testing.T) { } } -// TestCloseRefusesAMalformedGuard: the token is an integer and nothing else, -// refused at the edge before any database work. +// TestCloseRefusesAMalformedGuard: the token is a decimal STRING and nothing +// else, refused at the edge before any database work. +// +// The bare number is the case that matters. It is what the member used to be, so +// accepting it would be the transitional spelling this contract deliberately +// does not have — and a JSON number is exactly the shape that arrives already +// rounded from a double-based client. func TestCloseRefusesAMalformedGuard(t *testing.T) { for _, body := range []string{ - `{"actor":"alice","expected_version":"41"}`, + `{"actor":"alice","expected_version":41}`, + `{"actor":"alice","expected_version":9007199254740993}`, + `{"actor":"alice","expected_version":"41.5"}`, + `{"actor":"alice","expected_version":"not-a-token"}`, + `{"actor":"alice","expected_version":""}`, `{"actor":"alice","expected_version":1.5}`, `{"actor":"alice","expected_version":null}`, `{"actor":"alice","expected_version":true}`, diff --git a/internal/httpapi/create_test.go b/internal/httpapi/create_test.go index d0c53c33d..5e633ce50 100644 --- a/internal/httpapi/create_test.go +++ b/internal/httpapi/create_test.go @@ -280,6 +280,51 @@ func TestCreateAnswersTheStoredRow(t *testing.T) { } } +// TestCreateEchoesSubSecondTimestamps pins that the create response carries the +// role's timestamps at FULL precision, as the text a consumer parses. +// +// The role's snapshot is where the sub-second stamp comes from — that is the +// storage-side contract RunLifecycleCreateEchoesSubSecondTimestamps holds — and +// this is the half that says the wire does not round it away on the way out. A +// handler that re-rendered the time through a second-granular layout would print +// the same instant with the fraction gone, and every same-second create through +// POST /v0/beads/issues would tie. +func TestCreateEchoesSubSecondTimestamps(t *testing.T) { + stored := createdIssue("bd-nano") + stored.CreatedAt = time.Date(2026, 8, 1, 9, 0, 0, 123456789, time.UTC) + stored.UpdatedAt = time.Date(2026, 8, 1, 9, 0, 1, 987654321, time.UTC) + lifecycle := &roleLifecycle{createResult: issueops.CreateResult{Issue: stored}} + ts := newCreateServer(t, lifecycle) + + resp := ts.createIssue(t, `{"actor":"alice","title":"as sent"}`) + if resp.StatusCode != http.StatusOK { + t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) + } + body := decodeBody(t, resp) + for _, member := range []struct { + name string + want time.Time + }{ + {"created_at", stored.CreatedAt}, + {"updated_at", stored.UpdatedAt}, + } { + text, ok := body[member.name].(string) + if !ok { + t.Errorf("%s = %v, want an RFC3339 string", member.name, body[member.name]) + continue + } + got, err := time.Parse(time.RFC3339Nano, text) + if err != nil { + t.Errorf("%s = %q, which does not parse as RFC3339Nano: %v", member.name, text, err) + continue + } + if !got.Equal(member.want) { + t.Errorf("%s = %q, want %v exactly — the fraction the role stored must survive the wire", + member.name, text, member.want) + } + } +} + // TestCreateRefusesAnOccupiedExplicitID pins the 409 and its `param`. It is a // conflict rather than a 400 because the body is well-formed and stays // well-formed: the identical request succeeded before the id was taken. diff --git a/internal/httpapi/delete_test.go b/internal/httpapi/delete_test.go index e2048a30e..5f22606c8 100644 --- a/internal/httpapi/delete_test.go +++ b/internal/httpapi/delete_test.go @@ -314,13 +314,13 @@ func TestDeleteForwardsTheVersionGuard(t *testing.T) { body string want *int64 }{ - {"a guard is forwarded", `{"ids":["bd-1"],"expected_version":9007199254740993}`, guard(guardToken)}, - {"the never-written version is a real guard", `{"ids":["bd-1"],"expected_version":0}`, guard(0)}, + {"a guard is forwarded", `{"ids":["bd-1"],"expected_version":"9007199254740993"}`, guard(guardToken)}, + {"the never-written version is a real guard", `{"ids":["bd-1"],"expected_version":"0"}`, guard(0)}, {"an absent guard stays nil", `{"ids":["bd-1"]}`, nil}, // Cascade and force bypass POLICY, never a precondition. Both travel // beside the guard rather than instead of it. - {"cascade does not displace it", `{"ids":["bd-1"],"cascade":true,"expected_version":41}`, guard(41)}, - {"force does not displace it", `{"ids":["bd-1"],"force":true,"expected_version":41}`, guard(41)}, + {"cascade does not displace it", `{"ids":["bd-1"],"cascade":true,"expected_version":"41"}`, guard(41)}, + {"force does not displace it", `{"ids":["bd-1"],"force":true,"expected_version":"41"}`, guard(41)}, } { t.Run(tc.name, func(t *testing.T) { deleter := &roleDeleter{} @@ -358,7 +358,7 @@ func TestDeleteRefusesAGuardBesideSeveralIDs(t *testing.T) { deleter := &roleDeleter{} ts := newTestServer(t, rolesConfig(Config{Deleter: deleter})) - resp := ts.delete(t, `{"ids":["bd-1","bd-2"],"expected_version":41}`) + resp := ts.delete(t, `{"ids":["bd-1","bd-2"],"expected_version":"41"}`) if resp.StatusCode != http.StatusBadRequest { t.Fatalf("status = %d, want 400: %s", resp.StatusCode, readAll(t, resp)) } @@ -401,7 +401,7 @@ func TestDeleteCountsDistinctIDsForTheGuard(t *testing.T) { deleter := &roleDeleter{} ts := newTestServer(t, rolesConfig(Config{Deleter: deleter})) - resp := ts.delete(t, `{"ids":`+tc.ids+`,"expected_version":41}`) + resp := ts.delete(t, `{"ids":`+tc.ids+`,"expected_version":"41"}`) if resp.StatusCode != http.StatusOK { t.Fatalf("status = %d, want 200: %s", resp.StatusCode, readAll(t, resp)) } @@ -432,7 +432,7 @@ func TestDeleteCountsDistinctIDsForTheGuard(t *testing.T) { // list came out broken. func TestDeleteRefusesABlankID(t *testing.T) { for _, body := range []string{ - `{"ids":[" ","bd-1"],"expected_version":41}`, + `{"ids":[" ","bd-1"],"expected_version":"41"}`, `{"ids":["bd-1",""]}`, } { deleter := &roleDeleter{} @@ -464,7 +464,7 @@ func TestDeleteRefusesAStaleGuard(t *testing.T) { deleter := &roleDeleter{err: fmt.Errorf("delete bd-1: %w", issueops.ErrVersionMismatch)} ts := newTestServer(t, rolesConfig(Config{Deleter: deleter})) - resp := ts.delete(t, `{"ids":["bd-1"],"expected_version":9007199254740993}`) + resp := ts.delete(t, `{"ids":["bd-1"],"expected_version":"9007199254740993"}`) if resp.StatusCode != http.StatusConflict { t.Fatalf("status = %d, want 409: %s", resp.StatusCode, readAll(t, resp)) } @@ -483,10 +483,15 @@ func TestDeleteRefusesAStaleGuard(t *testing.T) { } } -// TestDeleteRefusesAMalformedGuard: the token is an integer and nothing else. +// TestDeleteRefusesAMalformedGuard: the token is a decimal STRING and nothing +// else — including not the bare number the member used to be, which is the +// spelling a double-based client would have already rounded. func TestDeleteRefusesAMalformedGuard(t *testing.T) { for _, body := range []string{ - `{"ids":["bd-1"],"expected_version":"41"}`, + `{"ids":["bd-1"],"expected_version":41}`, + `{"ids":["bd-1"],"expected_version":9007199254740993}`, + `{"ids":["bd-1"],"expected_version":"41.5"}`, + `{"ids":["bd-1"],"expected_version":"not-a-token"}`, `{"ids":["bd-1"],"expected_version":null}`, `{"ids":["bd-1"],"expected_version":{}}`, } { diff --git a/internal/httpapi/get_issue_test.go b/internal/httpapi/get_issue_test.go index 21308b435..702c709e6 100644 --- a/internal/httpapi/get_issue_test.go +++ b/internal/httpapi/get_issue_test.go @@ -457,8 +457,13 @@ func TestGetIssuePublishesTheRevisionToken(t *testing.T) { if err != nil { t.Fatalf("read body: %v", err) } + // Decoded as the STRING the document declares. The first case is + // the point of the shape: 2^53+1 is the smallest token a + // double-based parser cannot hold, so a number-typed member would + // hand a browser client a value one off the row's and its next + // guard would 409 against a row nobody touched. var body struct { - Revision *int64 `json:"revision"` + Revision *string `json:"revision"` } if err := json.Unmarshal(raw, &body); err != nil { t.Fatalf("decode %q: %v", raw, err) @@ -466,8 +471,8 @@ func TestGetIssuePublishesTheRevisionToken(t *testing.T) { if body.Revision == nil { t.Fatalf("the detail response carries no `revision`: %s", raw) } - if *body.Revision != tc.token { - t.Errorf("revision = %d, want the row's token %d", *body.Revision, tc.token) + if *body.Revision != types.RevisionToken(tc.token) { + t.Errorf("revision = %q, want the row's token %q", *body.Revision, types.RevisionToken(tc.token)) } // The storage spelling never rides along: row_lock is json:"-" on // the issue for a reason that still holds, and `revision` is the diff --git a/internal/httpapi/problem.go b/internal/httpapi/problem.go index 221b012c7..57edc7fe3 100644 --- a/internal/httpapi/problem.go +++ b/internal/httpapi/problem.go @@ -16,6 +16,7 @@ import ( "github.com/steveyegge/beads/internal/httpapi/apigen" "github.com/steveyegge/beads/internal/storage" "github.com/steveyegge/beads/internal/storage/uow" + "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" ) @@ -1140,8 +1141,14 @@ func (r Result) WithDeclaredLater(declaredLater bool) Result { // // It is the REQUEST's value rather than a read, which is why there is no // `actual_version` beside it here — see PreconditionFailed. +// +// The parameter stays int64 because every caller holds the PARSED guard by the +// time it refuses; the member is a decimal string on the wire, so the echo goes +// back out through types.RevisionToken and a client comparing it to what it sent +// gets its own spelling back. func (r Result) WithExpectedVersion(expected int64) Result { - r.Problem.ExpectedVersion = &expected + token := types.RevisionToken(expected) + r.Problem.ExpectedVersion = &token return r } diff --git a/internal/httpapi/release.go b/internal/httpapi/release.go index 7ef81f33b..40cbffd14 100644 --- a/internal/httpapi/release.go +++ b/internal/httpapi/release.go @@ -8,6 +8,7 @@ import ( "github.com/steveyegge/beads/internal/httpapi/apigen" "github.com/steveyegge/beads/internal/storage" + "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" ) @@ -84,7 +85,7 @@ func (s *Server) handleRelease(w http.ResponseWriter, r *http.Request) { writeJSON(w, apigen.ReleaseIssueResponse{ Issue: *result.Issue, Changed: result.Changed, - Revision: result.Issue.RowVersion, + Revision: types.RevisionToken(result.Issue.RowVersion), }) } diff --git a/internal/httpapi/release_test.go b/internal/httpapi/release_test.go index d9eb30250..376d136f7 100644 --- a/internal/httpapi/release_test.go +++ b/internal/httpapi/release_test.go @@ -74,8 +74,8 @@ func TestReleaseWritesOnceAndAnswersWithTheRowItWrote(t *testing.T) { if body["changed"] != true { t.Errorf("changed = %v, want true — the role reports it true on every answer it returns without an error", body["changed"]) } - if body["revision"] != float64(77) { - t.Errorf("revision = %v, want the post-release token off the row the role answered with", body["revision"]) + if body["revision"] != "77" { + t.Errorf("revision = %v, want the post-release token off the row the role answered with, as a decimal string", body["revision"]) } issue, ok := body["issue"].(map[string]any) if !ok { @@ -345,7 +345,7 @@ func TestReleaseRefusesUnknownAndMalformedBodies(t *testing.T) { body string param string }{ - {name: "an unknown member", body: `{"actor":"alice","expected_version":3}`, param: "expected_version"}, + {name: "an unknown member", body: `{"actor":"alice","expected_version":"3"}`, param: "expected_version"}, {name: "a missing actor", body: `{"force":true}`, param: claimActorMember}, {name: "an actor that is blank after trimming", body: `{"actor":" "}`, param: claimActorMember}, {name: "an actor carrying a newline", body: `{"actor":"alice\nbd: released by mallory"}`, param: claimActorMember}, diff --git a/internal/httpapi/reopen.go b/internal/httpapi/reopen.go index d5850f285..30f45c375 100644 --- a/internal/httpapi/reopen.go +++ b/internal/httpapi/reopen.go @@ -5,6 +5,7 @@ import ( "net/http" "github.com/steveyegge/beads/internal/httpapi/apigen" + "github.com/steveyegge/beads/internal/types" "github.com/steveyegge/beads/issueops" ) @@ -78,7 +79,7 @@ func (s *Server) handleReopen(w http.ResponseWriter, r *http.Request) { writeJSON(w, apigen.ReopenIssueResponse{ Issue: *result.Issue, AlreadyOpen: !result.Changed, - Revision: result.Issue.RowVersion, + Revision: types.RevisionToken(result.Issue.RowVersion), }) } diff --git a/internal/httpapi/reopen_test.go b/internal/httpapi/reopen_test.go index 643458de2..65394dd6c 100644 --- a/internal/httpapi/reopen_test.go +++ b/internal/httpapi/reopen_test.go @@ -347,8 +347,8 @@ func TestReopenForwardsTheVersionGuard(t *testing.T) { body string want *int64 }{ - {"a guard is forwarded", `{"actor":"alice","expected_version":9007199254740993}`, guard(guardToken)}, - {"the never-written version is a real guard", `{"actor":"alice","expected_version":0}`, guard(0)}, + {"a guard is forwarded", `{"actor":"alice","expected_version":"9007199254740993"}`, guard(guardToken)}, + {"the never-written version is a real guard", `{"actor":"alice","expected_version":"0"}`, guard(0)}, {"an absent guard stays nil", `{"actor":"alice"}`, nil}, } { t.Run(tc.name, func(t *testing.T) { @@ -423,7 +423,7 @@ func TestReopenRefusesAStaleGuard(t *testing.T) { lifecycle := &roleLifecycle{reopenErr: fmt.Errorf("reopen bd-1: %w", issueops.ErrVersionMismatch)} ts := newReopenServer(t, lifecycle) - resp := ts.reopenIssue(t, reopenPath, `{"actor":"alice","expected_version":9007199254740993}`) + resp := ts.reopenIssue(t, reopenPath, `{"actor":"alice","expected_version":"9007199254740993"}`) if resp.StatusCode != http.StatusConflict { t.Fatalf("status = %d, want 409: %s", resp.StatusCode, readAll(t, resp)) } @@ -442,11 +442,15 @@ func TestReopenRefusesAStaleGuard(t *testing.T) { } } -// TestReopenRefusesAMalformedGuard: the token is an integer and nothing else, -// refused at the edge before any database work. +// TestReopenRefusesAMalformedGuard: the token is a decimal STRING and nothing +// else — including not the bare number the member used to be — refused at the +// edge before any database work. func TestReopenRefusesAMalformedGuard(t *testing.T) { for _, body := range []string{ - `{"actor":"alice","expected_version":"41"}`, + `{"actor":"alice","expected_version":41}`, + `{"actor":"alice","expected_version":9007199254740993}`, + `{"actor":"alice","expected_version":"41.5"}`, + `{"actor":"alice","expected_version":"not-a-token"}`, `{"actor":"alice","expected_version":null}`, `{"actor":"alice","expected_version":[]}`, } { diff --git a/internal/httpapi/spec/openapi.v0.yaml b/internal/httpapi/spec/openapi.v0.yaml index ed508c621..ae0994266 100644 --- a/internal/httpapi/spec/openapi.v0.yaml +++ b/internal/httpapi/spec/openapi.v0.yaml @@ -6601,8 +6601,7 @@ components: epic_closeable: type: boolean revision: - type: integer - format: int64 + type: string description: >- The row's optimistic-concurrency token, and THE READ THAT SOURCES A GUARD. Every `expected_version` on this surface is composed from a @@ -6628,18 +6627,12 @@ components: `updated_at`, `status` and the label set. - It is ALWAYS PRESENT, including as 0 — a legacy row backfilled and + It is ALWAYS PRESENT, including as `"0"` — a legacy row backfilled and not mutated since — because an absent member would be ambiguous between a legacy-zero row and a server that does not publish the token. - DECODE IT AS A 64-BIT INTEGER, for the reason - `UpdateIssueRequest.expected_version` spells out: an IEEE-754-double - parser corrupts it silently, and the corruption only shows up as a - `precondition_failed` on the NEXT request. - - IT IS THE ANCHOR ROW'S ALONE. The issues nested under `dependencies` and `dependents` are `IssueWithDependencyMetadata` and carry no token: a caller that means to guard a NEIGHBOUR reads @@ -6651,6 +6644,15 @@ components: IT IS NOT ON THE LIST ROWS, and that is a decision rather than an oversight — see `GET /v0/beads/issues`. + + IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or + `"0"` for a legacy migration-0054 row. Send it back verbatim as an + `expected_version`; do not parse it into a number. A JSON number would not + survive the trip: the token spans the FULL 64-bit range, and an + IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's + `float` — rounds anything past 2^53 to a value NEAR the token that is not + it, so a guard composed from it is refused against a row nothing else + touched. A string round-trips exactly in every consumer. IssueWithDependencyMetadata: type: object description: >- @@ -7444,8 +7446,7 @@ components: computed against the same snapshot, and nothing is recorded in history either. expected_version: - type: integer - format: int64 + type: string description: >- Requires the named bead's revision to equal this value before anything is erased. A miss refuses the whole request with @@ -7491,10 +7492,14 @@ components: The token is the `revision` a lifecycle write answers with, and the one `GET /v0/beads/issues/{id}` publishes — which is where a delete guard should seed itself, since reading the bead before erasing it - is the only way to be sure it is the bead you meant. DECODE IT AS A - 64-BIT INTEGER, for the reason - `UpdateIssueRequest.expected_version` spells out. + is the only way to be sure it is the bead you meant. + + IT IS A STRING, and it must be the `revision` string a response carried, + verbatim. A JSON number — or any other type — is a `400` naming this + member. The token spans the FULL 64-bit range, so a number would be + rounded past 2^53 by an IEEE-754-double parser and the guard would miss a + row nothing else touched; a string round-trips exactly in every consumer. DeleteIssuesResult: type: object required: [dry_run, deleted, dependencies, labels, events, references_updated] @@ -8930,8 +8935,7 @@ components: patch: $ref: '#/components/schemas/ApplyPatchBody' expected_version: - type: integer - format: int64 + type: string description: >- Requires the row's `revision` to equal this value before the patch. A miss refuses the WHOLE request with `409 precondition_failed`. @@ -8950,11 +8954,11 @@ components: because a caller CAN know what its own earlier item set them to. - DECODE IT AS A 64-BIT INTEGER, for the reason - `UpdateIssueRequest.expected_version` spells out. It bites harder - here than anywhere else on the surface: a corrupted token refuses - the WHOLE plan rather than one write, so a client with a lossy - parser loses every item of every batch it guards. + IT IS A STRING, and it must be the `revision` string a response carried, + verbatim. A JSON number — or any other type — is a `400` naming this + member. The token spans the FULL 64-bit range, so a number would be + rounded past 2^53 by an IEEE-754-double parser and the guard would miss a + row nothing else touched; a string round-trips exactly in every consumer. expected_status: type: string maxLength: 255 @@ -9218,8 +9222,7 @@ components: open child is NOT refused: the policy is a gate on the closing act, not an invariant the store maintains. expected_version: - type: integer - format: int64 + type: string description: >- Requires the row's `revision` to equal this value, evaluated as-modified and checked before the idempotent close. A miss refuses @@ -9235,10 +9238,11 @@ components: `update` item whose `patch.status` crosses into the done category. - DECODE IT AS A 64-BIT INTEGER, on - `ApplyUpdateItem.expected_version`'s terms, including its note that - a corrupted token here costs the whole plan. - + IT IS A STRING, and it must be the `revision` string a response carried, + verbatim. A JSON number — or any other type — is a `400` naming this + member. The token spans the FULL 64-bit range, so a number would be + rounded past 2^53 by an IEEE-754-double parser and the guard would miss a + row nothing else touched; a string round-trips exactly in every consumer. ApplyDepAddItem: type: object additionalProperties: false @@ -9364,8 +9368,7 @@ components: idempotent re-add of an edge that already existed with the same type. revision: - type: integer - format: int64 + type: string description: >- The row's optimistic-concurrency token AFTER the item, and the value an `expected_version` guard is composed from. The same member the @@ -9390,14 +9393,14 @@ components: member would be ambiguous between the two. - DECODE IT AS A 64-BIT INTEGER, for the reason - `UpdateIssueRequest.expected_version` spells out: an IEEE-754-double - parser corrupts it silently, and the corruption only shows up as a - `precondition_failed` on the NEXT request. This member is the one - every other `revision` on the surface is spelled against, so the - warning belongs here most of all — a client that reads it through a - lossy parser here carries the damage into every guard it composes. - + IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or + `"0"` for a legacy migration-0054 row. Send it back verbatim as an + `expected_version`; do not parse it into a number. A JSON number would not + survive the trip: the token spans the FULL 64-bit range, and an + IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's + `float` — rounds anything past 2^53 to a value NEAR the token that is not + it, so a guard composed from it is refused against a row nothing else + touched. A string round-trips exactly in every consumer. AddDependenciesRequest: type: object additionalProperties: false @@ -9681,14 +9684,13 @@ components: space that answers "where is the `already_released` member" — there is none, and the operation description says why. revision: - type: integer - format: int64 + type: string description: >- The row's optimistic-concurrency token AFTER the release, spelled the way `UpdateIssueResponse.revision` spells it and carrying the same promise: a read-modify-write loop composes its next - `expected_version` from THIS value, never from a number it - incremented itself. + `expected_version` from THIS value, never from one it composed + itself. A release REMINTS the token by design, so a caller that guarded a @@ -9698,11 +9700,14 @@ components: step. - DECODE IT AS A 64-BIT INTEGER, for the reason - `UpdateIssueRequest.expected_version` spells out: an IEEE-754-double - parser corrupts it silently, and the corruption only shows up as a - `precondition_failed` on the NEXT request. - + IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or + `"0"` for a legacy migration-0054 row. Send it back verbatim as an + `expected_version`; do not parse it into a number. A JSON number would not + survive the trip: the token spans the FULL 64-bit range, and an + IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's + `float` — rounds anything past 2^53 to a value NEAR the token that is not + it, so a guard composed from it is refused against a row nothing else + touched. A string round-trips exactly in every consumer. ClaimNextRequest: type: object additionalProperties: false @@ -9956,8 +9961,7 @@ components: anyway" has said nothing about whether the row is still the one it read. expected_version: - type: integer - format: int64 + type: string description: >- Requires the row's revision to equal this value BEFORE the close. A miss refuses the whole request with `409 precondition_failed` and @@ -9976,7 +9980,7 @@ components: The token is the `revision` this operation's own response carries. Compose the next expectation from the value a write ANSWERED with, - never from a number the client incremented itself: the token is + never from one the client composed itself: the token is OPAQUE and compared for equality alone, so it has no predecessor a client can compute. A first guarded close seeds itself from `GET /v0/beads/issues/{id}`'s `revision` — the read that sources a @@ -9985,11 +9989,11 @@ components: `ApplyItemResult.revision`. - DECODE IT AS A 64-BIT INTEGER, for the reason - `UpdateIssueRequest.expected_version` spells out: an IEEE-754-double - parser corrupts it silently, and the corruption only surfaces as a - `precondition_failed` on the NEXT request. - + IT IS A STRING, and it must be the `revision` string a response carried, + verbatim. A JSON number — or any other type — is a `400` naming this + member. The token spans the FULL 64-bit range, so a number would be + rounded past 2^53 by an IEEE-754-double parser and the guard would miss a + row nothing else touched; a string round-trips exactly in every consumer. CloseIssueResponse: type: object required: [issue, already_closed, open_children, revision] @@ -10011,8 +10015,7 @@ components: bypassed the guard is exactly the caller that wants the number. An unforced close that got this far had none, so it reports 0. revision: - type: integer - format: int64 + type: string description: >- The row's optimistic-concurrency token AFTER this close, spelled the way `UpdateIssueResponse.revision` spells it. @@ -10027,9 +10030,14 @@ components: wrote. - DECODE IT AS A 64-BIT INTEGER, for the reason - `UpdateIssueResponse.revision` spells out. - + IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or + `"0"` for a legacy migration-0054 row. Send it back verbatim as an + `expected_version`; do not parse it into a number. A JSON number would not + survive the trip: the token spans the FULL 64-bit range, and an + IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's + `float` — rounds anything past 2^53 to a value NEAR the token that is not + it, so a guard composed from it is refused against a row nothing else + touched. A string round-trips exactly in every consumer. ReopenIssueRequest: type: object additionalProperties: false @@ -10058,8 +10066,7 @@ components: events. Refused for control characters, and bounded by what the column holds rather than by the number above. expected_version: - type: integer - format: int64 + type: string description: >- Requires the row's revision to equal this value BEFORE the reopen. A miss refuses the whole request with `409 precondition_failed` and @@ -10076,9 +10083,14 @@ components: The token is the `revision` this operation's own response carries; compose the next expectation from a value a write ANSWERED with and - never from one the client computed. DECODE IT AS A 64-BIT INTEGER, - for the reason `UpdateIssueRequest.expected_version` spells out. + never from one the client computed. + + IT IS A STRING, and it must be the `revision` string a response carried, + verbatim. A JSON number — or any other type — is a `400` naming this + member. The token spans the FULL 64-bit range, so a number would be + rounded past 2^53 by an IEEE-754-double parser and the guard would miss a + row nothing else touched; a string round-trips exactly in every consumer. ReopenIssueResponse: type: object required: [issue, already_open, revision] @@ -10093,8 +10105,7 @@ components: and `ClaimResponse.already_claimed`. The response still carries the row. revision: - type: integer - format: int64 + type: string description: >- The row's optimistic-concurrency token AFTER this reopen, spelled the way `CloseIssueResponse.revision` spells it and here for the same @@ -10102,6 +10113,15 @@ components: next `expected_version` from this value. DECODE IT AS A 64-BIT INTEGER. + + IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or + `"0"` for a legacy migration-0054 row. Send it back verbatim as an + `expected_version`; do not parse it into a number. A JSON number would not + survive the trip: the token spans the FULL 64-bit range, and an + IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's + `float` — rounds anything past 2^53 to a value NEAR the token that is not + it, so a guard composed from it is refused against a row nothing else + touched. A string round-trips exactly in every consumer. MetadataValue: # No x-go-type-import: the generator already imports encoding/json # unconditionally, and naming it here emits the import a second time. @@ -10210,8 +10230,7 @@ components: patch: $ref: '#/components/schemas/IssuePatchBody' expected_version: - type: integer - format: int64 + type: string description: >- Requires the row's revision to equal this value before the patch. A miss refuses the WHOLE request with `409 precondition_failed` and @@ -10225,16 +10244,16 @@ components: unguarded one or from `POST /v0/beads/issues:batchApply`'s `ApplyItemResult.revision`. Compose the next expectation from the value the write ANSWERED with, - never from a number the client incremented itself: the token is + never from one the client composed itself: the token is OPAQUE and compared for equality alone, so it has no predecessor a client can compute. - DECODE IT AS A 64-BIT INTEGER. Live tokens run past 5e17, where an - IEEE-754 double's ulp is already 64, so a parser that decodes JSON - numbers as doubles — JavaScript's `JSON.parse`, Go's `any`, Python's - `float` — hands back a value NEAR the token that is not it, and the - guard is refused against a row nothing else touched. + IT IS A STRING, and it must be the `revision` string a response carried, + verbatim. A JSON number — or any other type — is a `400` naming this + member. The token spans the FULL 64-bit range, so a number would be + rounded past 2^53 by an IEEE-754-double parser and the guard would miss a + row nothing else touched; a string round-trips exactly in every consumer. expected_status: type: string maxLength: 255 @@ -10497,8 +10516,7 @@ components: patch is a 200 with `changed: false` rather than an error — idempotent, like every replay answer on this surface. revision: - type: integer - format: int64 + type: string description: >- The row's optimistic-concurrency token AFTER this write, spelled the way `ApplyItemResult.revision` spells it. @@ -10513,11 +10531,14 @@ components: the same token, and this member agrees with it. - DECODE IT AS A 64-BIT INTEGER, for the reason - `UpdateIssueRequest.expected_version` spells out: an IEEE-754-double - parser corrupts it silently, and the corruption only shows up as a - `precondition_failed` on the NEXT request. - + IT IS A STRING, the token's decimal spelling — `"-3819021935081927"`, or + `"0"` for a legacy migration-0054 row. Send it back verbatim as an + `expected_version`; do not parse it into a number. A JSON number would not + survive the trip: the token spans the FULL 64-bit range, and an + IEEE-754-double parser — JavaScript's `JSON.parse`, Go's `any`, Python's + `float` — rounds anything past 2^53 to a value NEAR the token that is not + it, so a guard composed from it is refused against a row nothing else + touched. A string round-trips exactly in every consumer. CreateIssueRequest: type: object additionalProperties: false @@ -10942,8 +10963,7 @@ components: block and never close). Both polarities are reported; this member is never omitted to mean false. See `issue_id`. expected_version: - type: integer - format: int64 + type: string description: >- With `precondition_failed`: the row `revision` the request guarded on, echoed from the request itself. @@ -10955,9 +10975,15 @@ components: is a schema alternation, and no composition keyword is available to spell one here (see `ApplyItem`). Three typed pairs cost three member names and are readable by a generated client without a cast. + + + IT IS A STRING, and it must be the `revision` string a response carried, + verbatim. A JSON number — or any other type — is a `400` naming this + member. The token spans the FULL 64-bit range, so a number would be + rounded past 2^53 by an IEEE-754-double parser and the guard would miss a + row nothing else touched; a string round-trips exactly in every consumer. actual_version: - type: integer - format: int64 + type: string description: >- With `precondition_failed`: the `revision` the row was found holding, read inside the transaction that refused the guard. @@ -10980,6 +11006,13 @@ components: what it found is an addition rather than a wire change — a client must not wait for them, and must never read their absence as a value. + + + IT IS A STRING, and it must be the `revision` string a response carried, + verbatim. A JSON number — or any other type — is a `400` naming this + member. The token spans the FULL 64-bit range, so a number would be + rounded past 2^53 by an IEEE-754-double parser and the guard would miss a + row nothing else touched; a string round-trips exactly in every consumer. expected_status: type: string description: >- diff --git a/internal/httpapi/update.go b/internal/httpapi/update.go index 7bc766d83..12757e940 100644 --- a/internal/httpapi/update.go +++ b/internal/httpapi/update.go @@ -104,7 +104,7 @@ func (s *Server) handleUpdate(w http.ResponseWriter, r *http.Request) { writeJSON(w, apigen.UpdateIssueResponse{ Issue: *result.Issue, Changed: result.Changed, - Revision: result.Issue.RowVersion, + Revision: types.RevisionToken(result.Issue.RowVersion), }) } diff --git a/internal/httpapi/update_test.go b/internal/httpapi/update_test.go index e85dcbc5f..fcca7d714 100644 --- a/internal/httpapi/update_test.go +++ b/internal/httpapi/update_test.go @@ -320,7 +320,12 @@ func TestUpdateRejectsTheShapesTheDocumentRefuses(t *testing.T) { {"unknown metadata member", `{"actor":"alice","patch":{"metadata":{"clear":true}}}`, "patch.metadata.clear"}, {"force_assignee_transfer without an assignee edit", `{"actor":"alice","patch":{"title":"t"},"force_assignee_transfer":true}`, "force_assignee_transfer"}, {"force_assignee_transfer beside expected_assignee", `{"actor":"alice","patch":{"assignee":"bob"},"force_assignee_transfer":true,"expected_assignee":"carol"}`, "force_assignee_transfer"}, - {"expected_version is not a number", `{"actor":"alice","patch":{"title":"t"},"expected_version":"3"}`, "expected_version"}, + // The guard is a decimal STRING; a bare number is the spelling this + // contract deliberately does not also accept, since a double-based + // client would have rounded it before it ever arrived. + {"expected_version is a number", `{"actor":"alice","patch":{"title":"t"},"expected_version":3}`, "expected_version"}, + {"expected_version is a number past 2^53", `{"actor":"alice","patch":{"title":"t"},"expected_version":9007199254740993}`, "expected_version"}, + {"expected_version is not a decimal token", `{"actor":"alice","patch":{"title":"t"},"expected_version":"three"}`, "expected_version"}, {"null expected_status", `{"actor":"alice","patch":{"title":"t"},"expected_status":null}`, "expected_status"}, {"null force_close_policy", `{"actor":"alice","patch":{"title":"t"},"force_close_policy":null}`, "force_close_policy"}, {"blank title", `{"actor":"alice","patch":{"title":" "}}`, "patch.title"}, @@ -609,7 +614,7 @@ func TestUpdateForwardsTheGuardedMembers(t *testing.T) { resp := ts.updateIssue(t, updatePath, `{ "actor":"alice", - "expected_version": 41, + "expected_version": "41", "expected_status": "open", "force_close_policy": true, "patch": { @@ -757,20 +762,23 @@ func TestUpdateGuardsComposeFromTheRevisionTheWriteAnswered(t *testing.T) { if first.StatusCode != http.StatusOK { t.Fatalf("status = %d, want 200: %s", first.StatusCode, readAll(t, first)) } - revision, ok := decodeBody(t, first)["revision"].(float64) + revision, ok := decodeBody(t, first)["revision"].(string) if !ok { - t.Fatalf("the response carries no `revision`; a guard whose token no response carries cannot be filled") + t.Fatalf("the response carries no string `revision`; a guard whose token no response carries cannot be filled") } // The token must be the ROW's, read off the snapshot the role answered // with. Without this the loop below round-trips whatever the handler put // there — including a constant zero — and could not fail against a // `revision` that describes no row. - if int64(revision) != stored { - t.Fatalf("revision = %d, want the %d the role's row carries", int64(revision), stored) + if revision != types.RevisionToken(stored) { + t.Fatalf("revision = %q, want the %q the role's row carries", revision, types.RevisionToken(stored)) } + // The guard is the response's token spliced back in VERBATIM, which is the + // whole discipline the string spelling exists to make possible: nothing + // here parses, re-renders or arithmetics the value. second := ts.updateIssue(t, updatePath, - fmt.Sprintf(`{"actor":"alice","expected_version":%d,"patch":{"title":"second"}}`, int64(revision))) + fmt.Sprintf(`{"actor":"alice","expected_version":%q,"patch":{"title":"second"}}`, revision)) if second.StatusCode != http.StatusOK { t.Fatalf("guarded status = %d, want 200: %s", second.StatusCode, readAll(t, second)) } @@ -778,8 +786,8 @@ func TestUpdateGuardsComposeFromTheRevisionTheWriteAnswered(t *testing.T) { if len(got) != 2 { t.Fatalf("the role was called %d times, want 2", len(got)) } - if got[1].ExpectedVersion == nil || *got[1].ExpectedVersion != int64(revision) { - t.Errorf("expected_version = %v, want the %d the write answered with", got[1].ExpectedVersion, int64(revision)) + if got[1].ExpectedVersion == nil || *got[1].ExpectedVersion != stored { + t.Errorf("expected_version = %v, want the %d the write answered with", got[1].ExpectedVersion, stored) } } @@ -798,11 +806,11 @@ func TestUpdateRefusesAStaleGuard(t *testing.T) { }{ { name: "version", - body: `{"actor":"alice","expected_version":7,"patch":{"title":"t"}}`, + body: `{"actor":"alice","expected_version":"7","patch":{"title":"t"}}`, err: fmt.Errorf("update bd-1: %w", issueops.ErrVersionMismatch), wantParam: "expected_version", wantEcho: "expected_version", - wantValue: float64(7), + wantValue: "7", }, { name: "status", diff --git a/internal/storage/dolt/batch_creator_contract_test.go b/internal/storage/dolt/batch_creator_contract_test.go index aa4c1ce1c..db4e6878e 100644 --- a/internal/storage/dolt/batch_creator_contract_test.go +++ b/internal/storage/dolt/batch_creator_contract_test.go @@ -57,6 +57,9 @@ func TestBatchCreatorContract(t *testing.T) { t.Run("DoesNotMutateTheCallerRequest", func(t *testing.T) { conformance.RunBatchCreatorDoesNotMutateTheCallerRequest(t, ctx, fixture) }) + t.Run("EchoesSubSecondTimestamps", func(t *testing.T) { + conformance.RunBatchCreatorEchoesSubSecondTimestamps(t, ctx, fixture) + }) } // newDoltBatchCreatorFixture composes the frozen role kit with this backend's diff --git a/internal/storage/dolt/lifecycle_create_contract_test.go b/internal/storage/dolt/lifecycle_create_contract_test.go index 267075c98..b8b40def1 100644 --- a/internal/storage/dolt/lifecycle_create_contract_test.go +++ b/internal/storage/dolt/lifecycle_create_contract_test.go @@ -36,6 +36,9 @@ func TestLifecycleCreateContract(t *testing.T) { t.Run("WritesEveryScalarField", func(t *testing.T) { conformance.RunLifecycleCreateWritesEveryScalarField(t, ctx, fixture) }) + t.Run("EchoesSubSecondTimestamps", func(t *testing.T) { + conformance.RunLifecycleCreateEchoesSubSecondTimestamps(t, ctx, fixture) + }) } func newDoltLifecycleCreateFixture(t *testing.T, prefix string) (conformance.LifecycleCreateFixture, context.Context, func()) { diff --git a/internal/storage/domain/db/issue_mergeops_test.go b/internal/storage/domain/db/issue_mergeops_test.go index ab96ad80a..25b52d9cd 100644 --- a/internal/storage/domain/db/issue_mergeops_test.go +++ b/internal/storage/domain/db/issue_mergeops_test.go @@ -57,7 +57,7 @@ func (s *testSuite) issueUpdateSetMetadataMerges() { got := s.readMetadataMap("bd-mo-set", domain.IssueTableOpts{}) s.Equal("yes", got["existing"], "pre-existing key must survive a set-metadata edit") s.Equal("gold", got["tier"]) - s.Equal("99", got["score"], "--set-metadata values are stored as JSON strings (GH#4146)") + s.Equal(float64(99), got["score"], "--set-metadata infers scalar types: 99 is stored as a JSON number (v1.2.2 contract)") } func (s *testSuite) issueUpdateMergeMetadataOverlays() { @@ -161,7 +161,7 @@ func (s *testSuite) issueUpdateMergeOpsWispRouting() { got := map[string]any{} s.Require().NoError(json.Unmarshal(out.Metadata, &got)) s.Equal("wisp", got["kind"], "wisp's pre-existing metadata key must survive") - s.Equal("1", got["extra"]) + s.Equal(float64(1), got["extra"]) } // TestIssueUseCase_ApplyUpdateMergeOps proves the ops flow through the domain @@ -185,7 +185,7 @@ func (s *testSuite) iucApplyUpdateSetMetadata() { got := map[string]any{} s.Require().NoError(json.Unmarshal(updated.Metadata, &got)) s.Equal("safe", got["sibling"]) - s.Equal("1", got["mine"]) + s.Equal(float64(1), got["mine"]) } func (s *testSuite) iucApplyUpdateAppendNotes() { diff --git a/internal/storage/embeddeddolt/batch_creator_contract_test.go b/internal/storage/embeddeddolt/batch_creator_contract_test.go index d87ee5c6d..8bfb53398 100644 --- a/internal/storage/embeddeddolt/batch_creator_contract_test.go +++ b/internal/storage/embeddeddolt/batch_creator_contract_test.go @@ -58,6 +58,9 @@ func TestBatchCreatorContract(t *testing.T) { t.Run("DoesNotMutateTheCallerRequest", func(t *testing.T) { conformance.RunBatchCreatorDoesNotMutateTheCallerRequest(t, ctx, fixture) }) + t.Run("EchoesSubSecondTimestamps", func(t *testing.T) { + conformance.RunBatchCreatorEchoesSubSecondTimestamps(t, ctx, fixture) + }) } func newEmbeddedBatchCreatorFixture(t *testing.T, te *testEnv, prefix string) conformance.BatchCreatorFixture { diff --git a/internal/storage/embeddeddolt/lifecycle_create_contract_test.go b/internal/storage/embeddeddolt/lifecycle_create_contract_test.go index 55da92ff7..96d586b0d 100644 --- a/internal/storage/embeddeddolt/lifecycle_create_contract_test.go +++ b/internal/storage/embeddeddolt/lifecycle_create_contract_test.go @@ -37,6 +37,9 @@ func TestLifecycleCreateContract(t *testing.T) { t.Run("WritesEveryScalarField", func(t *testing.T) { conformance.RunLifecycleCreateWritesEveryScalarField(t, ctx, fixture) }) + t.Run("EchoesSubSecondTimestamps", func(t *testing.T) { + conformance.RunLifecycleCreateEchoesSubSecondTimestamps(t, ctx, fixture) + }) } func newEmbeddedLifecycleCreateFixture(t *testing.T, te *testEnv, prefix string) conformance.LifecycleCreateFixture { diff --git a/internal/storage/issueops/create_batch.go b/internal/storage/issueops/create_batch.go index 35146fbf5..26c720e4a 100644 --- a/internal/storage/issueops/create_batch.go +++ b/internal/storage/issueops/create_batch.go @@ -181,6 +181,7 @@ func ExecuteCreateBatch(ctx context.Context, tx *sql.Tx, request publicops.Creat if err != nil { return publicops.CreateBatchResult{}, nil, err } + OverlayCreateTimestamps(hydrated, issue) result.Issues[i] = hydrated } return result, tables, nil diff --git a/internal/storage/issueops/execution.go b/internal/storage/issueops/execution.go index 56a3c5acf..c0c7a621b 100644 --- a/internal/storage/issueops/execution.go +++ b/internal/storage/issueops/execution.go @@ -108,6 +108,7 @@ func ExecuteCreate(ctx context.Context, tx *sql.Tx, request publicops.CreateRequ if err != nil { return publicops.CreateResult{}, nil, err } + OverlayCreateTimestamps(hydrated, issue) return publicops.CreateResult{Issue: hydrated}, tables, nil } diff --git a/internal/storage/issueops/public_hydration.go b/internal/storage/issueops/public_hydration.go index 18c1f5efe..29dc3db44 100644 --- a/internal/storage/issueops/public_hydration.go +++ b/internal/storage/issueops/public_hydration.go @@ -35,3 +35,24 @@ func HydrateIssueOperationResult(ctx context.Context, tx DBTX, id string, includ } return issue, nil } + +// OverlayCreateTimestamps restores onto a hydrated create result the +// full-precision timestamps the INSERT actually sent. +// +// created_at/updated_at are DATETIME(0) columns, so the re-read a create does +// to build its result snapshot comes back rounded to whole seconds. The create +// echo has carried sub-second RFC3339Nano stamps since before the lifecycle +// facade existed (v1.2.2 returned the caller's own in-memory struct), and +// agents ordering same-second creates by that echo depend on it. Everything +// else on the snapshot stays DB-truth, which is the facade's contract; only +// these three fields are restored, and only for create. +func OverlayCreateTimestamps(hydrated, written *types.Issue) { + if hydrated == nil || written == nil { + return + } + hydrated.CreatedAt = written.CreatedAt + hydrated.UpdatedAt = written.UpdatedAt + if written.ClosedAt != nil { + hydrated.ClosedAt = written.ClosedAt + } +} diff --git a/internal/storage/metadata.go b/internal/storage/metadata.go index 77096cdf2..eb842d081 100644 --- a/internal/storage/metadata.go +++ b/internal/storage/metadata.go @@ -312,13 +312,33 @@ func ApplyMetadataEdits(existing json.RawMessage, setFlags, unsetFlags []string) return json.RawMessage(result), nil } -// MetadataEditValue converts a --set-metadata string value to JSON. Per the CLI -// contract (GH#4146), --set-metadata values are ALWAYS stored as JSON strings; -// inferring numbers/booleans/null from string content silently broke -// map[string]string round-trips for Go consumers (a numeric-looking id or a -// version like "1e3" came back as a JSON number). Typed values go through the -// explicit --metadata / --metadata-json path (MergeMetadataJSON). +// MetadataEditValue converts a --set-metadata string value to JSON, inferring +// the scalar type from the value's spelling: "null" is JSON null, "true"/"false" +// are booleans, anything that scans as a float AND is valid JSON on its own is +// emitted as that literal (so 5 -> 5, 1e3 -> 1e3, while 05, +5 and NaN stay +// strings because they are not valid JSON), and everything else is a string. +// +// This is the shipped v1.2.2 CLI contract (v1.2.2's cmd/bd/update.go toJSONValue, +// copied body-for-body so the parity claim stays checkable). GH#4146 asked for +// string-always so that map[string]string Go consumers keep numeric-looking ids +// and versions like "1e3" intact; that briefly landed here and silently changed +// the CLI contract, so it is served instead by the explicitly typed routes — +// `--metadata` / `--metadata-json` (MergeMetadataJSON) on the CLI and the typed +// set map on the HTTP/Go path (issueops.applyTypedMetadataEdits). func MetadataEditValue(s string) json.RawMessage { + if s == "null" { + return json.RawMessage("null") + } + if s == "true" || s == "false" { + return json.RawMessage(s) + } + // Numbers (integer or float), but only when the spelling is also valid JSON + // on its own — that rejects NaN, Inf, "+5" and leading-zero forms. + if _, err := fmt.Sscanf(s, "%f", new(float64)); err == nil { + if json.Valid([]byte(s)) { + return json.RawMessage(s) + } + } b, _ := json.Marshal(s) return json.RawMessage(b) } diff --git a/internal/storage/metadata_edit_value_test.go b/internal/storage/metadata_edit_value_test.go new file mode 100644 index 000000000..d9a2f0a95 --- /dev/null +++ b/internal/storage/metadata_edit_value_test.go @@ -0,0 +1,86 @@ +package storage + +import ( + "encoding/json" + "testing" +) + +// TestMetadataEditValuePinsV122Inference pins the shipped v1.2.2 `--set-metadata` +// scalar contract (v1.2.2's cmd/bd/update.go toJSONValue): null/bool/number keep +// their JSON type, and a spelling that is not valid JSON on its own stays a +// string even when it scans as a float. An in-window build stored every value as +// a string; that regression is what this table guards against coming back. +func TestMetadataEditValuePinsV122Inference(t *testing.T) { + t.Parallel() + tests := []struct { + name string + input string + want string + }{ + {"integer", "5", `5`}, + {"negative integer", "-2", `-2`}, + {"trailing zero float", "0.50", `0.50`}, + {"exponent", "1e3", `1e3`}, + {"zero", "0", `0`}, + {"true", "true", `true`}, + {"false", "false", `false`}, + {"null", "null", `null`}, + {"leading zero is not JSON", "05", `"05"`}, + {"unary plus is not JSON", "+5", `"+5"`}, + {"NaN is not JSON", "NaN", `"NaN"`}, + {"version triple", "1.2.3", `"1.2.3"`}, + {"empty", "", `""`}, + {"word", "abc", `"abc"`}, + {"sentence", "hello world", `"hello world"`}, + } + for _, tt := range tests { + tt := tt + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + got := string(MetadataEditValue(tt.input)) + if got != tt.want { + t.Errorf("MetadataEditValue(%q) = %s, want %s", tt.input, got, tt.want) + } + if !json.Valid([]byte(got)) { + t.Errorf("MetadataEditValue(%q) = %s, which is not valid JSON", tt.input, got) + } + }) + } +} + +// TestApplyMetadataEditsTypesScalars proves the inference reaches the merged +// blob every caller writes (embedded CLI, proxied CLI and the update executor's +// []string path all funnel through ApplyMetadataEdits). +func TestApplyMetadataEditsTypesScalars(t *testing.T) { + t.Parallel() + merged, err := ApplyMetadataEdits( + json.RawMessage(`{"existing":"yes"}`), + []string{"score=99", "tier=gold", "ratio=0.5", "done=true", "cleared=null"}, + nil, + ) + if err != nil { + t.Fatalf("ApplyMetadataEdits: %v", err) + } + var got map[string]any + if err := json.Unmarshal(merged, &got); err != nil { + t.Fatalf("unmarshal %s: %v", merged, err) + } + if got["score"] != float64(99) { + t.Errorf("metadata[score] = %#v, want the JSON number 99", got["score"]) + } + if got["ratio"] != 0.5 { + t.Errorf("metadata[ratio] = %#v, want the JSON number 0.5", got["ratio"]) + } + if got["done"] != true { + t.Errorf("metadata[done] = %#v, want the JSON boolean true", got["done"]) + } + if v, present := got["cleared"]; !present || v != nil { + t.Errorf("metadata[cleared] = %#v (present=%v), want JSON null", v, present) + } + if got["tier"] != "gold" { + t.Errorf("metadata[tier] = %#v, want %q", got["tier"], "gold") + } + if got["existing"] != "yes" { + t.Errorf("metadata[existing] = %#v, want %q: pre-existing keys must survive", got["existing"], "yes") + } +} diff --git a/internal/storage/uow/batch_applier.go b/internal/storage/uow/batch_applier.go index 66b9a8dfd..927b36a96 100644 --- a/internal/storage/uow/batch_applier.go +++ b/internal/storage/uow/batch_applier.go @@ -192,6 +192,7 @@ func (r *uowApplyRun) applyCreate(ctx context.Context, index int, item *publicop if err != nil { return err } + storageissueops.OverlayCreateTimestamps(issue, created.Issue) if item.Key != "" { r.keys[item.Key] = issue.ID r.result.Keys[item.Key] = issue.ID diff --git a/internal/storage/uow/batch_creator.go b/internal/storage/uow/batch_creator.go index e00bf3bcb..6a9321522 100644 --- a/internal/storage/uow/batch_creator.go +++ b/internal/storage/uow/batch_creator.go @@ -115,5 +115,10 @@ func createBatchItem(ctx context.Context, uw UnitOfWork, request publicops.Creat if err != nil { return nil, storageissueops.ClassifyPublicCreateError(err) } - return hydrateIssueOperation(ctx, uw, created.Issue, false, false) + hydrated, err := hydrateIssueOperation(ctx, uw, created.Issue, false, false) + if err != nil { + return nil, err + } + storageissueops.OverlayCreateTimestamps(hydrated, created.Issue) + return hydrated, nil } diff --git a/internal/storage/uow/batch_creator_contract_test.go b/internal/storage/uow/batch_creator_contract_test.go index dec119da0..0bc5f74fb 100644 --- a/internal/storage/uow/batch_creator_contract_test.go +++ b/internal/storage/uow/batch_creator_contract_test.go @@ -58,6 +58,9 @@ func TestBatchCreatorContract(t *testing.T) { t.Run("DoesNotMutateTheCallerRequest", func(t *testing.T) { conformance.RunBatchCreatorDoesNotMutateTheCallerRequest(t, ctx, fixture) }) + t.Run("EchoesSubSecondTimestamps", func(t *testing.T) { + conformance.RunBatchCreatorEchoesSubSecondTimestamps(t, ctx, fixture) + }) } func newUOWBatchCreatorFixture(t *testing.T, ctx context.Context, prefix string) conformance.BatchCreatorFixture { diff --git a/internal/storage/uow/issue_operations.go b/internal/storage/uow/issue_operations.go index 708284dd9..ee8ca59f7 100644 --- a/internal/storage/uow/issue_operations.go +++ b/internal/storage/uow/issue_operations.go @@ -112,6 +112,7 @@ func (o *issueOperations) Create(ctx context.Context, request publicops.CreateRe if err != nil { return publicops.CreateResult{}, "", err } + storageissueops.OverlayCreateTimestamps(issue, created.Issue) return publicops.CreateResult{Issue: issue}, "create issue", nil }) } diff --git a/internal/storage/uow/lifecycle_create_contract_test.go b/internal/storage/uow/lifecycle_create_contract_test.go index fd4609dc1..19e1d16b5 100644 --- a/internal/storage/uow/lifecycle_create_contract_test.go +++ b/internal/storage/uow/lifecycle_create_contract_test.go @@ -37,6 +37,9 @@ func TestLifecycleCreateContract(t *testing.T) { t.Run("WritesEveryScalarField", func(t *testing.T) { conformance.RunLifecycleCreateWritesEveryScalarField(t, ctx, fixture) }) + t.Run("EchoesSubSecondTimestamps", func(t *testing.T) { + conformance.RunLifecycleCreateEchoesSubSecondTimestamps(t, ctx, fixture) + }) } func newUOWLifecycleCreateFixture(t *testing.T, ctx context.Context, prefix string) conformance.LifecycleCreateFixture { diff --git a/internal/types/types.go b/internal/types/types.go index 82bc0b243..823dfece7 100644 --- a/internal/types/types.go +++ b/internal/types/types.go @@ -9,6 +9,7 @@ import ( "hash" "regexp" "slices" + "strconv" "strings" "time" "unicode/utf8" @@ -80,8 +81,10 @@ type Issue struct { // row_lock is random per write, so generic Issue serialization would break // stable list/export round-trips. The detail-view DTO projects it explicitly // as `revision` for guarded clients (IssueDetails.Revision, set by - // NewIssueDetails, and on the wire at GET /v0/beads/issues/{id}); Go - // consumers read RowVersion directly. + // NewIssueDetails, and on the wire at GET /v0/beads/issues/{id}) — as a + // decimal STRING, via RevisionToken, because the full int64 range does not + // survive a JSON number in a JavaScript consumer. Go consumers read + // RowVersion directly and never see the string. // // Coverage is deliberately partial: it changes on claim/close/unclaim and the // generic update path, but NOT on direct-UPDATE paths that rewrite text @@ -1186,12 +1189,44 @@ type IssueDetails struct { // from a legacy migration-0054 row, so the projection lives beside the // field and not at each caller. // - // NO omitempty. A guarded write that expects 0 matches an un-mutated + // IT IS A STRING ON THE WIRE, holding the token's decimal spelling + // (RevisionToken). The token is drawn from the FULL int64 range, and a JSON + // number past 2^53 does not survive a JavaScript consumer: it reads back a + // rounded value, echoes that as its guard, and earns a 409 for a row nobody + // touched. A string round-trips exactly in every JSON consumer, which is + // what an equality-only opaque token needs, and it leaves a future backend + // free to mint a token that is not an int64 at all. + // + // NO omitempty. A guarded write that expects "0" matches an un-mutated // legacy row and misses any current one, which is correct CAS; omitting // the member would leave that client unable to read the value it must // send, and would make an absent field mean either "legacy-zero" or "this - // producer has no token". - Revision int64 `json:"revision"` + // producer has no token". The legacy migration-0054 value is the string + // "0", not the empty string. + Revision string `json:"revision"` +} + +// RevisionToken renders an optimistic-concurrency token for the wire. +// +// This and ParseRevisionToken are the ONE spelling of the encoding. The token +// is int64 everywhere inside bd — the row_lock column, Issue.RowVersion, the +// ExpectedVersion guard on the issueops requests — and a decimal string +// everywhere on the wire, because it is opaque and equality-only and a JSON +// number loses the top bits in a JavaScript consumer. Keeping the conversion in +// one pair of functions is what keeps "0" meaning the legacy row rather than +// an absent value. +func RevisionToken(v int64) string { + return strconv.FormatInt(v, 10) +} + +// ParseRevisionToken reads a wire revision token back to the internal int64. +// +// It accepts exactly what RevisionToken emits. A caller must echo the token a +// response carried rather than compose one, so anything else is a client that +// invented a value, and reporting that as a parse failure is more useful than +// guessing at it. +func ParseRevisionToken(s string) (int64, error) { + return strconv.ParseInt(s, 10, 64) } // NewIssueDetails starts a detail view of issue with the wire-visible revision @@ -1202,7 +1237,7 @@ type IssueDetails struct { // literal would publish a silently wrong token that nothing can distinguish // from a right one. The caller fills in labels, edges and counts afterwards. func NewIssueDetails(issue Issue) *IssueDetails { - return &IssueDetails{Issue: issue, Revision: issue.RowVersion} + return &IssueDetails{Issue: issue, Revision: RevisionToken(issue.RowVersion)} } // DependencyType categorizes the relationship diff --git a/internal/types/types_test.go b/internal/types/types_test.go index cf0edb2ba..538874def 100644 --- a/internal/types/types_test.go +++ b/internal/types/types_test.go @@ -4,6 +4,8 @@ import ( "encoding/json" "errors" "fmt" + "math" + "regexp" "strings" "testing" "time" @@ -995,13 +997,15 @@ func TestNewIssueDetailsProjectsTheRevisionToken(t *testing.T) { token int64 want string }{ - {"a mutated row", 123456789, `"revision":123456789`}, - {"a legacy un-mutated row", 0, `"revision":0`}, + {"a mutated row", 123456789, `"revision":"123456789"`}, + {"a legacy un-mutated row", 0, `"revision":"0"`}, + {"a negative token", -3819021935081927, `"revision":"-3819021935081927"`}, + {"a token past 2^53", 9007199254740993, `"revision":"9007199254740993"`}, } { t.Run(tc.name, func(t *testing.T) { details := NewIssueDetails(Issue{ID: "test-1", Title: "Versioned", RowVersion: tc.token}) - if details.Revision != tc.token { - t.Errorf("Revision = %d, want %d", details.Revision, tc.token) + if details.Revision != RevisionToken(tc.token) { + t.Errorf("Revision = %q, want %q", details.Revision, RevisionToken(tc.token)) } b, err := json.Marshal(details) @@ -1021,6 +1025,79 @@ func TestNewIssueDetailsProjectsTheRevisionToken(t *testing.T) { } } +// TestRevisionTokenIsAJSONString is the JS-safety pin: whatever the token, the +// marshaled member is a QUOTED decimal, so no consumer that decodes JSON numbers +// as IEEE-754 doubles can round it. +// +// It matches the bytes with a regexp rather than comparing a decoded value, +// because a decoded value is exactly what the defect hides behind — Go's own +// `any` decode of a JSON number is a float64 too, so a test that unmarshaled and +// compared would agree with the broken wire shape for small tokens and disagree +// with it for large ones for the wrong reason. +func TestRevisionTokenIsAJSONString(t *testing.T) { + member := regexp.MustCompile(`"revision":"-?\d+"`) + for _, token := range []int64{0, 1, -1, 123456789, math.MaxInt64, math.MinInt64, 1 << 53, (1 << 53) + 1} { + b, err := json.Marshal(NewIssueDetails(Issue{ID: "test-1", Title: "Versioned", RowVersion: token})) + if err != nil { + t.Fatalf("marshal with token %d: %v", token, err) + } + if !member.Match(b) { + t.Errorf("token %d marshaled to %s, want a quoted decimal `revision` member", token, b) + } + } +} + +// TestRevisionTokenRoundTrips pins that the wire spelling is lossless across the +// whole int64 range — the property the string exists for. A JSON number would +// fail this above 2^53 in any double-based consumer. +func TestRevisionTokenRoundTrips(t *testing.T) { + for _, token := range []int64{ + math.MinInt64, -3819021935081927, -(1 << 53) - 1, -1, 0, 1, + 1 << 53, (1 << 53) + 1, 9007199254740993, math.MaxInt64, + } { + got, err := ParseRevisionToken(RevisionToken(token)) + if err != nil { + t.Errorf("ParseRevisionToken(RevisionToken(%d)): %v", token, err) + continue + } + if got != token { + t.Errorf("ParseRevisionToken(RevisionToken(%d)) = %d, want %d", token, got, token) + } + } +} + +// TestRevisionTokenSurvivesAJavaScriptRealisticParse walks the round trip a +// browser client actually performs — marshal, decode the member as the string it +// is, parse it back — and proves the token that motivated this shape survives it. +// +// The float64 leg is the control: it is what a consumer got when the member was +// a JSON number, and it is WRONG by 1 for this token. Without it the test would +// pass on a broken wire shape too. +func TestRevisionTokenSurvivesAJavaScriptRealisticParse(t *testing.T) { + const token = int64(9007199254740993) // 2^53 + 1, the smallest int64 a double cannot hold + + b, err := json.Marshal(NewIssueDetails(Issue{ID: "test-1", Title: "Versioned", RowVersion: token})) + if err != nil { + t.Fatalf("marshal: %v", err) + } + var decoded struct { + Revision string `json:"revision"` + } + if err := json.Unmarshal(b, &decoded); err != nil { + t.Fatalf("decode revision as a string: %v (a number-typed member would fail here): %s", err, b) + } + got, err := ParseRevisionToken(decoded.Revision) + if err != nil { + t.Fatalf("ParseRevisionToken(%q): %v", decoded.Revision, err) + } + if got != token { + t.Errorf("round trip gave %d, want %d", got, token) + } + if lossy := int64(float64(token)); lossy == token { + t.Fatalf("the control is broken: %d survives a float64 round trip, so this test proves nothing", token) + } +} + func TestReclaimedLeaseJSONSerialization(t *testing.T) { b, err := json.Marshal(ReclaimedLease{ID: "bd-1", PreviousOwner: "worker-a"}) if err != nil { diff --git a/internal/workapi/detail_test.go b/internal/workapi/detail_test.go index ee92887a2..d42de56c0 100644 --- a/internal/workapi/detail_test.go +++ b/internal/workapi/detail_test.go @@ -754,11 +754,11 @@ func TestBuildIssueDetailsProjectsTheRevisionToken(t *testing.T) { if err != nil { t.Fatalf("BuildIssueDetails: %v", err) } - if details.Revision != 987654321 { - t.Errorf("Revision = %d, want the row's token 987654321", details.Revision) + if details.Revision != "987654321" { + t.Errorf("Revision = %q, want the row's token %q", details.Revision, "987654321") } - if details.Revision != details.RowVersion { - t.Errorf("Revision = %d but RowVersion = %d; the published token must be the row's", + if details.Revision != types.RevisionToken(details.RowVersion) { + t.Errorf("Revision = %q but RowVersion = %d; the published token must be the row's", details.Revision, details.RowVersion) } })