beads/backend/conformance/ready_claimer_contract.go
Julian Knutsen d801ec43dc
feat(issueops): put every issue capability behind one library surface
Beads had two implementations of most issue verbs: one for the direct route
(the CLI talking to a store it opened itself) and one for the proxied-server
route (the CLI talking through a unit of work over a running Dolt server).
They drifted — different commit messages, different transaction boundaries,
different refusals, occasionally different answers.

Seven role interfaces now live in the leaf package issueops: Lifecycle,
Reader, ReadyClaimer, BatchCloser, DependencyEditor, Commenter and Relations.
Each is reached only through a store accessor, never a constructor, because
the accessor is where the hook and telemetry decorators add their layers.
Three implementations back every role — dolt, embeddeddolt, and the
unit-of-work provider the proxied route uses. Both routes call the same role
for close, dep add/remove/list, comment, ready --claim and update.

A depguard rule (httpapi-domain-boundary) denies internal/storage/domain from
internal/httpapi, so a handler cannot reach uw.IssueUseCase() past the roles
and open a second front door one lint-clean commit at a time.

Behaviour users will notice, all in the CHANGELOG:
  - bd close a b c is one Dolt commit, not three, and --claim-next moved
    inside that transaction so it fires only when something landed
  - the open-children guard moved into the transaction and its hand-rolled
    cmd/bd copy is gone, removing a read-then-write window that made
    bd close <child> <parent> depend on argument order
  - bd dep add --file honours deferred version commit
  - embedded bd comment writes the role's message and author
  - dep verb commit messages are the role's on the direct route

Wisp-sourced dependency edges are restored. Moving bd dep add onto the role
had pinned an edge's SOURCE to the issues plane, and the two routes did not
even fail alike: direct refused with "issue <id> not found", proxied threw an
fk_dep_issue violation. The comment justifying the pin claimed the issues
plane was "the only one its unit-of-work sibling can reach" — that was false;
domain.DependencyUseCase declared a full set of wisp twins with no production
caller. All three implementations now route per edge by the edge's own
source. A mixed request stays one transaction: parent-child-first ordering
and the whole-graph cycle gate span both planes, and a refusal rolls back
both. Behind the role, three bulk add verbs collapsed into one source-routed
AddDependencies, so no plane-pinned variant is left to reach for by mistake.

Six Provenance fields with no production caller were deleted rather than
wired — CloseRequest, CloseBatchRequest, ClaimNextRequest, AddCommentRequest,
AddDependenciesRequest, RemoveDependencyRequest. Each role already composes an
id-bearing message, so a caller could only restate the default and make it
unreachable from production. Two are not caller-settable even in principle:
CloseBatchCommitMessage names what LANDED and ClaimNextCommitMessage names the
id the claim WON. UpdateRequest and ReopenRequest keep theirs; commit messages
users see are unchanged.

Verified: build, vet and gofmt clean; golangci-lint 0 issues; protocol corpus
byte-identical under BEADS_PROTOCOL_REQUIRE_DOLT=1; all twelve
DependencyEditor conformance wirings green (four contract functions against
each implementation); TestEmbeddedDepAddWispSource runs bd dep add <wisp-id>
at the front door and was demonstrated RED against the pinned routing first.
Three internal/storage/dolt failures reproduce on pristine origin/main.

Known gaps are enumerated in the PR description rather than left to be found:
comment listing is on no role, bd dep tree and bd dep cycles have no role,
bd create and bd reopen are on Lifecycle only on the direct route, per-edge
line attribution is lost in bd dep add --file, multi-store bd close
--claim-next rides only the first store's batch, and the is_blocked staging gap
(bd-2y9ke, predates this change). Seven of the eight role interfaces now have a
shared conformance contract in backend/conformance, run at all three
implementations; main's Claimer, added in parallel by #5334, is the eighth and
has none yet.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 12:27:56 -07:00

765 lines
36 KiB
Go

package conformance
import (
"context"
"errors"
"reflect"
"testing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/types"
publicops "github.com/steveyegge/beads/issueops"
)
// This file holds the semantic contract every implementation of
// publicops.ReadyClaimer must satisfy. There are three accessors answering the
// role — the server-backed store, the embedded store, and the unit-of-work
// provider — but only two BODIES: the first two share
// internal/storage/issueops's ValidateClaimNextRequest and ExecuteClaimNext and
// differ in the transaction wrapper and the engine beneath it, while the
// unit-of-work
// implementation is separate code that reuses the same validator and the same
// workapi.BuildReadyFilter. Wiring all three is still worth it — the third run
// is what catches wrapper and engine divergence, which is where the claim's
// commit message diverged before the role existed — but a case passing three
// times is not three independent votes on the body.
//
// EVERY CASE IS SCOPED BY A LABEL, and that is load-bearing rather than
// stylistic. The ready front is a property of the whole database, not of an id
// prefix, so a claim seeded by one assertion is claimable by the next one. Each
// case therefore seeds rows carrying a label only it uses and asks its question
// through Filter.Labels, which is what lets the whole suite share one database
// — the unit-of-work wiring's one-provider-many-subtests shape depends on it,
// because a fresh provider there boots a real Dolt sql-server.
//
// EVERY CASE NAMES A SORT POLICY. ReadyRequest.Sort's empty value resolves to
// hybrid at the storage layer, which the leaf says no front door may rely on
// (issueops/reader.go:79-83); a contract that relied on it would be pinning the
// fallback instead of the order.
//
// NOT IN THIS CONTRACT: two racing claimers producing exactly one winner. That
// is a transaction property of the persistence boundary, not a promised result
// of the operation, and it belongs per-backend if it is written at all.
// ReadyClaimerFixture supplies adapter-specific storage access for the
// ready-claim assertions.
type ReadyClaimerFixture struct {
// IssuePrefix namespaces the ids each assertion seeds, so several of them
// can share one database.
IssuePrefix string
Claimer publicops.ReadyClaimer
// Reader is the SAME backend's reader accessor. One case needs it: the
// claim's filter is Reader.Ready's filter in the leaf's words ("the same
// type, not a parallel one shaped like it"), and the only way to observe
// that end to end is to ask both surfaces the one question and compare.
Reader publicops.Reader
// CreateIssue seeds a durable issue in the issues plane.
CreateIssue func(context.Context, *types.Issue, string) error
// CreateWisp seeds an ephemeral issue in the wisps plane. It is a separate
// field rather than an Ephemeral flag on CreateIssue because the three
// adapters reach the two planes through different verbs.
CreateWisp func(context.Context, *types.Issue, string) error
// AddDependency seeds ONE edge. The claim hydrates the row it wins, so a
// case that wants to see a non-zero cardinality has to put one there.
AddDependency func(context.Context, *types.Dependency, string) error
QueryScalar func(context.Context, string, []any, ...any) error
// CountHistory reports the fixture's durable history length, for the "at
// most one entry per call, none when nothing was eligible" clause. Nil
// means the backend cannot observe history: the case whose whole subject is
// that clause then SKIPS with that reason rather than passing quietly, and
// the cases that merely carry a delta check alongside their own subject
// drop the check and keep their subject. It is non-nil on all three
// fixtures today.
CountHistory func(context.Context) (int, error)
}
// RunReadyClaimerRejectsLimitOffsetAndEmptyActor pins the deterministic
// request-validation refusals — Limit set, Offset set, Actor empty
// (issueops/readyclaimer.go:15-23 and :7-8) — and the state clause that comes
// with them: "a validation failure leaves persistent state unchanged"
// (issueops/readyclaimer.go:56).
//
// Rejecting Limit and Offset is the visible half of a rule about the SCAN. A
// claim delivers one row however large the pool it walked, and the walk has to
// stay unbounded so a window that happens to be unclaimable does not report
// "nothing to claim" while other ready work waits. Accepting the two fields and
// quietly dropping them would be the same behavior with the promise hidden.
// An explicit zero limit is refused with the rest: Limit is a pointer so that
// "unset" and "explicitly unlimited" stay distinguishable
// (issueops/reader.go:85-100), and only the first of those is what this request
// permits.
//
// The claimable row seeded here is the point of the state half: each refusal
// runs against a front that WOULD have yielded it, so an implementation that
// validated after claiming fails on the row rather than on the error.
//
// WHAT IS DELIBERATELY NOT ASSERTED: the result value. The leaf says "Result
// values are unspecified when error is non-nil" (issueops/readyclaimer.go:55),
// so a case checking that the refused call also returned a zero result would be
// pinning today's implementations rather than the contract. The state
// assertions below are the part the contract does promise.
func RunReadyClaimerRejectsLimitOffsetAndEmptyActor(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) {
t.Helper()
label := fixture.IssuePrefix + "-rcreject"
candidate := fixture.IssuePrefix + "-rcreject-a"
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(candidate, 1, label))
before := readyClaimerHistoryCount(t, ctx, fixture)
limit := 5
unlimited := 0
for _, refusal := range []struct {
name string
request publicops.ClaimNextRequest
}{
{"limit", publicops.ClaimNextRequest{
Actor: "claimer",
Filter: publicops.ReadyRequest{Labels: []string{label}, Sort: readyClaimerSort, Limit: &limit},
}},
{"explicitly unlimited limit", publicops.ClaimNextRequest{
Actor: "claimer",
Filter: publicops.ReadyRequest{Labels: []string{label}, Sort: readyClaimerSort, Limit: &unlimited},
}},
{"offset", publicops.ClaimNextRequest{
Actor: "claimer",
Filter: publicops.ReadyRequest{Labels: []string{label}, Sort: readyClaimerSort, Offset: 1},
}},
{"empty actor", publicops.ClaimNextRequest{
Filter: publicops.ReadyRequest{Labels: []string{label}, Sort: readyClaimerSort},
}},
} {
if _, err := fixture.Claimer.ClaimNext(ctx, refusal.request); !errors.Is(err, storage.ErrValidation) {
t.Errorf("ClaimNext with %s: error = %v, want ErrValidation", refusal.name, err)
}
}
// Unchanged means unchanged: the row a valid request would have won is
// still open and unassigned, and nothing was written to history.
assertReadyClaimerRowState(t, ctx, fixture, candidate, string(types.StatusOpen), "")
assertReadyClaimerHistoryDelta(t, ctx, fixture, before, 0, "four refused requests")
}
// RunReadyClaimerEmptyFrontIsNormal pins the outcome most likely to diverge: a
// drained queue answers with a nil Claimed and a NIL ERROR
// (issueops/readyclaimer.go:32-37). An empty front is the steady state of a
// polling agent, and one that had to classify an error to discover it would be
// pattern-matching prose. Nothing is written and no history entry is recorded
// (issueops/readyclaimer.go:35-36, :71-72), so an implementation that commits an
// empty transaction fails here too.
//
// The decoy is what makes the case about the FRONT rather than about an empty
// database: a ready, claimable row exists throughout, it simply does not match
// the filter, and it must still be sitting there afterwards.
func RunReadyClaimerEmptyFrontIsNormal(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) {
t.Helper()
label := fixture.IssuePrefix + "-rcempty"
decoy := fixture.IssuePrefix + "-rcempty-decoy"
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(decoy, 0, label+"-other"))
before := readyClaimerHistoryCount(t, ctx, fixture)
result, err := fixture.Claimer.ClaimNext(ctx, publicops.ClaimNextRequest{
Actor: "claimer",
Filter: publicops.ReadyRequest{Labels: []string{label}, Sort: readyClaimerSort},
})
if err != nil {
t.Fatalf("ClaimNext against an empty ready front: error = %v, want nil — an empty front is a normal outcome, not an error", err)
}
if result.Claimed != nil {
t.Fatalf("ClaimNext against an empty ready front claimed %s, want nil", result.Claimed.ID)
}
assertReadyClaimerRowState(t, ctx, fixture, decoy, string(types.StatusOpen), "")
assertReadyClaimerHistoryDelta(t, ctx, fixture, before, 0, "a claim that found nothing")
}
// RunReadyClaimerClaimsTheFrontRowAndReturnsThePostClaimState pins the winning
// path: the first row in the requested order moves to in-progress with the
// assignee set to Actor, and the RETURNED row is the post-claim row rather than
// the pre-claim one (issueops/readyclaimer.go:28-31).
//
// What it does NOT try to prove is the transactional simultaneity itself. That
// selection, the compare-and-set and the hydration share one transaction is not
// black-box observable; what is observable is that the snapshot handed back
// equals the state left in the database, and that the cardinalities are
// populated from real edges rather than zeroed. Both halves of that are here,
// and the seeded edges are why the count assertion can be an equality instead of
// a "not obviously empty".
func RunReadyClaimerClaimsTheFrontRowAndReturnsThePostClaimState(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) {
t.Helper()
label := fixture.IssuePrefix + "-rcwin"
winner := fixture.IssuePrefix + "-rcwin-a"
runnerUp := fixture.IssuePrefix + "-rcwin-b"
// A CLOSED blocker: it gives the winner a dependency to count without
// taking it off the ready front.
blocker := fixture.IssuePrefix + "-rcwin-blocker"
dependent := fixture.IssuePrefix + "-rcwin-dependent"
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(winner, 0, label))
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(runnerUp, 1, label))
closed := readyClaimerIssue(blocker, 1, label+"-blocker")
closed.Status = types.StatusClosed
seedReadyClaimerIssue(t, ctx, fixture, closed)
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(dependent, 1, label+"-dependent"))
seedReadyClaimerEdge(t, ctx, fixture, winner, blocker)
seedReadyClaimerEdge(t, ctx, fixture, dependent, winner)
result, err := fixture.Claimer.ClaimNext(ctx, publicops.ClaimNextRequest{
Actor: "claimer",
Filter: publicops.ReadyRequest{Labels: []string{label}, Sort: readyClaimerSort},
})
if err != nil {
t.Fatalf("ClaimNext against a seeded ready front: %v", err)
}
if result.Claimed == nil {
t.Fatal("ClaimNext returned no row against a front holding two claimable issues")
}
if result.Claimed.ID != winner {
t.Fatalf("claimed %s, want %s — the first row of the requested order", result.Claimed.ID, winner)
}
if result.Claimed.Issue == nil {
t.Fatal("claimed row carries a nil Issue")
}
if result.Claimed.Issue.Status != types.StatusInProgress {
t.Errorf("returned status = %q, want %q", result.Claimed.Issue.Status, types.StatusInProgress)
}
if result.Claimed.Issue.Assignee != "claimer" {
t.Errorf("returned assignee = %q, want %q", result.Claimed.Issue.Assignee, "claimer")
}
if result.Claimed.DependencyCount != 1 {
t.Errorf("returned DependencyCount = %d, want 1 — the claim hydrates the row it won", result.Claimed.DependencyCount)
}
if result.Claimed.DependentCount != 1 {
t.Errorf("returned DependentCount = %d, want 1 — the claim hydrates the row it won", result.Claimed.DependentCount)
}
// The returned snapshot IS the stored state, not a projection of the row
// as it was before the compare-and-set.
assertReadyClaimerRowState(t, ctx, fixture,
winner, string(result.Claimed.Issue.Status), result.Claimed.Issue.Assignee)
assertReadyClaimerRowState(t, ctx, fixture, winner, string(types.StatusInProgress), "claimer")
// One row is won per call, so the runner-up is untouched.
assertReadyClaimerRowState(t, ctx, fixture, runnerUp, string(types.StatusOpen), "")
}
// RunReadyClaimerClaimsAnEphemeralRowTheFilterAdmits pins the ephemeral half of
// the ready set: "a filter that sets IncludeEphemeral pulls [ephemeral rows] in
// for the claim exactly as it does for the listing: such a row IS claimable"
// (issueops/readyclaimer.go:63-76). The wisp seeded here is ready by every other
// measure and the request opts ephemeral rows in, so the listing offers it — and
// the claim takes it.
//
// The case asserts through Reader.Ready first, and fails there rather than
// silently degenerating, because "the claim took the row the listing offered" is
// only meaningful when the listing offered one. A seed that never reached the
// front would make this a second copy of the winning-path case.
//
// Three things beyond "it returned a row" are asserted, because each is a
// separate way an implementation could plausibly interpret the clause and get it
// wrong:
// - the EPHEMERAL row moved. The claim lands on the row that was offered, not
// on a durable copy of it, so the wisps row carries the actor.
// - no durable row appeared. Claiming an ephemeral row must not promote it.
// - durable history did not move. Ephemeral rows are not versioned, so the
// leaf's "a claim that wins an EPHEMERAL row records none either" is the
// visible consequence a `bd dolt log` reader would otherwise be surprised
// by. This is the ONE ready-claim outcome that mutates state without a
// history entry, which is exactly why it is pinned rather than assumed.
//
// bd-yby99.4 adjudicated this. The case previously asserted the opposite — that
// the claim declines a ready wisp — on the strength of a leaf sentence reading
// "the ready set is the issues plane". All three backends claimed the wisp
// anyway; the owner ruled the implementations right and the sentence wrong, so
// the sentence and this case inverted together.
func RunReadyClaimerClaimsAnEphemeralRowTheFilterAdmits(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) {
t.Helper()
label := fixture.IssuePrefix + "-rcwisp"
wisp := fixture.IssuePrefix + "-rcwisp-w"
seedReadyClaimerWisp(t, ctx, fixture, readyClaimerIssue(wisp, 0, label))
request := publicops.ReadyRequest{
Labels: []string{label},
Sort: readyClaimerSort,
IncludeEphemeral: true,
}
page, err := fixture.Reader.Ready(ctx, request)
if err != nil {
t.Fatalf("Reader.Ready over the seeded wisp: %v", err)
}
if !readyClaimerPageHas(page, wisp) {
t.Fatalf("Reader.Ready did not offer the seeded ready wisp %s (page: %v); "+
"the case cannot say the claim took a row the front never held", wisp, readyClaimerPageIDs(page))
}
before := readyClaimerHistoryCount(t, ctx, fixture)
result, err := fixture.Claimer.ClaimNext(ctx, publicops.ClaimNextRequest{Actor: "claimer", Filter: request})
if err != nil {
t.Fatalf("ClaimNext over a front holding one ready wisp: error = %v, want nil", err)
}
if result.Claimed == nil {
t.Fatal("ClaimNext returned no row against a front holding one ready wisp that IncludeEphemeral admitted")
}
if result.Claimed.ID != wisp {
t.Fatalf("claimed %s, want the ephemeral row %s the filter admitted", result.Claimed.ID, wisp)
}
if result.Claimed.Issue == nil {
t.Fatal("claimed row carries a nil Issue")
}
if result.Claimed.Issue.Status != types.StatusInProgress {
t.Errorf("returned status = %q, want %q", result.Claimed.Issue.Status, types.StatusInProgress)
}
if result.Claimed.Issue.Assignee != "claimer" {
t.Errorf("returned assignee = %q, want %q", result.Claimed.Issue.Assignee, "claimer")
}
assertReadyClaimerWispState(t, ctx, fixture, wisp, string(types.StatusInProgress), "claimer")
assertReadyClaimerRowAbsent(t, ctx, fixture, "issues", wisp)
assertReadyClaimerHistoryDelta(t, ctx, fixture, before, 0, "a claim that won an ephemeral row")
}
// RunReadyClaimerLeavesEphemeralRowsOutOfTheDefaultReadySet pins the DEFAULT
// half of the same clause the case above pins the opt-in half of: "Ephemeral
// rows are outside [the ready set] by default, and a filter that sets
// IncludeEphemeral pulls them in for the claim exactly as it does for the
// listing" (issueops/readyclaimer.go:65-67). A request that never mentions
// ephemeral rows never claims one.
//
// The two halves fail independently and only one of them was pinned anywhere.
// The reader contract pins the default gate for the LISTING
// (RunReaderReadyDeferredAndEphemeralGates), not for the claim; and after
// bd-yby99.4 inverted the opt-in case, an implementation that overcorrected
// into always admitting wisps would hand an agent work `bd ready` never offered
// it — the failure that clause exists to prevent — with nothing failing.
//
// The listing probe is what keeps the nil honest. The seeded wisp is ready by
// every other measure, and the ONLY difference between the request that offers
// it and the request that must not claim it is IncludeEphemeral, so a nil
// Claimed here cannot be a mis-seeded row or a label that matches nothing.
func RunReadyClaimerLeavesEphemeralRowsOutOfTheDefaultReadySet(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) {
t.Helper()
label := fixture.IssuePrefix + "-rcdefault"
wisp := fixture.IssuePrefix + "-rcdefault-w"
seedReadyClaimerWisp(t, ctx, fixture, readyClaimerIssue(wisp, 0, label))
admitted := publicops.ReadyRequest{Labels: []string{label}, Sort: readyClaimerSort, IncludeEphemeral: true}
page, err := fixture.Reader.Ready(ctx, admitted)
if err != nil {
t.Fatalf("Reader.Ready over the seeded wisp with IncludeEphemeral: %v", err)
}
if !readyClaimerPageHas(page, wisp) {
t.Fatalf("Reader.Ready did not offer the seeded ready wisp %s even with IncludeEphemeral (page: %v); "+
"a nil claim below would then say nothing about the default gate", wisp, readyClaimerPageIDs(page))
}
before := readyClaimerHistoryCount(t, ctx, fixture)
result, err := fixture.Claimer.ClaimNext(ctx, publicops.ClaimNextRequest{
Actor: "claimer",
Filter: publicops.ReadyRequest{Labels: []string{label}, Sort: readyClaimerSort},
})
if err != nil {
t.Fatalf("ClaimNext with IncludeEphemeral unset: error = %v, want nil — a front holding only ephemeral rows is an EMPTY front, not a failure", err)
}
if result.Claimed != nil {
t.Fatalf("ClaimNext claimed %s with IncludeEphemeral unset; ephemeral rows are outside the default ready set, "+
"so this hands an agent work the listing never offered it", result.Claimed.ID)
}
assertReadyClaimerWispState(t, ctx, fixture, wisp, string(types.StatusOpen), "")
assertReadyClaimerHistoryDelta(t, ctx, fixture, before, 0, "a default claim over a front holding one ephemeral row")
}
// RunReadyClaimerLeasesADurableWinButNotAnEphemeralOne pins both halves of the
// lease clause, in one case, because each half is what makes the other mean
// something.
//
// THE AFFIRMATIVE: "A DURABLE win grants EXACTLY ONE LEASE on the row it won"
// (issueops/readyclaimer.go:78-82). THE NEGATIVE: "An ephemeral win carries NO
// LEASE, which is the sharper of the two consequences because it has no expiry
// to wait out" (readyclaimer.go:84-90).
//
// Asserting the zero alone would be half vacuous: a backend whose leases table
// this fixture cannot reach reports zero for the wisp too, and a backend that
// stopped leasing durable claims entirely would pass. Asserting the one alone
// would say nothing about the recovery story the leaf tells a caller it does
// NOT get for a wisp. Together the pair says the query can see lease rows AND
// that the plane is what decides whether there is one.
//
// The clause's other half — heartbeats refuse an ephemeral row, lease-expiry
// recovery only walks leased durable ones — is a promise about OTHER verbs and
// is not observable through ClaimNext; the lease row is the part this seam can
// see, and it is what makes those two true.
//
// (This was a spec gap, bd-yby99.13: the durable check was a probe rather
// than an assertion; the owner ratified the affirmative and the probe became
// the assertion it already looked like.)
func RunReadyClaimerLeasesADurableWinButNotAnEphemeralOne(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) {
t.Helper()
ephemeralLabel := fixture.IssuePrefix + "-rclease-eph"
durableLabel := fixture.IssuePrefix + "-rclease-dur"
wisp := fixture.IssuePrefix + "-rclease-w"
durable := fixture.IssuePrefix + "-rclease-d"
seedReadyClaimerWisp(t, ctx, fixture, readyClaimerIssue(wisp, 0, ephemeralLabel))
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(durable, 0, durableLabel))
won := readyClaimerWin(t, ctx, fixture, publicops.ReadyRequest{
Labels: []string{ephemeralLabel}, Sort: readyClaimerSort, IncludeEphemeral: true,
})
if won != wisp {
t.Fatalf("claimed %s, want the ephemeral row %s", won, wisp)
}
assertReadyClaimerWispState(t, ctx, fixture, wisp, string(types.StatusInProgress), "claimer")
if leases := readyClaimerLeaseCount(t, ctx, fixture, wisp); leases != 0 {
t.Errorf("the ephemeral win left %d leases row(s) for %s, want 0 — a leased wisp joins the lease-expiry "+
"recovery walk, which is the recovery story the leaf tells a caller it does NOT get", leases, wisp)
}
won = readyClaimerWin(t, ctx, fixture, publicops.ReadyRequest{Labels: []string{durableLabel}, Sort: readyClaimerSort})
if won != durable {
t.Fatalf("claimed %s, want the durable row %s", won, durable)
}
if leases := readyClaimerLeaseCount(t, ctx, fixture, durable); leases != 1 {
t.Fatalf("the durable win left %d leases row(s) for %s, want exactly 1 — a durable claim with no lease is work "+
"nothing can take back, because heartbeats have no handle to extend and lease-expiry recovery never sees it",
leases, durable)
}
}
// RunReadyClaimerAnswersTheQuestionReaderReadyLists pins the filter's
// provenance (issueops/readyclaimer.go:9-14): the claim's predicate is the
// listing's predicate, because the request type IS Reader.Ready's request type
// and there is one builder behind both. Asserting it costs one shared seed and
// it encodes the rule that motivates the whole clause — a claim must not hand an
// agent work the listing never offered it.
//
// The high-priority outsider is the half that makes the agreement mean
// something. It would win an unfiltered claim, so a request whose filter was
// dropped or widened anywhere between the two surfaces takes it instead, and
// this case says so.
func RunReadyClaimerAnswersTheQuestionReaderReadyLists(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) {
t.Helper()
label := fixture.IssuePrefix + "-rcagree"
selected := fixture.IssuePrefix + "-rcagree-a"
wrongPriority := fixture.IssuePrefix + "-rcagree-b"
outsider := fixture.IssuePrefix + "-rcagree-outsider"
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(selected, 1, label))
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(wrongPriority, 2, label))
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(outsider, 0, label+"-outsider"))
priority := 1
request := publicops.ReadyRequest{Labels: []string{label}, Priority: &priority, Sort: readyClaimerSort}
page, err := fixture.Reader.Ready(ctx, request)
if err != nil {
t.Fatalf("Reader.Ready: %v", err)
}
if len(page.Items) == 0 {
t.Fatal("Reader.Ready listed nothing for a filter matching a seeded ready issue")
}
listedFirst := page.Items[0].ID
result, err := fixture.Claimer.ClaimNext(ctx, publicops.ClaimNextRequest{Actor: "claimer", Filter: request})
if err != nil {
t.Fatalf("ClaimNext: %v", err)
}
if result.Claimed == nil {
t.Fatalf("ClaimNext returned nothing for the filter Reader.Ready answered with %v", readyClaimerPageIDs(page))
}
if result.Claimed.ID != listedFirst {
t.Errorf("claimed %s but Reader.Ready listed %s first for the same request; "+
"the claim's predicate and the listing's predicate must be one predicate", result.Claimed.ID, listedFirst)
}
if result.Claimed.ID != selected {
t.Errorf("claimed %s, want %s", result.Claimed.ID, selected)
}
assertReadyClaimerRowState(t, ctx, fixture, outsider, string(types.StatusOpen), "")
}
// RunReadyClaimerSkipsIneligibleFrontRows makes the unbounded-scan rationale
// (issueops/readyclaimer.go:17-22) observable without a race. The top of the
// ready order is occupied by rows this actor cannot take — they are already
// assigned — and the claim must walk past them to the first row it CAN take
// rather than reporting an empty front.
//
// This is also where the claim's eligibility is narrower than the listing's:
// `bd ready` offers assigned open work, and the claim does not take it. Both
// halves are asserted, so a change that made the claim steal an assigned row
// fails here rather than in production.
func RunReadyClaimerSkipsIneligibleFrontRows(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) {
t.Helper()
label := fixture.IssuePrefix + "-rcskip"
takenFirst := fixture.IssuePrefix + "-rcskip-a"
takenSecond := fixture.IssuePrefix + "-rcskip-b"
eligible := fixture.IssuePrefix + "-rcskip-c"
first := readyClaimerIssue(takenFirst, 0, label)
first.Assignee = "other-agent"
second := readyClaimerIssue(takenSecond, 1, label)
second.Assignee = "other-agent"
seedReadyClaimerIssue(t, ctx, fixture, first)
seedReadyClaimerIssue(t, ctx, fixture, second)
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(eligible, 2, label))
request := publicops.ReadyRequest{Labels: []string{label}, Sort: readyClaimerSort}
page, err := fixture.Reader.Ready(ctx, request)
if err != nil {
t.Fatalf("Reader.Ready: %v", err)
}
if !readyClaimerPageHas(page, takenFirst) {
t.Fatalf("Reader.Ready did not offer the assigned row %s (page: %v); "+
"the case needs an ineligible row AT THE FRONT to have anything to skip", takenFirst, readyClaimerPageIDs(page))
}
result, err := fixture.Claimer.ClaimNext(ctx, publicops.ClaimNextRequest{Actor: "claimer", Filter: request})
if err != nil {
t.Fatalf("ClaimNext over a front whose first rows are ineligible: %v", err)
}
if result.Claimed == nil {
t.Fatal("ClaimNext returned nothing while an eligible row sat behind two ineligible ones")
}
if result.Claimed.ID != eligible {
t.Fatalf("claimed %s, want %s — the first ELIGIBLE row", result.Claimed.ID, eligible)
}
assertReadyClaimerRowState(t, ctx, fixture, takenFirst, string(types.StatusOpen), "other-agent")
assertReadyClaimerRowState(t, ctx, fixture, takenSecond, string(types.StatusOpen), "other-agent")
}
// RunReadyClaimerRecordsOneHistoryEntryForAWin pins the counting half of "at
// most one durable history entry [per call], and none at all when nothing was
// eligible" (issueops/readyclaimer.go:71-76). The empty-front half lives in
// RunReadyClaimerEmptyFrontIsNormal, where the call that records nothing is the
// subject; the ephemeral half — a win that also records nothing, because
// ephemeral rows are not versioned — lives in
// RunReadyClaimerClaimsAnEphemeralRowTheFilterAdmits; here the subject is the
// DURABLE win, which records exactly one.
//
// It counts a DELTA around the operation rather than reading the top of the
// log: two commits made inside the same second tie on date, and their relative
// order is not something to rely on. What the entry SAYS — the commit-message
// spelling — is deliberately not here; that is single-sourced in
// internal/storage/issueops and pinning it three times would be duplication.
func RunReadyClaimerRecordsOneHistoryEntryForAWin(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) {
t.Helper()
if fixture.CountHistory == nil {
t.Skip("fixture cannot observe durable history, so the entry-per-call clause is unobservable on this backend")
}
label := fixture.IssuePrefix + "-rchist"
winner := fixture.IssuePrefix + "-rchist-a"
seedReadyClaimerIssue(t, ctx, fixture, readyClaimerIssue(winner, 0, label))
before := readyClaimerHistoryCount(t, ctx, fixture)
result, err := fixture.Claimer.ClaimNext(ctx, publicops.ClaimNextRequest{
Actor: "claimer",
Filter: publicops.ReadyRequest{Labels: []string{label}, Sort: readyClaimerSort},
})
if err != nil {
t.Fatalf("ClaimNext: %v", err)
}
if result.Claimed == nil {
t.Fatal("ClaimNext returned nothing against a front holding one claimable issue")
}
assertReadyClaimerHistoryDelta(t, ctx, fixture, before, 1, "a winning claim")
}
// RunReadyClaimerDoesNotMutateTheCallerRequest is the request-snapshot
// tripwire the leaf promises in so many words: "Implementations never mutate
// caller-owned request values, snapshot the request at method entry, and apply
// validation and normalization only to attempt-local clones"
// (issueops/readyclaimer.go:52-56).
//
// The request is passed by value, so only its REFERENCE members can carry a
// mutation back to the caller — the four label slices, ExcludeTypes,
// MetadataFields and the Priority pointer. Every one of them is populated here
// with a value normalization would want to touch, and the comparison is against
// a second copy built by the same function, so an in-place trim, dedupe, sort,
// alias expansion or write-through fails.
//
// The filter matches nothing on purpose. The promise is about the request, not
// about the outcome, and an empty front is the one outcome that is guaranteed
// not to depend on what the rest of the suite has seeded.
func RunReadyClaimerDoesNotMutateTheCallerRequest(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) {
t.Helper()
build := func() publicops.ClaimNextRequest {
priority := 2
return publicops.ClaimNextRequest{
Actor: "claimer",
Filter: publicops.ReadyRequest{
IssueType: " Task ",
Labels: []string{fixture.IssuePrefix + "-rcsnap ", fixture.IssuePrefix + "-rcsnap "},
LabelsAny: []string{" " + fixture.IssuePrefix + "-rcsnap-any"},
ExcludeLabels: []string{fixture.IssuePrefix + "-rcsnap-not "},
ExcludeTypes: []string{"mr,epic", " chore "},
MetadataFields: map[string]string{"team": "conformance"},
HasMetadataKey: "team",
Priority: &priority,
Sort: readyClaimerSort,
},
}
}
request := build()
want := build()
if _, err := fixture.Claimer.ClaimNext(ctx, request); err != nil {
t.Fatalf("ClaimNext with a fully populated filter: %v", err)
}
if !reflect.DeepEqual(request, want) {
t.Errorf("ClaimNext mutated the caller's request:\n got %+v\nwant %+v", request, want)
}
}
// readyClaimerSort is the order every case names. It is the policy whose SQL is
// a plain "ORDER BY priority, created_at, id", so a seed with distinct
// priorities has one unambiguous front row — hybrid's recency bucket would make
// the winner depend on when the fixture was seeded.
const readyClaimerSort = "priority"
func readyClaimerIssue(id string, priority int, labels ...string) *types.Issue {
return &types.Issue{
ID: id,
Title: id,
Status: types.StatusOpen,
Priority: priority,
IssueType: types.TypeTask,
Labels: labels,
}
}
func seedReadyClaimerIssue(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture, issue *types.Issue) {
t.Helper()
if err := fixture.CreateIssue(ctx, issue, "seed"); err != nil {
t.Fatalf("seed issue %s: %v", issue.ID, err)
}
}
func seedReadyClaimerWisp(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture, issue *types.Issue) {
t.Helper()
issue.Ephemeral = true
if err := fixture.CreateWisp(ctx, issue, "seed"); err != nil {
t.Fatalf("seed wisp %s: %v", issue.ID, err)
}
}
func seedReadyClaimerEdge(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture, issueID, dependsOnID string) {
t.Helper()
if err := fixture.AddDependency(ctx, &types.Dependency{
IssueID: issueID, DependsOnID: dependsOnID, Type: types.DepBlocks,
}, "seed"); err != nil {
t.Fatalf("seed edge %s -> %s: %v", issueID, dependsOnID, err)
}
}
// assertReadyClaimerRowState reads the durable row's status and assignee back
// out of the database. The assignee comes through COALESCE because an unclaimed
// row's column may be NULL or empty depending on how it was seeded, and the
// three fixtures' scan paths do not agree on what a NULL means.
func assertReadyClaimerRowState(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture, id, wantStatus, wantAssignee string) {
t.Helper()
assertReadyClaimerPlaneRowState(t, ctx, fixture, "issues", id, wantStatus, wantAssignee)
}
func assertReadyClaimerWispState(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture, id, wantStatus, wantAssignee string) {
t.Helper()
assertReadyClaimerPlaneRowState(t, ctx, fixture, "wisps", id, wantStatus, wantAssignee)
}
// assertReadyClaimerRowAbsent checks that a plane holds no row for id. It
// counts rather than scanning one, so "absent" and "present but unreadable"
// cannot be confused: a failed scan would be a fixture error, an empty count is
// the answer.
func assertReadyClaimerRowAbsent(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture, table, id string) {
t.Helper()
var rows int
//nolint:gosec // G201: table is one of the contract's two hardcoded names.
query := "SELECT COUNT(*) FROM " + table + " WHERE id = ?"
if err := fixture.QueryScalar(ctx, query, []any{id}, &rows); err != nil {
t.Fatalf("count %s rows for %s: %v", table, id, err)
}
if rows != 0 {
t.Errorf("%s holds %d row(s) for %s, want 0", table, rows, id)
}
}
func assertReadyClaimerPlaneRowState(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture, table, id, wantStatus, wantAssignee string) {
t.Helper()
var status, assignee string
//nolint:gosec // G201: table is one of the contract's two hardcoded names.
query := "SELECT status, COALESCE(assignee, '') FROM " + table + " WHERE id = ?"
if err := fixture.QueryScalar(ctx, query, []any{id}, &status, &assignee); err != nil {
t.Fatalf("read %s row %s: %v", table, id, err)
}
if status != wantStatus || assignee != wantAssignee {
t.Errorf("%s row %s = (status %q, assignee %q), want (%q, %q)",
table, id, status, assignee, wantStatus, wantAssignee)
}
}
// readyClaimerWin runs one claim that is expected to take a row and reports the
// id it won. A nil Claimed is fatal here rather than a returned empty string,
// because every caller of this helper is asserting something ABOUT the win.
func readyClaimerWin(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture, filter publicops.ReadyRequest) string {
t.Helper()
result, err := fixture.Claimer.ClaimNext(ctx, publicops.ClaimNextRequest{Actor: "claimer", Filter: filter})
if err != nil {
t.Fatalf("ClaimNext(labels=%v, includeEphemeral=%v): %v", filter.Labels, filter.IncludeEphemeral, err)
}
if result.Claimed == nil {
t.Fatalf("ClaimNext(labels=%v, includeEphemeral=%v) returned no row against a front seeded to hold one",
filter.Labels, filter.IncludeEphemeral)
}
return result.Claimed.ID
}
// readyClaimerLeaseCount reports how many lease rows the ephemeral leases table
// holds for id. The table is a plain SQL table on every backend
// (internal/storage/schema/cli_migrations.go:108-115), reached here through the
// same QueryScalar the row-state assertions use.
func readyClaimerLeaseCount(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture, id string) int {
t.Helper()
var rows int
if err := fixture.QueryScalar(ctx, "SELECT COUNT(*) FROM leases WHERE issue_id = ?", []any{id}, &rows); err != nil {
t.Fatalf("count leases for %s: %v", id, err)
}
return rows
}
func readyClaimerHistoryCount(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture) int {
t.Helper()
if fixture.CountHistory == nil {
return -1
}
entries, err := fixture.CountHistory(ctx)
if err != nil {
t.Fatalf("count history: %v", err)
}
return entries
}
// assertReadyClaimerHistoryDelta checks how far the durable history moved.
// A fixture that cannot observe history reports -1 from
// readyClaimerHistoryCount and the check is skipped there rather than passing
// on an arithmetic accident.
func assertReadyClaimerHistoryDelta(t *testing.T, ctx context.Context, fixture ReadyClaimerFixture, before, want int, subject string) {
t.Helper()
if before < 0 {
return
}
after := readyClaimerHistoryCount(t, ctx, fixture)
if after-before != want {
t.Errorf("history entries went %d -> %d across %s, want exactly %d more", before, after, subject, want)
}
}
func readyClaimerPageHas(page publicops.IssuePage, id string) bool {
for _, item := range page.Items {
if item != nil && item.ID == id {
return true
}
}
return false
}
func readyClaimerPageIDs(page publicops.IssuePage) []string {
ids := make([]string, 0, len(page.Items))
for _, item := range page.Items {
if item != nil {
ids = append(ids, item.ID)
}
}
return ids
}