WP2 of the beads protocol conformance corpus (PROPOSAL-beads-protocol-v0 §11).
Seven §J clauses had no test; the keystone one had no test anywhere.
cmd/bd/protocol/interchange_test.go pins:
J6.6 export -> import into an EMPTY store -> export reproduces the stream.
bd-go had same-DB byte-stability and per-field round-trip tests, but
nothing asserted CROSS-store equivalence — the exact blind spot where an
import that drops, defaults, or rewrites a field hides. The fixture
spans P0 (the zero-value priority), every core issue_type, a closed
issue with close_reason, labels, inline comments, both dep orientations,
metadata, assignee, and memories.
J1.2 unknown fields ignored — a record carrying future fields at the top
level, inside a dependency, and inside a comment still imports cleanly.
J1.3 `_schema` header records skipped, on both the file and stdin readers.
J6.1 import never deletes: a partial stream does not remove the ids it omits.
J6.3 a dependency whose target id is absent is skipped AND reported
(skipped_dependencies in `bd import --json`).
J6.5 `bd import -` reads a stream from stdin.
J2.4 zero/unknown timestamps export as the Unix epoch, never year-0001
(which json.Marshal refuses outright, failing the whole export).
J1.3 needed a code fix, not just a test. parseJSONLFile (the bootstrap reader)
skipped the header record, but the `bd import` reader loop — the one `bd import`
and `bd import -` both run through — did not: the header line fell through to
the issue path, unmarshaled into an empty Issue, and aborted the WHOLE import
with "validation failed for issue : title is required". So a canonical export
carrying a provenance header could not be imported at all. Verified against the
new test: it fails with exactly that error without the guard.
Two stale artifacts found during the extraction, fixed here:
- TestCLI_Import_PrefixValidation_E2E asserted that import REJECTS a foreign
id prefix without --skip-prefix-validation, a flag that no longer exists
(every import path now passes SkipPrefixValidation). Being build-tagged out
of CI (cgo && integration), it rotted unnoticed. Rewritten as
TestCLI_Import_ForeignPrefix_E2E, pinning the behavior bd actually has —
which the protocol requires anyway: §J6.6 round-trips through a store with
its own prefix, and §J7.1 makes ids opaque.
- docs/reference/json-schema.md claimed export emits schema_version per line.
It does not (and must not): schema_version belongs to the --json command
envelope; the interchange's version marker is the optional _schema header.
The import --json summary field list was also missing five fields.
Gates: gofmt + go vet clean, go build ./... ok, full cmd/bd/protocol package
green (280s, -count=1).
414 lines
17 KiB
Go
414 lines
17 KiB
Go
package protocol
|
|
|
|
// Interchange contract tests (PROPOSAL-beads-protocol-v0 §J1/§J2/§J6).
|
|
//
|
|
// These pin the JSONL interchange at the CLI level: what a conforming reader
|
|
// must tolerate (unknown fields, header records, dangling dep targets), what
|
|
// import must never do (delete), which streams it must accept (stdin), and the
|
|
// keystone round-trip invariant §J6.6 — export → import into an EMPTY store →
|
|
// export must reproduce the stream. bd-go had same-DB byte-stability tests but
|
|
// no cross-store equivalence test, which is where an import that silently drops
|
|
// or rewrites a field hides.
|
|
|
|
import (
|
|
"encoding/json"
|
|
"os"
|
|
"os/exec"
|
|
"path/filepath"
|
|
"strconv"
|
|
"strings"
|
|
"testing"
|
|
)
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Interchange helpers
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// exportJSONL runs `bd export -o <file>` and returns the file's bytes as a
|
|
// string. Export-to-file (not stdout) is deliberate: the summary line goes to
|
|
// stderr and the atomic-write path is the one real callers use.
|
|
func (w *workspace) exportJSONL(name string, extra ...string) string {
|
|
w.t.Helper()
|
|
path := filepath.Join(w.dir, name)
|
|
args := append([]string{"export", "-o", path}, extra...)
|
|
w.run(args...)
|
|
data, err := os.ReadFile(path) //nolint:gosec // test-controlled path
|
|
if err != nil {
|
|
w.t.Fatalf("read export %s: %v", path, err)
|
|
}
|
|
return string(data)
|
|
}
|
|
|
|
// importStream writes stream to a file in the workspace and imports it,
|
|
// returning bd's combined output.
|
|
func (w *workspace) importStream(name, stream string, extra ...string) string {
|
|
w.t.Helper()
|
|
path := filepath.Join(w.dir, name)
|
|
if err := os.WriteFile(path, []byte(stream), 0o644); err != nil {
|
|
w.t.Fatalf("write %s: %v", path, err)
|
|
}
|
|
args := append([]string{"import", "-i", path}, extra...)
|
|
return w.run(args...)
|
|
}
|
|
|
|
// runStdin runs bd with stream on stdin and returns stdout only (stdout is
|
|
// where --json summaries land; stderr carries human progress lines).
|
|
func (w *workspace) runStdin(stream string, args ...string) string {
|
|
w.t.Helper()
|
|
cmd := exec.Command(w.bd, args...)
|
|
cmd.Dir = w.dir
|
|
cmd.Env = w.env()
|
|
cmd.Stdin = strings.NewReader(stream)
|
|
out, err := cmd.Output()
|
|
if err != nil {
|
|
stderr := ""
|
|
if ee, ok := err.(*exec.ExitError); ok {
|
|
stderr = string(ee.Stderr)
|
|
}
|
|
w.t.Fatalf("bd %s (stdin): %v\n%s", strings.Join(args, " "), err, stderr)
|
|
}
|
|
return string(out)
|
|
}
|
|
|
|
// importJSONSummary imports a stream with --json and returns the parsed
|
|
// summary object (source/created/skipped/skipped_dependencies/...).
|
|
func (w *workspace) importJSONSummary(name, stream string) map[string]any {
|
|
w.t.Helper()
|
|
path := filepath.Join(w.dir, name)
|
|
if err := os.WriteFile(path, []byte(stream), 0o644); err != nil {
|
|
w.t.Fatalf("write %s: %v", path, err)
|
|
}
|
|
cmd := exec.Command(w.bd, "import", "-i", path, "--json")
|
|
cmd.Dir = w.dir
|
|
cmd.Env = w.env()
|
|
out, err := cmd.Output()
|
|
if err != nil {
|
|
stderr := ""
|
|
if ee, ok := err.(*exec.ExitError); ok {
|
|
stderr = string(ee.Stderr)
|
|
}
|
|
w.t.Fatalf("bd import --json: %v\n%s", err, stderr)
|
|
}
|
|
items := parseJSONOutput(w.t, string(out))
|
|
if len(items) == 0 {
|
|
w.t.Fatalf("bd import --json produced no summary object:\n%s", out)
|
|
}
|
|
return items[0]
|
|
}
|
|
|
|
// listAllIDs returns the set of issue ids in the store, all statuses.
|
|
func (w *workspace) listAllIDs() map[string]bool {
|
|
w.t.Helper()
|
|
items := parseJSONOutput(w.t, w.run("list", "--all", "--json", "-n", "0"))
|
|
ids := make(map[string]bool, len(items))
|
|
for _, it := range items {
|
|
if id, ok := it["id"].(string); ok {
|
|
ids[id] = true
|
|
}
|
|
}
|
|
return ids
|
|
}
|
|
|
|
// diffStreams renders the first differing line of two JSONL streams.
|
|
func diffStreams(t *testing.T, want, got string) string {
|
|
t.Helper()
|
|
wl := strings.Split(strings.TrimRight(want, "\n"), "\n")
|
|
gl := strings.Split(strings.TrimRight(got, "\n"), "\n")
|
|
var b strings.Builder
|
|
if len(wl) != len(gl) {
|
|
b.WriteString("line count differs: original=" +
|
|
strconv.Itoa(len(wl)) + " re-export=" + strconv.Itoa(len(gl)) + "\n")
|
|
}
|
|
n := min(len(wl), len(gl))
|
|
for i := range n {
|
|
if wl[i] != gl[i] {
|
|
b.WriteString("first differing line " + strconv.Itoa(i+1) + ":\n original: " + wl[i] + "\n re-export: " + gl[i] + "\n")
|
|
return b.String()
|
|
}
|
|
}
|
|
if len(wl) > n {
|
|
b.WriteString("only in original: " + wl[n] + "\n")
|
|
}
|
|
if len(gl) > n {
|
|
b.WriteString("only in re-export: " + gl[n] + "\n")
|
|
}
|
|
return b.String()
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// §J6.6 — the keystone round-trip invariant
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// TestProtocol_Interchange_RoundTripEquivalence pins §J6.6: export → import
|
|
// into an empty conforming store → export MUST reproduce the original stream.
|
|
//
|
|
// bd-go had same-DB byte-stability (export twice from one store) and per-field
|
|
// round-trip tests, but nothing asserted CROSS-STORE equivalence — so an import
|
|
// that dropped, defaulted, or rewrote a field (or a relational row) could not be
|
|
// caught. The fixture deliberately spans the fields the interchange must carry:
|
|
// P0 (the zero-value priority §J2.1), every core issue_type, a closed issue with
|
|
// close_reason, labels, inline comments, both dependency orientations
|
|
// (parent-child and blocks), metadata, assignee, and memories (§J6.4).
|
|
func TestProtocol_Interchange_RoundTripEquivalence(t *testing.T) {
|
|
t.Parallel()
|
|
src := newWorkspace(t)
|
|
|
|
critical := src.create("--title", "P0 critical bug", "--type", "bug", "--priority", "0",
|
|
"--description", "Line one\nline two — unicode: ✓", "--assignee", "alice",
|
|
"--design", "Design body", "--acceptance", "All green", "--notes", "Notes body")
|
|
src.run("update", critical, "--metadata", `{"component":"auth","risk":"high"}`)
|
|
|
|
epic := src.create("--title", "Epic parent", "--type", "epic", "--priority", "1")
|
|
child := src.create("--title", "Child task", "--type", "task", "--priority", "2", "--parent", epic)
|
|
blocker := src.create("--title", "Blocker", "--type", "chore", "--priority", "3")
|
|
src.run("dep", "add", child, blocker)
|
|
|
|
src.run("label", "add", child, "zeta")
|
|
src.run("label", "add", child, "alpha")
|
|
src.run("comments", "add", child, "first comment")
|
|
src.run("comments", "add", child, "second comment")
|
|
|
|
done := src.create("--title", "Finished feature", "--type", "feature", "--priority", "4")
|
|
src.run("close", done, "--reason", "shipped in abc123")
|
|
|
|
src.run("remember", "--key", "zebra", "last memory by key")
|
|
src.run("remember", "--key", "aardvark", "first memory by key")
|
|
|
|
original := src.exportJSONL("original.jsonl", "--include-memories")
|
|
if strings.Count(original, "\n") < 7 {
|
|
t.Fatalf("fixture export looks too small (%d lines):\n%s", strings.Count(original, "\n"), original)
|
|
}
|
|
|
|
// A fresh workspace is an EMPTY conforming store with its own prefix — the
|
|
// import must carry the foreign ids and every field verbatim.
|
|
dst := newWorkspace(t)
|
|
if got := dst.listAllIDs(); len(got) != 0 {
|
|
t.Fatalf("destination store is not empty: %v", got)
|
|
}
|
|
dst.importStream("incoming.jsonl", original)
|
|
|
|
reexport := dst.exportJSONL("reexport.jsonl", "--include-memories")
|
|
|
|
if reexport != original {
|
|
t.Errorf("§J6.6 violated: export → import → export did not reproduce the stream\n%s",
|
|
diffStreams(t, original, reexport))
|
|
}
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// §J1.2 — forward compatibility (unknown fields ignored)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// TestProtocol_Interchange_UnknownFieldsTolerated pins §J1.2: readers MUST
|
|
// ignore unknown fields on any record. A future bd emitting new fields must not
|
|
// break an older reader — so a stream carrying fields this build has never heard
|
|
// of (at the top level, inside a dependency object, and inside a comment) still
|
|
// imports cleanly, with the known fields intact.
|
|
func TestProtocol_Interchange_UnknownFieldsTolerated(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
target := w.prefix + "-fut1"
|
|
future := w.prefix + "-fut2"
|
|
|
|
stream := strings.Join([]string{
|
|
`{"_type":"issue","id":"` + target + `","title":"Dep target","status":"open","issue_type":"task","priority":2,` +
|
|
`"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}`,
|
|
`{"_type":"issue","id":"` + future + `","title":"From the future","status":"open","issue_type":"task","priority":1,` +
|
|
`"created_at":"2026-01-02T00:00:00Z","updated_at":"2026-01-02T00:00:00Z",` +
|
|
`"labels":["known"],` +
|
|
`"dependencies":[{"issue_id":"` + future + `","depends_on_id":"` + target + `","type":"blocks",` +
|
|
`"created_at":"2026-01-02T00:00:00Z","quantum_flux":"dep-level unknown"}],` +
|
|
`"comments":[{"id":"c1","issue_id":"` + future + `","author":"bob","text":"hello",` +
|
|
`"created_at":"2026-01-02T00:00:00Z","sentiment":"comment-level unknown"}],` +
|
|
`"telepathy_score":42,"future_object":{"nested":["a","b"]},"future_list":[1,2,3]}`,
|
|
"",
|
|
}, "\n")
|
|
|
|
w.importStream("future.jsonl", stream)
|
|
|
|
issue := w.showJSONFull(future)
|
|
assertField(t, issue, "title", "From the future")
|
|
assertField(t, issue, "status", "open")
|
|
assertFieldFloat(t, issue, "priority", 1)
|
|
requireStringSetEqual(t, getStringSlice(issue, "labels"), []string{"known"},
|
|
"labels survived a record carrying unknown fields")
|
|
requireDepEdgesEqual(t, getObjectSlice(issue, "dependencies"),
|
|
[]depEdge{{issueID: future, dependsOnID: target}},
|
|
"dependency survived a dep object carrying an unknown field")
|
|
requireCommentTextsEqual(t, getObjectSlice(issue, "comments"), []string{"hello"},
|
|
"comment survived a comment object carrying an unknown field")
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// §J1.3 — header record skipped by the `bd import` reader
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// TestProtocol_Interchange_SchemaHeaderSkipped pins §J1.3: a reader MUST skip
|
|
// any record bearing `_schema`.
|
|
//
|
|
// This was a real gap, not a hypothetical: the bootstrap reader (parseJSONLFile)
|
|
// skipped the header, but the `bd import` reader loop did not — a canonical
|
|
// export with a provenance header aborted the WHOLE import with "title is
|
|
// required", because the header line fell through to the issue path and
|
|
// unmarshaled into an empty Issue. Fixed alongside this test (wy-ltox1).
|
|
func TestProtocol_Interchange_SchemaHeaderSkipped(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
id := w.prefix + "-hdr1"
|
|
|
|
stream := `{"_schema":"beads-jsonl/1","_dolt_branch":"main","_sort":"stable-v1"}` + "\n" +
|
|
`{"_type":"issue","id":"` + id + `","title":"After the header","status":"open","issue_type":"task",` +
|
|
`"priority":2,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}` + "\n"
|
|
|
|
t.Run("file_import", func(t *testing.T) {
|
|
w.importStream("headered.jsonl", stream)
|
|
assertField(t, w.showJSON(id), "title", "After the header")
|
|
})
|
|
|
|
t.Run("stdin_import", func(t *testing.T) {
|
|
// Same reader loop, second entry point — and a header is exactly what a
|
|
// piped canonical export carries.
|
|
stdinID := w.prefix + "-hdr2"
|
|
piped := strings.Replace(stream, id, stdinID, -1)
|
|
w.runStdin(piped, "import", "-")
|
|
assertField(t, w.showJSON(stdinID), "title", "After the header")
|
|
})
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// §J6.1 — import never deletes
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// TestProtocol_Interchange_ImportNeverDeletes pins §J6.1: import is upsert-only.
|
|
// Absence of an id from the stream implies nothing — an import of a partial
|
|
// stream MUST NOT delete the local issues it omits. (Doc-stated in
|
|
// SYNC_CONCEPTS; no test held the line, and a "make the store match the file"
|
|
// regression would silently destroy every bead the file predates.)
|
|
func TestProtocol_Interchange_ImportNeverDeletes(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
kept := w.create("--title", "Not in the stream", "--type", "task", "--priority", "2")
|
|
updated := w.create("--title", "In the stream", "--type", "task", "--priority", "2")
|
|
|
|
// A stream mentioning ONLY `updated` (with a strictly newer updated_at so the
|
|
// §J6.2 stale guard lets it land).
|
|
stream := `{"_type":"issue","id":"` + updated + `","title":"Retitled by import","status":"open",` +
|
|
`"issue_type":"task","priority":2,"created_at":"2026-01-01T00:00:00Z",` +
|
|
`"updated_at":"2099-01-01T00:00:00Z"}` + "\n"
|
|
w.importStream("partial.jsonl", stream)
|
|
|
|
ids := w.listAllIDs()
|
|
if !ids[kept] {
|
|
t.Errorf("§J6.1 violated: issue %s was absent from the imported stream and no longer exists (store now: %v)", kept, ids)
|
|
}
|
|
assertField(t, w.showJSON(updated), "title", "Retitled by import")
|
|
assertField(t, w.showJSON(kept), "title", "Not in the stream")
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// §J6.3 — tolerant linking (missing dep target skipped AND reported)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// TestProtocol_Interchange_MissingDepTargetSkippedAndReported pins §J6.3: a
|
|
// dependency edge whose target id is absent MUST NOT fail the import; it is
|
|
// skipped and REPORTED. Both halves matter — silently swallowing the edge would
|
|
// let a partial sync quietly lose the graph.
|
|
func TestProtocol_Interchange_MissingDepTargetSkippedAndReported(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
id := w.prefix + "-dangl"
|
|
missing := w.prefix + "-nope9"
|
|
|
|
stream := `{"_type":"issue","id":"` + id + `","title":"Has a dangling dep","status":"open",` +
|
|
`"issue_type":"task","priority":2,"created_at":"2026-01-01T00:00:00Z",` +
|
|
`"updated_at":"2026-01-01T00:00:00Z","dependencies":[{"issue_id":"` + id + `",` +
|
|
`"depends_on_id":"` + missing + `","type":"blocks","created_at":"2026-01-01T00:00:00Z"}]}` + "\n"
|
|
|
|
summary := w.importJSONSummary("dangling.jsonl", stream)
|
|
|
|
// The issue lands (import did not fail)...
|
|
assertField(t, w.showJSON(id), "title", "Has a dangling dep")
|
|
|
|
// ...the edge does not...
|
|
if deps := getObjectSlice(w.showJSON(id), "dependencies"); len(deps) != 0 {
|
|
t.Errorf("§J6.3: dependency on absent target %s should be skipped, got %v", missing, deps)
|
|
}
|
|
|
|
// ...and the skip is reported, naming the target.
|
|
reported := getStringSlice(summary, "skipped_dependencies")
|
|
if len(reported) == 0 {
|
|
t.Fatalf("§J6.3 violated: skipped dependency was not reported in bd import --json (summary: %v)", summary)
|
|
}
|
|
if !strings.Contains(strings.Join(reported, "\n"), missing) {
|
|
t.Errorf("§J6.3: skipped_dependencies does not name the missing target %s: %v", missing, reported)
|
|
}
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// §J6.5 — streams (stdin import, stdout export)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// TestProtocol_Interchange_StdinImport pins §J6.5: import MUST accept stdin
|
|
// (`bd import -`) — the `bd export | ssh host bd import -` pipe is the
|
|
// interchange's whole point, and it was untested.
|
|
func TestProtocol_Interchange_StdinImport(t *testing.T) {
|
|
t.Parallel()
|
|
src := newWorkspace(t)
|
|
src.create("--title", "Piped issue", "--type", "task", "--priority", "1")
|
|
stream := src.exportJSONL("piped.jsonl")
|
|
|
|
dst := newWorkspace(t)
|
|
dst.runStdin(stream, "import", "-")
|
|
|
|
if got := len(dst.listAllIDs()); got != 1 {
|
|
t.Fatalf("bd import - : expected 1 issue in the destination store, got %d", got)
|
|
}
|
|
if dst.exportJSONL("dst.jsonl") != stream {
|
|
t.Errorf("§J6.5: stream imported from stdin did not re-export identically")
|
|
}
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// §J2.4 — epoch sanitize (GH#2488)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
// TestProtocol_Interchange_EpochSanitize pins §J2.4: zero/unknown times are
|
|
// represented as the Unix epoch (1970-01-01T00:00:00Z), never as year-0001.
|
|
// A Go zero time.Time marshals to year 0001, which json.Marshal REFUSES ("year
|
|
// outside of range [0,9999]") — so without the sanitizer a single row with a
|
|
// NULL timestamp fails the entire export. The reachable CLI-level trigger is an
|
|
// import record with no timestamps (§J2.5 makes them optional).
|
|
func TestProtocol_Interchange_EpochSanitize(t *testing.T) {
|
|
t.Parallel()
|
|
w := newWorkspace(t)
|
|
id := w.prefix + "-notime"
|
|
|
|
// No created_at / updated_at at all.
|
|
stream := `{"_type":"issue","id":"` + id + `","title":"Timeless","status":"open","issue_type":"task","priority":2}` + "\n"
|
|
w.importStream("timeless.jsonl", stream)
|
|
|
|
out := w.exportJSONL("timeless-out.jsonl")
|
|
line := ""
|
|
for _, l := range strings.Split(strings.TrimSpace(out), "\n") {
|
|
if strings.Contains(l, `"`+id+`"`) {
|
|
line = l
|
|
}
|
|
}
|
|
if line == "" {
|
|
t.Fatalf("issue %s missing from export:\n%s", id, out)
|
|
}
|
|
|
|
var rec map[string]any
|
|
if err := json.Unmarshal([]byte(line), &rec); err != nil {
|
|
t.Fatalf("export line is not valid JSON: %v\n%s", err, line)
|
|
}
|
|
for _, field := range []string{"created_at", "updated_at"} {
|
|
ts, _ := rec[field].(string)
|
|
if strings.HasPrefix(ts, "0001-") {
|
|
t.Errorf("§J2.4 violated: %s exported as year-0001 (%q) — must be the Unix epoch", field, ts)
|
|
}
|
|
if ts == "" {
|
|
t.Errorf("§J2.4: %s missing from the export record (§J2.1 requires it)", field)
|
|
}
|
|
}
|
|
}
|