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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-29 05:20:27 +00:00

433 lines
17 KiB
Go

// corpus.go — producer-side logic for the Beads↔consumer cross-version
// contract-test system (Phase 2).
//
// This file is the dependency-free, unit-testable core: it defines the
// deterministic command PLAN that exercises bd's stable CLI/JSON surface,
// a canonicalizer that strips nondeterminism (timestamps, ordering) so two
// independent runs produce byte-identical output, and the manifest that
// records the corpus's provenance.
//
// A downstream consumer vendors the generated corpus (testdata/corpus/) and replays it
// against its own consumer to detect cross-version drift without needing a
// live bd. Everything here must stay free of test-only and bd-internal
// imports so it can be reasoned about (and reused) in isolation.
package protocol
import (
"bytes"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"regexp"
"sort"
"strings"
)
// Capture is a single named command in the corpus PLAN. Name is the stable
// blob filename (without extension); Args is the exact bd argument vector
// (excluding the bd binary itself and the global --json flag, which the
// runner appends where appropriate).
type Capture struct {
Name string
Args []string
}
// Fixed issue IDs used by the PLAN. Pinning IDs removes the largest source
// of nondeterminism (generated hash IDs) so the only thing left to
// canonicalize is timestamps.
const (
CorpusRootID = "corpus-root"
CorpusDepID = "corpus-dep"
CorpusClosedID = "corpus-closed" // created, then closed + reopened
CorpusDeletedID = "corpus-deleted" // created, then deleted
)
// errorCaptureName is the single PLAN capture that deliberately targets a
// missing issue, so it is the one capture expected to exit non-zero. It pins the
// exit-codes-and-errors half of the contract — a non-zero exit plus the
// {error, schema_version} stdout envelope (see CATALOG.md) — while every other
// capture must exit 0. The generator special-cases this name in both the
// exit-status check and the error-envelope guard.
const errorCaptureName = "error"
// CorpusPlan returns the ordered, deterministic list of captures. The order
// matters: create steps must run before the read steps that observe them,
// and the dependency must be added before dep_list is captured.
//
// Each Capture's Args are passed verbatim to bd. Read commands include
// --json so the output is the structured contract surface; the "error"
// capture deliberately targets a missing issue to pin the error envelope.
func CorpusPlan() []Capture {
return []Capture{
// CREATE: --force lets us pin custom IDs despite bd's per-database random
// ID prefix; pinned IDs make every downstream read deterministic. Four
// beads: root + dep exercise reads/dependencies; closed + deleted are
// created here so the close/reopen and delete mutations below have stable
// subjects without disturbing root/dep.
{
Name: "create_root",
Args: []string{"create", "Corpus root issue", "--id", CorpusRootID, "--force", "--priority", "1", "--type", "feature", "--description", "deterministic corpus root", "--json"},
},
{
Name: "create_dep",
Args: []string{"create", "Corpus dependency issue", "--id", CorpusDepID, "--force", "--priority", "2", "--type", "task", "--description", "deterministic corpus dependency", "--json"},
},
{
Name: "create_closed",
Args: []string{"create", "Corpus closeable issue", "--id", CorpusClosedID, "--force", "--priority", "3", "--type", "task", "--description", "deterministic corpus closeable", "--json"},
},
{
Name: "create_deleted",
Args: []string{"create", "Corpus deletable issue", "--id", CorpusDeletedID, "--force", "--priority", "3", "--type", "task", "--description", "deterministic corpus deletable", "--json"},
},
// dep_add pins the dual-key dependency-edge shape {issue_id, depends_on_id,
// type, status}.
{
Name: "dep_add",
Args: []string{"dep", "add", CorpusRootID, CorpusDepID, "--type", "blocks", "--json"},
},
// READS captured before the mutations below, so show/dep_list pin the
// pre-mutation root (the stable, long-standing blobs).
{
Name: "show",
Args: []string{"show", CorpusRootID, "--json"},
},
{
Name: "dep_list",
Args: []string{"dep", "list", CorpusRootID, "--json"},
},
// MUTATIONS: update/close/reopen return an array of the affected issue;
// update pins label + metadata coercion (phase=2 -> string "2", since
// --set-metadata always stores values as JSON strings); close pins
// close_reason + closed_at; dep_remove/delete pin their confirmation shapes.
{
Name: "update",
Args: []string{"update", CorpusRootID, "--json", "--priority", "0", "--add-label", "corpus-label", "--set-metadata", "phase=2", "--description", "updated corpus root"},
},
{
Name: "close",
Args: []string{"close", "--force", "--json", "--reason", "corpus close reason exceeding twenty chars", CorpusClosedID},
},
{
Name: "reopen",
Args: []string{"reopen", "--json", CorpusClosedID},
},
{
Name: "dep_remove",
Args: []string{"dep", "remove", CorpusRootID, CorpusDepID, "--json"},
},
{
Name: "delete",
Args: []string{"delete", "--force", "--json", CorpusDeletedID},
},
// READS captured after the mutations, so list/ready/count reflect the
// full post-mutation state (updated root, reopened bead, removed edge,
// deleted bead gone).
{
Name: "list",
Args: []string{"list", "--all", "--json"},
},
{
Name: "ready",
Args: []string{"ready", "--json"},
},
{
Name: "count",
Args: []string{"count", "--json"},
},
{
Name: "version",
Args: []string{"version", "--json"},
},
// The error capture pins the {error, schema_version} envelope bd emits on
// stdout for a missing issue — a downstream consumer's isBdNotFound classifier depends on
// it — plus the non-zero exit status bd returns (see checkCaptureExit).
{
Name: errorCaptureName,
Args: []string{"show", "nonexistent-xyz-corpus", "--json"},
},
}
}
// timestampRE matches RFC3339 / RFC3339Nano timestamps anywhere in a string
// value. We anchor it to the full string so we only replace values that are
// timestamps in their entirety, not strings that happen to embed a date.
var timestampRE = regexp.MustCompile(
`^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$`,
)
// tsPlaceholder is the canonical stand-in for any timestamp value.
const tsPlaceholder = "<TS>"
// provenanceDropKeys are removed entirely during canonicalization: they vary in
// both value AND presence across builds. `bd version --json` embeds "commit"
// from Go's VCS stamping, which a local worktree build may omit while a CI
// clean-clone build includes — so it must be dropped, not just normalized.
var provenanceDropKeys = map[string]bool{"commit": true}
// provenanceValueKeys have a stable presence but a release/build-specific value
// (the bd version number, git branch, and build tag from `bd version --json`).
// The corpus pins the SHAPE of the version command — that these fields exist and
// schema_version is present — not the release identity, which changes every time
// beads bumps its version. Their values are replaced with a placeholder so the
// corpus stays reproducible across versions; gc's actual version parsing/gating
// is covered by the cross-version matrix and bd_version_pin_test, not here.
var provenanceValueKeys = map[string]string{
"version": "<VERSION>",
"branch": "<BRANCH>",
"build": "<BUILD>",
}
// revisionPlaceholder is the canonical stand-in for a guarded-write revision
// (row_lock) token value.
const revisionPlaceholder = "<REVISION>"
// volatileValueKeys have a stable presence but a per-write-random value, so the
// corpus pins that the field EXISTS (its wire shape) while replacing its value
// with a placeholder — exactly as it does for timestamps. `bd show --json`
// exposes the guarded-write revision (the row_lock optimistic-concurrency
// token), which the engine rewrites to a fresh random value on every
// lifecycle/ownership write; pinning its literal value would break both the
// golden byte-comparison and the double-run determinism check. Same bare-key-
// name scope caveat as the provenance transforms below: `revision` is currently
// emitted only by `bd show --json`. If a future command ever emits a
// deterministic field named `revision`, scope this to the show capture (thread
// Capture.Name through generation) before relying on it.
var volatileValueKeys = map[string]string{
"revision": revisionPlaceholder,
}
// CanonicalizeJSON normalizes a bd JSON blob so that two independent runs
// produce byte-identical output:
//
// 1. Any string value that is an RFC3339/RFC3339Nano timestamp is replaced
// with "<TS>".
// 2. Any per-write-random token value (the guarded-write "revision" /
// row_lock, matched by key name) is replaced with "<REVISION>", pinning
// the field's presence without its nondeterministic value.
// 3. Any array whose elements are all objects is stably sorted by the
// element's "id" field (falling back to the element's canonical-JSON
// form when "id" is absent or equal), so list/ready/sql ordering is
// deterministic regardless of storage iteration order.
// 4. The result is re-marshaled with 2-space indentation and sorted keys
// (Go's encoding/json sorts map keys), yielding a minimal, byte-stable
// diff.
//
// The input need not be a single object; arrays and scalars are handled.
func CanonicalizeJSON(raw []byte) ([]byte, error) {
var v any
dec := json.NewDecoder(bytes.NewReader(raw))
dec.UseNumber()
if err := dec.Decode(&v); err != nil {
return nil, fmt.Errorf("canonicalize: decode: %w", err)
}
// A corpus capture must be exactly one JSON document. bd could print a
// warning line (or, on a bug, a second JSON value) after the payload; that
// trailing stdout would otherwise be silently dropped here and canonicalized
// as if the command emitted clean JSON, while a real consumer decoding the
// whole stream would choke on it. Require the stream to end after the first
// value; only trailing whitespace, which the decoder skips, is allowed.
if err := dec.Decode(new(json.RawMessage)); !errors.Is(err, io.EOF) {
if err == nil {
return nil, fmt.Errorf("canonicalize: unexpected second JSON value after the first")
}
return nil, fmt.Errorf("canonicalize: unexpected trailing data after JSON value: %w", err)
}
canon := canonValue(v)
out, err := marshalCanonical(canon)
if err != nil {
return nil, fmt.Errorf("canonicalize: marshal: %w", err)
}
return out, nil
}
// canonValue recursively normalizes a decoded JSON value in place.
func canonValue(v any) any {
switch t := v.(type) {
case map[string]any:
for k, child := range t {
// NOTE ON SCOPE: the provenance transforms below match by bare key
// name at every nesting depth of every blob, not just the version
// capture. That is safe only because these keys (commit/version/
// branch/build) currently appear solely in the version blob
// (`grep -rl '"version"' testdata/corpus` lists version blobs only).
// If a future command ever emits a field named commit/version/branch/
// build, this would silently drop or placeholder it and the corpus
// would stop guarding that command's wire shape. Before adding such a
// field, scope these transforms to the version capture (thread the
// Capture.Name through generation) — note it cannot be done by "top
// level only" because envelope mode nests these under "data".
//
// Drop build-provenance keys entirely so the canonical corpus does
// not depend on how (or where) bd was built.
if provenanceDropKeys[k] {
delete(t, k)
continue
}
// Replace release/build-specific values (version, branch, build) with
// a placeholder: pin the version command's shape, not its identity.
if ph, ok := provenanceValueKeys[k]; ok {
if _, isStr := child.(string); isStr {
t[k] = ph
continue
}
}
// 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 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
}
t[k] = canonValue(child)
}
return t
case []any:
for i, child := range t {
t[i] = canonValue(child)
}
sortObjectArray(t)
return t
case string:
if timestampRE.MatchString(t) {
return tsPlaceholder
}
return t
default:
// json.Number, bool, nil — already deterministic.
return v
}
}
// sortObjectArray stably sorts arr in place iff every element is an object.
// Elements are ordered by their "id" string when present; ties (or missing
// ids) fall back to the element's canonical-JSON encoding so the order is
// fully determined by content.
func sortObjectArray(arr []any) {
for _, e := range arr {
if _, ok := e.(map[string]any); !ok {
return // mixed or scalar array — preserve original order
}
}
sort.SliceStable(arr, func(i, j int) bool {
return elemSortKey(arr[i]) < elemSortKey(arr[j])
})
}
// elemSortKey derives a stable ordering key for an object array element:
// its "id" field plus its canonical-JSON form as a tiebreaker. Including the
// canonical form guarantees a total order even when ids collide or are
// absent.
func elemSortKey(e any) string {
idPart := ""
if m, ok := e.(map[string]any); ok {
if id, ok := m["id"].(string); ok {
idPart = id
}
}
body, err := marshalCanonical(e)
if err != nil {
return idPart
}
return idPart + "\x00" + string(body)
}
// marshalCanonical encodes v with sorted keys (json default) and 2-space
// indentation, without HTML-escaping, so the bytes are stable and minimal.
func marshalCanonical(v any) ([]byte, error) {
var buf bytes.Buffer
enc := json.NewEncoder(&buf)
enc.SetEscapeHTML(false)
enc.SetIndent("", " ")
if err := enc.Encode(v); err != nil {
return nil, err
}
// json.Encoder appends a trailing newline; keep it for clean diffs.
return buf.Bytes(), nil
}
// BlobMeta records a single corpus blob's provenance: the bd command that
// produced it and the SHA-256 of its canonicalized bytes.
type BlobMeta struct {
Cmd string `json:"cmd"`
SHA256 string `json:"sha256"`
}
// Manifest is the corpus index. It pins the schema version (the coordination
// canary), the generator identity, and a per-blob SHA-256 checksum so consumers
// can detect tampering or partial vendoring. It deliberately does not
// pin the live bd version/commit — see the field comment below for why the
// corpus stays version-agnostic.
type Manifest struct {
SchemaVersion int `json:"schema_version"`
// bd_version and bd_commit are intentionally omitted: both vary by build
// environment / release and would make the committed manifest
// non-reproducible. The corpus is version-agnostic (it pins wire SHAPES, not
// a release identity); schema_version is the coordination canary and the
// per-blob checksums are the integrity anchor. The generating bd version/
// commit lives in the PR that updates the corpus.
GeneratedBy string `json:"generated_by"`
Canonicalized bool `json:"canonicalized"`
Blobs map[string]BlobMeta `json:"blobs"`
}
// NewManifest builds a Manifest from the captured (mode → name → bytes)
// corpus. The blob key is "<mode>/<name>" (e.g. "flat/show",
// "envelope/show") and cmd is the joined bd argument vector for that
// capture. bytes are the already-canonicalized blob contents; the SHA is
// computed over them so the manifest validates exactly what's on disk.
func NewManifest(schemaVersion int, generatedBy string, plan []Capture, blobs map[string]map[string][]byte) Manifest {
cmdByName := make(map[string]string, len(plan))
for _, c := range plan {
cmdByName[c.Name] = "bd " + joinArgs(c.Args)
}
out := make(map[string]BlobMeta)
for mode, byName := range blobs {
for name, data := range byName {
sum := sha256.Sum256(data)
out[mode+"/"+name] = BlobMeta{
Cmd: cmdByName[name],
SHA256: hex.EncodeToString(sum[:]),
}
}
}
return Manifest{
SchemaVersion: schemaVersion,
GeneratedBy: generatedBy,
Canonicalized: true,
Blobs: out,
}
}
// MarshalManifest encodes a Manifest deterministically (sorted keys, 2-space
// indent) so committing it produces stable diffs.
func MarshalManifest(m Manifest) ([]byte, error) {
return marshalCanonical(m)
}
// joinArgs renders an argument vector as a single shell-ish string for the
// manifest's cmd field. Args containing spaces are quoted so multi-word titles
// and descriptions read correctly.
func joinArgs(args []string) string {
parts := make([]string, len(args))
for i, a := range args {
if strings.ContainsRune(a, ' ') {
parts[i] = `"` + a + `"`
} else {
parts[i] = a
}
}
return strings.Join(parts, " ")
}