beads/issueops/readyclaimer.go
Stephanie Jarmak 7e825441b4
feat(workapi,storage): opt-in Brief projection for the list and ready pages (#5554)
STORAGE LAYER ONLY, per CONTRIBUTING_PR_GUIDELINES.md. issueops.ListRequest
and issueops.ReadyRequest gain Brief; no CLI flag and no HTTP parameter sets
it yet, so no front door's payload changes. The wiring stacks on top.

WHAT IT DROPS is the free-form text: description, design, acceptance_criteria,
notes, payload and waiters are not selected, and the row comes back carrying
types.Issue.IsLitePartial. #5546 measured a 16,051-issue store where
`bd ready --json` returned 454,021 bytes and notes plus description were 76% of
it, on the call an agent makes to decide what to work on. Measured through
issueops.Reader on 100 rows sized from those per-row ratios: 362,301 bytes
full, 24,001 brief, a 93.4% reduction.

THE PRIMITIVE WAS HALF-BUILT AND UNREACHABLE. #3906 landed
types.IssueFilter.Lite, IssueSelectColumnsLite, HeavyDropList,
ScanIssueLiteFrom and Issue.IsLitePartial, then wired filter.Lite into exactly
one place: SearchIssuesInTx, the UNCOUNTED store-backed search. Every read that
answers with IssueWithCounts, which is every --json route of both commands,
both implementations of issueops.Reader, and both HTTP reads, runs the counts
mega-query instead and ignored the field. A request that set it would have come
back correct, fully hydrated, and with nothing on it to say the projection had
not happened. That silent no-op is what this closes.

THE APPLICATION POINT IS THE COUNTS MEGA-QUERY, and it is one point rather than
four because sqlbuild.SearchCountsSQL and issueops.ScanReadyWorkRowWithCounts
are already the pair every counted read passes through: the store seam's list
(search_counts.go) and ready (ready_work_counts.go), and the unit-of-work
seam's list (issue_search_counts.go) and ready (ready_work_union.go, via
fetchCountsByIDs). sqlbuild.CountsHydration is already the value that carries
hydration opt-outs across that pair on both seams, so Lite is a third field on
it rather than a new channel.

IT CHANGES THE PROJECTION'S SHAPE, which SkipLabels and SkipCounts do not, and
that is why ScanReadyWorkRowWithCounts now takes the whole hydration instead of
a bool: the value that chose the SELECT list is the value that drives the scan,
so the two cannot be given different answers. Substituting empty strings in the
heavy positions would have kept one scan path and was rejected, because the row
would carry blank text with IsLitePartial=false, which is indistinguishable
from a genuinely textless row, the ambiguity ga-clgh and CommentsOmitted
already record.

WHERE IS INDEPENDENT OF SELECT, so this bounds the size of a row and never
which rows match: DescContains, NotesContains and EmptyDesc keep selecting
exactly what they select today, and no sort key, keyset cursor or wisp-merge
dedup reads a dropped column (CompareIssuesBy orders on nine fields, none of
them heavy).

THE CLAIM REFUSES IT, which is not the same call the page makes and is the
sharper case of the rule Limit and Offset already state. A claim does not read
its row through the page's query at all: ExecuteClaimNext refetches the winning
row whole with GetIssueInTx and hydrates its counts itself, so the projection
has nothing to apply to. Accepting the field would answer a MUTATING request
with a fully hydrated row carrying IsLitePartial=false, the caller's one signal
that it did not get what it asked for, reporting that it did. The check lives
in issueops.ValidateClaimNextRequest, which is the shared rule both ready
claimers and BatchCloser's claim already run, so all four backends refuse it on
the same line.

BuildReadyCountFilter CARRIES it, which is the opposite treatment and the
opposite reason. A count reads no field of any row, so the projection cannot
make the number wrong, and the count is not always cheap enough for that to be
the end of it: the unit-of-work seam has no COUNT(*) over the ready predicate
and sizes the set by running the unbounded page and taking its length
(uow/ready_counter.go), so dropping the field there would hydrate every heavy
column of the whole ready set to answer `bd ready --brief`, a larger read than
the page it was asked for. Carrying it also keeps that builder what its doc
says it is: the listing's filter with the PAGE removed and nothing else.

TWO ASYMMETRIES on the page path, both deliberate and both stated in code:

  - Brief IS carried onto the --ready arm (ReadyFilterFromIssueFilter) where
    SkipLabels and SkipCounts are dropped. Those two hide a number the ready
    renderings print; this drops a body no listing prints, so carrying it is
    what makes `bd list --ready` and `bd ready` answer one request one way.
  - types.WorkFilter carries Lite and neither of the other two, so the ready
    paths get readyHydrationFor rather than hydrationFor. Before this, both
    uow ready call sites passed a hardcoded CountsHydration{}, a literal that
    could not carry a filter's answer at all, which is how that path would have
    been missed.

CONFORMANCE at all four registered sites, one Test per case, for the two page
cases and for the claim refusal. Every field the cases assert stripped is
seeded heavy first and the premise is checked, so a backend that never
round-trips one of the six fails loudly instead of turning that clause into one
that cannot fail. Identity is asserted too (ID, Title, Status, IssueType,
Priority), or a body that stripped the row to its id would satisfy every
emptiness clause. IsLitePartial is asserted in both directions.

THE LITE COLUMN LIST IS PINNED BY ORDER, not only by membership. Both lists are
scanned positionally, so two columns of the same SQL type can be transposed
with no membership change at all: the pre-existing set-based parity test stays
green, the scan succeeds, and every row silently carries one column's value in
another's field. TestIssueSelectColumnsLite_IsFullMinusHeavyInOrder derives the
expected list by deleting HeavyDropList from IssueSelectColumns in place, which
makes the lite list a derivation rather than a second hand-maintained copy.

RED BEFORE GREEN, five sabotages, each verified and reverted:

  - deleting the lite branch from CountsHydration.IssueColumns fails both page
    cases with "expected 58 destination arguments in Scan, not 52";
  - accepting Brief without plumbing it to either filter, the silent no-op this
    change exists to close, fails both page cases on all six text fields and on
    IsLitePartial, which is the run that proves the assertions are
    load-bearing;
  - transposing created_by and owner in IssueSelectColumnsLite fails only the
    new order test, on IssueSelectColumnsLite[9] = owner, want created_by,
    while the set-based test stays green, which is the gap it was added for;
  - dropping the claim's refusal fails the claimer contract with "ClaimNext
    with brief: error = <nil>, want ErrValidation"; and
  - clearing Brief in BuildReadyCountFilter fails
    TestBuildReadyCountFilterIsTheUnboundedReadyFilter, which already existed to
    catch a ReadyRequest field the count builder forgets to carry and gains
    Brief in its fixture here.

The recorded ready-filter golden gains "Lite": false in 62 cases because
types.WorkFilter gained the field and the test compares marshaled JSON
byte-for-byte. False is what a request that did not ask for the projection
resolves that field to, so the replay stays exact; the test comment says so.

Gates: go build ./..., go vet ./..., gofmt, internal/storage/... (dolt,
embeddeddolt with BEADS_TEST_EMBEDDED_DOLT=1, uow, issueops, sqlbuild,
domain/db), internal/workapi/..., backend/conformance/..., issueops/...,
make api-check.

Refs: #5546, #3906

Co-authored-by: sjarmak <t@t.co>
2026-08-10 10:45:23 -07:00

98 lines
5 KiB
Go

package issueops
import "context"
// ClaimNextRequest describes one atomic take of ready work.
type ClaimNextRequest struct {
// Actor is the claimant and must not be empty.
Actor string
// Filter selects the candidate set in Reader.Ready's EXACT vocabulary —
// the same type, not a parallel one shaped like it. A claim that answered
// a different question than `bd ready` shows would hand an agent work the
// listing never offered it, and two predicates that are allowed to differ
// eventually do.
//
// Limit and Offset must be unset (ErrValidation). A claim delivers exactly
// the one row it wins no matter how large the pool it scanned, and the
// scan itself must stay unbounded: the implementation walks the ready
// order and continues past rows a racing agent already took, so a bounded
// window would report "nothing to claim" whenever that window happened to
// be unclaimable while plenty of other ready work remained. Rejecting the
// two fields says that out loud rather than accepting them and quietly
// dropping them.
//
// Brief must be unset too, and for the same reason stated once more
// because this one costs a write: the claim refetches its winning row
// whole rather than reading it through the page's query, so the projection
// cannot be applied here, and accepting it would return an unprojected row
// from a request that has already mutated state.
Filter ReadyRequest
}
// ClaimNextResult reports the claim.
type ClaimNextResult struct {
// Claimed is the claimed row with its relationship cardinalities, hydrated
// inside the transaction that committed the claim, so the counts describe
// the state the claim actually produced rather than a later one.
//
// It is nil when nothing was eligible. That is a NORMAL outcome, not an
// error: an empty ready front is the steady state of a drained queue, and
// a polling agent that had to classify an error to discover it would be
// pattern-matching prose. Nothing is written and no history entry is
// recorded for it.
Claimed *IssueWithCounts
}
// ReadyClaimer describes the atomic take of ready work: the operation `bd
// ready --claim` performs, and — like Lifecycle and Reader — a role with its
// own accessor. A new capability gets a new role interface and its own
// accessor; never append a method here.
//
// It is a role of its own rather than a fifth Lifecycle verb because it is not
// a mutation of an issue the caller names. The caller names a QUESTION and the
// implementation picks the answer, which makes selection part of the
// operation's contract: the ready predicate, the compare-and-set that wins the
// row, and the hydration of the row that was won all belong to the same
// transaction, and none of them is expressible as a patch.
//
// Implementations never mutate caller-owned request values, snapshot the
// request at method entry, and apply validation and normalization only to
// attempt-local clones. Deterministic request-validation failures match
// ErrValidation. Result values are unspecified when error is non-nil; a
// validation failure leaves persistent state unchanged.
type ReadyClaimer interface {
// ClaimNext claims the first ready issue matching the request's filter and
// returns it hydrated. Selection, the compare-and-set and the hydration
// share ONE transaction, so the row cannot move between being chosen and
// being reported.
//
// The ready set is whatever the request's filter admits — the same set
// Reader.Ready lists for that filter, which is the whole point of the two
// surfaces sharing a request type. Ephemeral rows are outside it by
// default, and a filter that sets IncludeEphemeral pulls them in for the
// claim exactly as it does for the listing: such a row IS claimable, and
// claiming it moves the ephemeral row itself rather than promoting it to
// a durable one or refusing it.
//
// At most one durable history entry is recorded, and none at all when
// nothing was eligible. A claim that wins an EPHEMERAL row records none
// either: ephemeral rows are not versioned, so the row moves to
// in-progress under the actor while the durable history stands still. A
// caller reconstructing who took what from history alone will not see
// those claims — read the row.
//
// A DURABLE win grants EXACTLY ONE LEASE on the row it won. The lease is
// what makes the claim recoverable — it is the handle heartbeats extend,
// and the row lease-expiry recovery walks once nothing extends it — so a
// win that wrote no lease would hand out work nothing could ever take
// back.
//
// An ephemeral win carries NO LEASE, which is the sharper of the two
// consequences because it has no expiry to wait out. Heartbeats refuse an
// ephemeral row and lease-expiry recovery only walks leased durable ones,
// so nothing reclaims the row if its claimant dies: it stays in-progress
// under a gone actor until something releases or finishes it. A caller
// that hands ephemeral work to agents it does not supervise owns that
// recovery itself.
ClaimNext(ctx context.Context, req ClaimNextRequest) (ClaimNextResult, error)
}