beads/cmd/bd/protocol/CATALOG.md
Test User 1fc38ba778 feat: choose your own storage backend (Postgres / MySQL / SQLite) — rebased on main
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>
2026-07-10 17:44:37 +00:00

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 — TestCorpusGolden runs the plan against a live bd (built from source, Dolt-backed) in both flat and BD_JSON_ENVELOPE=1 variants, canonicalizes, and byte-compares against the committed corpus. A diff is a hard failure (make corpus-regen to update); a Dolt-boot failure is an infra skip, never a silent pass.
  • canonicalize_test.go — unit tests for the canonicalizer plus TestCorpusDoubleRunByteIdentical, 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 sql is not supported in embedded mode (this harness's mode), so it is not in the corpus. A downstream consumer's ready-projection enrichment depends on bd sql against a managed Dolt server; covering it needs a server-mode generation path.
  • The error blob pins the not-found envelope; other error classifiers (claim-conflict, silent-fallback auto-import, bd sql unsupported) are plain-text on stderr and belong in a separate error-string fixture set.