`bd ready --limit 100` prints "showing 100 of 412", and the 412 came from
nowhere in particular. The direct route computed it inline: unwrap past the
storage decorators, type-assert to storage.ReadyWorkCounter, and fall back to
an unbounded ready query when the assertion missed — twice, once in the --json
branch and once in the text one, with two different fallbacks. The proxied
route could not compute it at all and published no `total` key, so the same
script read a number under one workspace topology and nothing under another.
THE ROLE. issueops.ReadyCounter, reached through store.ReadyCounter() and the
provider's own accessor. It answers a question neither neighbour can: Reader
answers with a PAGE and its verdict is has-more ("did the limit hide
anything"), where this is "how many" — strictly larger, and already published
output, so collapsing the two would change what a shipped surface says. Counter
answers a predicate over one table, and the ready predicate is blocker-aware:
it reads the dependency graph and the wisp tier, which no CountRequest can
describe. Counter's own doc already said the count of ready work would be its
own role for that reason.
It takes issueops.ReadyRequest VERBATIM, the precedent ClaimNextRequest set, so
a listing, a claim and a count ask ONE question of ONE set. Limit and Offset are
ErrValidation for the reason a claim refuses them: a cardinality has no page, so
a limit would answer "how many of the first N" and an offset would subtract the
rows it skipped from the size of a set that still holds them.
THE CONTRACT IS AN IDENTITY, not a resemblance:
CountReady(r).Total == len(Reader.Ready(r with Limit=0).Items)
at every implementation. backend/conformance/ready_counter_contract.go holds
seven cases, each citing the leaf doc by line, run at all three backends with
ZERO parks. They are TWO independent bodies plus an engine check: dolt and
embeddeddolt share internal/workapi/storereadycounter (one indexed COUNT(*) per
plane minus their overlap), and the unit-of-work provider is genuinely separate
code that runs the unbounded ready query and takes its length — which is why
the wisp-tier case is written the way it is, since that is where a COUNT and
the page it sizes are assembled by different arithmetic.
A DEFECT THIS FOUND, and it is not the count's. `bd ready`'s directory-label
default (GH#541) never reached the ReadyClaimer role. claimNextRequest re-ran
the gatherer's own emptiness test against in.filter — and the gatherer had
already written the default INTO that filter, so the test saw a non-empty label
set and skipped. The branch could never fire. In a directory with
`directory.labels` configured, `bd ready --claim` therefore claimed from the
WHOLE ready front while `bd ready` beside it listed only the configured scope:
exactly the "hand an agent work the listing never offered it" that
ReadyClaimer's contract exists to forbid. The gatherer now RECORDS its decision
(readyInput.dirLabels) and both roles read it, so there is one answer instead of
two derivations of it. Caught by writing the count's own test for the same
line, and pinned by cmd/bd/ready_role_request_test.go.
WHAT ELSE CONVERGED. Both routes and both output modes now ask one question
through one accessor: the direct route's two inline epilogues become one call,
and the proxied route's `pagination.total` exists for the first time. The
"showing X of N" text a human reads and the total a script parses are the same
number by construction. cmd/bd no longer names storage.ReadyWorkCounter at all
— the capability is required by the store body's PARAMETER TYPE, so a backend
that cannot size the ready set fails to compile instead of falling back to a
mega-query at runtime.
THE HTTP OPERATION, spec first (per bd-jtp1h's A2 scope decision):
GET /v0/beads/ready:count, capability `ready.count`, answering
`ReadyCount {total}`. It publishes no `limit` and no `sort`: a cardinality has
no page and no order, and the handler sends the listing's own sort default so
the request stays the listing's request rather than one that resembles it. The
filter vocabulary is decoded by ONE function shared with GET /v0/beads/ready
(readyFilters), so the two operations cannot admit different parameters — which
is what the identity rests on over the wire.
`TestCountReadyAndListReadyAdmitTheSameFilters` compares the two predicates
built from one query string. No component here carries allOf and none is
x-go-type-pinned: the pinned seven are canonical Go structs whose JSON encoding
IS the contract, and there is no canonical struct for this number — the CLI
publishes it inside its own stdout envelope, which is not a wire type — so
pinning would weld the body to a CLI presentation type rather than prevent a
drift. The generated output was read to confirm it (a struct with `Total
int64`, not an alias), which is the v2.6.0 trap this document warns about.
httpapi.Config's ROLES database source grows a REQUIRED third member. That is
the sharp edge for the next role commit and is now written down in
engdocs/ADDING_AN_ISSUEOPS_ROLE.md as step 13: a Config carrying the old pair
would bind and then nil-dereference on the first request that reached the new
handler, so Listen refuses it with the same message a half-set pair gets.
USER-VISIBLE, for the wave's changelog pass: proxied `bd ready --json --limit N`
now publishes `pagination.total`; `bd ready --claim` now honours the
directory-label scope on both routes.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
(regenerate-and-diff plus the httpapi suite) green; TestReadyCounterContract
7/7 at dolt, embeddeddolt and uow; the httpapi package suite; the direct-route
`bd ready` suites under BEADS_TEST_EMBEDDED_DOLT=1 and the proxied ones under
BEADS_TEST_PROXIED_SERVER=1, including the pagination envelope that now asserts
the total; TestProxiedLookup*; and the ready protocol-corpus tests, which are
byte-identical.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
95 lines
5.2 KiB
Go
95 lines
5.2 KiB
Go
package issueops
|
|
|
|
import "context"
|
|
|
|
// ReadyCountResult is the size of a ready set.
|
|
type ReadyCountResult struct {
|
|
// Total is how many rows the request's ready predicate admits. It is an
|
|
// int64 for the reason CountResult.Total is one — the counting seam counts
|
|
// in one — and not because a ready front is expected to be large.
|
|
Total int64
|
|
}
|
|
|
|
// ReadyCounter describes sizing the ready set: the question `bd ready`'s
|
|
// pagination answers when it reports "showing 100 of 412", and — like Reader,
|
|
// ReadyClaimer and Counter — 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 DIFFERENT QUESTION FROM BOTH OF ITS NEIGHBORS, which is why it is
|
|
// neither a Reader method nor a Counter one.
|
|
//
|
|
// - Reader.Ready answers with a PAGE, and the verdict it carries is
|
|
// HasMore: "did the limit hide anything". This role answers "how many",
|
|
// which is strictly larger — no page can be truncated into it — and it is
|
|
// the number one surface has published for years, so collapsing the two
|
|
// would change shipped output rather than tidy a duplicate.
|
|
// - Counter answers a predicate over one table. The ready predicate is
|
|
// BLOCKER-AWARE: it reads the dependency graph and the wisp tier, and no
|
|
// CountRequest can describe it. Counter's own doc says so in as many words
|
|
// ("The count of READY work is likewise a different question ... and is
|
|
// its own role for the same reason").
|
|
//
|
|
// IT TAKES ReadyRequest VERBATIM — the same type Reader.Ready takes and the
|
|
// same type ClaimNextRequest.Filter carries, not a parallel one shaped like
|
|
// it. A listing, a claim and a count then ask ONE question of ONE set, and the
|
|
// three cannot drift apart at the predicate: every implementation builds the
|
|
// filter through internal/workapi.BuildReadyCountFilter, which is
|
|
// BuildReadyFilter with the page removed.
|
|
//
|
|
// Implementations never mutate caller-owned request values, snapshot the
|
|
// request at method entry, and apply normalization only to attempt-local
|
|
// clones. That promise is load-bearing rather than conventional here:
|
|
// ReadyRequest carries four label slices and a metadata map, and normalization
|
|
// is the step that would otherwise write through them.
|
|
//
|
|
// COUNTING IS A READ. Nothing here records a history entry, fires a completion
|
|
// hook or changes a row, and a refusal changes nothing either. Deterministic
|
|
// request-validation failures match ErrValidation; result values are
|
|
// unspecified when error is non-nil.
|
|
//
|
|
// WHAT COST THIS HAS IS NOT PROMISED, only what it answers. The store-backed
|
|
// implementation sizes the set with indexed COUNT(*)s over the ready
|
|
// predicate; the unit-of-work implementation has no such seam and materializes
|
|
// the unbounded ready page to count it. Both answer the same number for the
|
|
// same request — that IS promised, by CountReady — and a caller that must
|
|
// bound the work asks a narrower question rather than a bounded one, because
|
|
// there is no bounded count to ask for (see CountReady's refusals).
|
|
type ReadyCounter interface {
|
|
// CountReady returns how many issues the request's ready predicate admits.
|
|
//
|
|
// THE ANSWER IS AN IDENTITY, not a similar number:
|
|
//
|
|
// CountReady(r).Total == len(Reader.Ready(r with Limit=0).Items)
|
|
//
|
|
// for every request r this method accepts, at every implementation. That
|
|
// is the whole contract of this role — a total the page it sizes does not
|
|
// agree with is worse than no total at all, because it is read as "how
|
|
// much work is left" — and it is why the two surfaces share a request type
|
|
// rather than merely similar filters. It holds for the wisp tier too: a
|
|
// request that admits ephemeral rows counts them exactly as the listing
|
|
// lists them.
|
|
//
|
|
// LIMIT AND OFFSET MUST BE UNSET (ErrValidation), mirroring
|
|
// ClaimNextRequest for a reason of the same shape. A cardinality has no
|
|
// page: a Limit would answer "how many of the first N", which no caller
|
|
// wants and which the identity above would stop being true of; an Offset
|
|
// would silently subtract the rows it skipped from the size of a set that
|
|
// still contains them. Rejecting both says that out loud rather than
|
|
// accepting two knobs and dropping them. An explicit zero Limit is refused
|
|
// with the rest: Limit is a pointer so "unset" and "explicitly unlimited"
|
|
// stay distinguishable (see ReadyRequest.Limit), and only the first is
|
|
// what this request permits — an unlimited count is the only kind there
|
|
// is, so asking for one is asking for the default.
|
|
//
|
|
// A PREDICATE THAT MATCHES NOTHING IS 0 AND A NIL ERROR. That is the whole
|
|
// of the "not found" story here, as it is for Counter: an empty ready
|
|
// front is the steady state of a drained queue, and a poller that had to
|
|
// classify an error to read a zero would be pattern-matching prose.
|
|
//
|
|
// IT IS NOT ONE SNAPSHOT WITH A PAGE. A caller that lists a page and then
|
|
// counts has issued two queries, and a write between them can leave the
|
|
// total disagreeing with the page by that write. Nothing here is
|
|
// transactional across the two calls, and no front door reconciles them:
|
|
// `bd ready --json` publishes both and says only what each is.
|
|
CountReady(ctx context.Context, req ReadyRequest) (ReadyCountResult, error)
|
|
}
|