beads/cmd/bd/protocol/errors_contract_test.go
Steve Yegge 08881217b6 test(protocol): pin §E/§M/§V conformance clauses at the CLI level (wy-ge2h8)
Conformance corpus WP4 from PROPOSAL-beads-protocol-v0.md §11: the errors,
memories, and versioning clauses that the manifest listed as TODO. All of them
are CLI-surface clauses, so they land in cmd/bd/protocol — the corpus an
alternate implementation replays against its own binary.

Pinned:
  E3  exit codes 10 (remote-divergence refused), 12 (destroy-token missing),
      130 (prompt canceled), asserted as LITERALS, not as bd's Go constants —
      the clause freezes the numbers a script branches on.
  E4  error classes distinguishable from the message alone: not-found,
      already-claimed (naming the holder), not-claimable (naming the state),
      validation.
  E5  --json errors are {error, hint?, schema_version:1}.
  M1  memory CRUD surface (remember / recall / memories / forget).
  M4  reserved namespace: `bd kv set memory.*` refuses and names the owner.
  V2  designated-migrator gate; BD_ALLOW_REMOTE_MIGRATE=1 is the way through.
  V3  schema-skew refusal, and the BD_IGNORE_SCHEMA_SKEW downgrade to a warning.

Rebased onto origin/main and the exit-130 prompt deadline widened to 120s: that
case is the one init test on the SUCCESS path (initEnv pins the suite's Dolt
server), so it pays a full store creation before the wizard prompts — the old
15s deadline fired mid-init and misreported a missing prompt (wy-wst4r).

Landed via wy-wst4r after the original close of wy-ge2h8 cited a wyvern-side
doc-only commit and left this 1005-line corpus stranded on a local branch.

Agent-Signature: claude-code-opus-4.8-high on behalf of Steve Yegge
2026-07-13 10:30:24 -07:00

240 lines
9.3 KiB
Go

// errors_contract_test.go — protocol v0 §E (errors and exit codes), the
// error-class half.
//
// E4 (error classes). Implementations MUST distinguish, in message and
// structured output (NOT by exit code), at least: not-found, already-claimed
// (naming the holder), not-claimable (naming the state), and validation. The
// Go error values (storage.ErrAlreadyClaimed & co.) are accident; what an agent
// branches on is the message and the --json shape, so that is what these tests
// pin.
//
// E5 (structured errors). With --json, an error is a JSON object carrying at
// least "error" (message), optionally "hint", and schema_version: 1.
//
// E1/E2 (empty is success, failure is nonzero) are pinned in exit_codes_test.go
// and reinforced here: every error class below exits 1, none exits 0.
package protocol
import (
"strings"
"testing"
)
const (
actorAlice = "BEADS_ACTOR=alice"
actorBob = "BEADS_ACTOR=bob"
)
// isNotFound reports whether a message expresses the not-found class. The
// clause requires the CLASS to be recognizable, not one blessed phrase, so this
// tolerates both spellings an implementation is likely to use ("not found",
// "no issue found matching …") rather than freezing bd's current wording as
// though it were the protocol.
func isNotFound(msg string) bool {
lower := strings.ToLower(msg)
if strings.Contains(lower, "not found") {
return true
}
return (strings.Contains(lower, "no issue found") || strings.Contains(lower, "no issues found")) &&
strings.Contains(lower, "matching")
}
// TestProtocol_ErrorClass_NotFound pins the not-found class: a nonzero exit,
// a message that expresses not-found, and a structured --json error (§E5).
func TestProtocol_ErrorClass_NotFound(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
out, code := w.runExpectError("show", "nonexistent-xyz")
if code == 0 {
t.Errorf("exit code = 0, want nonzero (§E2)")
}
if !isNotFound(out) {
t.Errorf("message does not express the not-found class (§E4):\n%s", out)
}
if !strings.Contains(out, "nonexistent-xyz") {
t.Errorf("not-found message does not name the missing id (§E4):\n%s", out)
}
jsonOut, jsonCode := w.runExpectError("show", "nonexistent-xyz", "--json")
if jsonCode == 0 {
t.Errorf("--json exit code = 0, want nonzero (§E2)")
}
obj := requireJSONError(t, jsonOut, "not-found --json")
if !isNotFound(errorMessage(obj)) {
t.Errorf("--json error message does not express the not-found class (§E4/§E5): %q", errorMessage(obj))
}
}
// TestProtocol_ErrorClass_AlreadyClaimedNamesHolder pins the already-claimed
// class (§E4, §L2.4): claiming an issue another actor holds must fail with a
// message that NAMES THE HOLDER — an agent that cannot see who holds the claim
// cannot decide whether to wait, escalate, or move on.
func TestProtocol_ErrorClass_AlreadyClaimedNamesHolder(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
id := w.create("Contended issue")
w.runEnv([]string{actorAlice}, "update", id, "--claim")
out, code := w.runEnvExpectError([]string{actorBob}, "update", id, "--claim")
if code == 0 {
t.Errorf("exit code = 0, want nonzero (§L2.4)")
}
lower := strings.ToLower(out)
if !strings.Contains(lower, "already claimed") {
t.Errorf("message does not identify the already-claimed class (§E4):\n%s", out)
}
if !strings.Contains(out, "alice") {
t.Errorf("message does not name the holder (§E4/§L2.4):\n%s", out)
}
}
// TestProtocol_ErrorClass_NotClaimableNamesState pins the not-claimable class
// (§E4): claiming an issue that is in a non-claimable STATE (here: closed) is a
// different failure from already-claimed, and the message must name the state.
// Distinguishing the two is the whole point of the clause — "retry later" is
// right for a contended claim and wrong for a closed issue.
func TestProtocol_ErrorClass_NotClaimableNamesState(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
id := w.create("Closed issue")
w.run("close", id)
out, code := w.runEnvExpectError([]string{actorBob}, "update", id, "--claim")
if code == 0 {
t.Errorf("exit code = 0, want nonzero (§E2)")
}
lower := strings.ToLower(out)
if !strings.Contains(lower, "not claimable") {
t.Errorf("message does not identify the not-claimable class (§E4):\n%s", out)
}
if !strings.Contains(lower, "closed") {
t.Errorf("message does not name the blocking state (§E4):\n%s", out)
}
}
// TestProtocol_ErrorClass_ClaimFailures_StructuredJSON is the §E5 half of the
// claim error classes — and it is SKIPPED because bd-go does not satisfy it
// today (wy-kxgf4).
//
// bd routes not-found through the JSON-respecting error helper, so
// `bd show <missing> --json` emits {error, schema_version:1} (pinned above).
// The claim path does not: `bd update <id> --claim --json` prints
//
// Error claiming t04…-qqr: issue already claimed by alice
//
// as plain text, so an agent driving bd with --json gets an unparseable stderr
// line for the single most common contended-write failure it must branch on.
// The message contract (§E4) holds; the structured contract (§E5) does not.
//
// Per proposal §14, where bd's behavior deviates from a clause the clause wins
// and the deviation is a bug — so this test asserts the clause and stays
// skipped until wy-kxgf4 lands, at which point it becomes the guardrail.
func TestProtocol_ErrorClass_ClaimFailures_StructuredJSON(t *testing.T) {
t.Skip("bd emits claim failures as plain text even with --json; violates §E5 (wy-kxgf4)")
t.Parallel()
w := newWorkspace(t)
claimed := w.create("Held by alice")
w.runEnv([]string{actorAlice}, "update", claimed, "--claim")
closed := w.create("Closed")
w.run("close", closed)
// already-claimed: structured, and still naming the holder.
out, _ := w.runEnvExpectError([]string{actorBob}, "update", claimed, "--claim", "--json")
obj := requireJSONError(t, out, "already-claimed --json")
msg := errorMessage(obj)
if !strings.Contains(strings.ToLower(msg), "already claimed") || !strings.Contains(msg, "alice") {
t.Errorf("--json error does not name class + holder (§E4/§E5): %q", msg)
}
// not-claimable: structured, and still naming the state.
out, _ = w.runEnvExpectError([]string{actorBob}, "update", closed, "--claim", "--json")
obj = requireJSONError(t, out, "not-claimable --json")
msg = strings.ToLower(errorMessage(obj))
if !strings.Contains(msg, "not claimable") || !strings.Contains(msg, "closed") {
t.Errorf("--json error does not name class + state (§E4/§E5): %q", errorMessage(obj))
}
}
// TestProtocol_ErrorClass_Validation pins the validation class (§E4): a
// malformed argument fails with a message about the argument, and is NOT
// reported as a not-found.
func TestProtocol_ErrorClass_Validation(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
id := w.create("Valid issue")
out, code := w.runExpectError("update", id, "--status", "not_a_status")
if code == 0 {
t.Errorf("exit code = 0, want nonzero (§E2)")
}
lower := strings.ToLower(out)
if !strings.Contains(lower, "status") {
t.Errorf("validation message does not name the offending input (§E4):\n%s", out)
}
if strings.Contains(lower, "not found") {
t.Errorf("validation failure misreported as not-found (§E4):\n%s", out)
}
}
// TestProtocol_ErrorClasses_AreDistinguishable is the clause itself (§E4): the
// three claim-adjacent failures — not-found, already-claimed, not-claimable —
// must be told apart from the message alone. Exit codes deliberately do NOT
// distinguish them in v0 (§E2), so if the messages collapse, an agent has
// nothing left to branch on.
func TestProtocol_ErrorClasses_AreDistinguishable(t *testing.T) {
t.Parallel()
w := newWorkspace(t)
claimed := w.create("Held by alice")
w.runEnv([]string{actorAlice}, "update", claimed, "--claim")
closed := w.create("Closed")
w.run("close", closed)
notFoundOut, notFoundCode := w.runExpectError("update", "nonexistent-xyz", "--claim")
claimedOut, claimedCode := w.runEnvExpectError([]string{actorBob}, "update", claimed, "--claim")
closedOut, closedCode := w.runEnvExpectError([]string{actorBob}, "update", closed, "--claim")
// §E2: all three fail nonzero. §E4: none of them may be told apart by the
// exit code — the message carries the class.
for name, code := range map[string]int{
"not-found": notFoundCode,
"already-claimed": claimedCode,
"not-claimable": closedCode,
} {
if code == 0 {
t.Errorf("%s: exit code = 0, want nonzero (§E2)", name)
}
}
// Each class is recognized by its own predicate, and must be recognized by
// EXACTLY one: a message that reads as two classes at once (or as none) is
// as useless to an agent as a shared exit code.
recognizers := map[string]func(string) bool{
"not-found": isNotFound,
"already-claimed": func(s string) bool { return strings.Contains(strings.ToLower(s), "already claimed") },
"not-claimable": func(s string) bool { return strings.Contains(strings.ToLower(s), "not claimable") },
}
outputs := map[string]string{
"not-found": notFoundOut,
"already-claimed": claimedOut,
"not-claimable": closedOut,
}
for class, out := range outputs {
var matched []string
for name, recognize := range recognizers {
if recognize(out) {
matched = append(matched, name)
}
}
if len(matched) != 1 || matched[0] != class {
t.Errorf("%s failure is recognized as %v, want exactly [%s] — the classes are not distinguishable from the message (§E4):\n%s",
class, matched, class, out)
}
}
}