Rebase of PR #4601 (feat/choose-your-own-backend) onto current origin/main, squashed to a single commit because the original 73-commit history built and then removed the uowStore derisk spike incrementally, which does not replay cleanly over the 125 commits main has since advanced (notably #4679, the ready-work counts fix, which merged to main and is now inherited rather than re-applied). The full pre-rebase history remains on the original branch tip for reference. Contents (multi-backend feature + the six review follow-ups): - bd init --backend=postgres|mysql|sqlite provisioning behind the Dolt-parity seam; the three SQL backends share *sqlkit.Store over pluggable dialects and carry a generated typed-unsupported shell for the non-core surface. - Passwords in init DSNs are redacted before persisting to metadata.json (driver parser + re-parse verification), with a negative-test matrix proving no secret survives (pgdialect + mysql). - The uowStore derisk spike and its report artifacts are removed; the shell generator now lives in internal/storage/unsupportedgen (neutral name). - Compile-time guard `var _ storage.DoltStorage = (*Store)(nil)` on each backend plus a regen-idempotence test keep the generated skip lists honest. - sqlkit exposes CountReadyWork so every SQL backend satisfies storage.ReadyWorkCounter and inherits the shared page-pushed ready-counts path. - Commercial/product names scrubbed from the feature's own code for vendor neutrality. Rebase reconciliations: adopted main's metadata-load hardening in the store factories alongside the backend dispatch; combined the config interface (GetMetadata + ReconcileVersion) and the conformance registrations (ReadyCounts + Claim/lease); took main's versions of the shared-infra concurrency (uow doltserver_tx) and delete-cascade (domain/issue_delete) evolutions; implemented the interface's new UnclaimIssue on sqlkit (delegating to issueops) and added it to the skip lists. Verified: go build (cgo + CGO_ENABLED=0) and go vet clean; unit tests (sqlbuild/issueops/pgdialect/mysql/unsupportedgen) and the SQLite conformance suite green (RunAll, incl. ReadyCounts equivalence and Claim/lease on the real sqlkit backend). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3.2 KiB
3.2 KiB
bd contract corpus — producer catalog
This package is the producer half of the Beads ↔ consumer cross-version
contract-test system. It pins the bd --json wire surface that a downstream
consumer's decoder consumes, by generating a canonicalized golden-JSON corpus
under testdata/corpus/ and failing CI on any unreviewed change to it.
A downstream consumer vendors this corpus and replays it against its own decoder,
so a bd release can never silently change a wire shape the consumer parses.
How it works
corpus.go— the deterministic command plan, the canonicalizer (timestamps →<TS>, object arrays stable-sorted, keys sorted, 2-space indent), and the provenance manifest.corpus_test.go—TestCorpusGoldenruns the plan against a livebd(built from source, Dolt-backed) in both flat andBD_JSON_ENVELOPE=1variants, canonicalizes, and byte-compares against the committed corpus. A diff is a hard failure (make corpus-regento update); a Dolt-boot failure is an infra skip, never a silent pass.canonicalize_test.go— unit tests for the canonicalizer plusTestCorpusDoubleRunByteIdentical, the determinism backstop that generates the corpus twice and asserts byte-identity.
Regenerate after any deliberate wire change: make corpus-regen, review the
diff, and bump JSONSchemaVersion (cmd/bd/output.go) — the schema_version
field in every blob is the coordination canary a downstream consumer keys its
pinned-decoder migration off.
Coverage
| Blob (flat + envelope) | bd command | Contract domain |
|---|---|---|
create_root, create_dep, create_closed, create_deleted |
bd create … --json |
json-output-shapes (object) |
show |
bd show <id> --json |
json-output-shapes (array-of-one), dependency shape |
update |
bd update … --json |
json-output-shapes (mutation array), label add + metadata coercion (phase → integer) |
close |
bd close --reason … --json |
close semantics (close_reason, closed_at) |
reopen |
bd reopen … --json |
reopen semantics (status back to open) |
list |
bd list --all --json |
json-output-shapes (array / list envelope) |
ready |
bd ready --json |
ready-projection-semantics |
dep_add, dep_list |
bd dep add/list --json |
json-output-shapes (dependency) |
dep_remove |
bd dep remove … --json |
dependency-edge removal confirmation |
delete |
bd delete --force … --json |
delete confirmation shape |
count |
bd count --json |
json-output-shapes (scalar) |
version |
bd version --json |
version-compat, the schema_version canary |
error |
bd show <missing> --json |
exit-codes-and-errors ({error, schema_version}) |
Known gaps (tracked, not silent)
bd sqlis not supported in embedded mode (this harness's mode), so it is not in the corpus. A downstream consumer's ready-projection enrichment depends onbd sqlagainst a managed Dolt server; covering it needs a server-mode generation path.- The
errorblob pins the not-found envelope; other error classifiers (claim-conflict, silent-fallback auto-import,bd sqlunsupported) are plain-text on stderr and belong in a separate error-string fixture set.