beads/issueops/reader_ready_scope.go
CI Bot aa10a725e5 feat(list): put bd list's row cap and counts hydration on ListRequest (bd-b34o7)
STAGE ONE OF TWO. Fields, not methods, and no route flips — those are stage 2
(bd-5k21g). `issueops.ListRequest` gains MaxRows, MaxRowsSource and SkipCounts,
each with a conformance contract running at all three backends and zero parks.

MAXROWS IS THE EXACT INVERSE OF OFFSET, which is why it needed no new shape.
Offset is honored by the unit-of-work body — it renders OFFSET — and refused by
the store-backed one with a typed *ErrUnsupported. The cap points the other way:
the store search path enforces it after the scan (EnforceMaxRowsCap), and the
unit-of-work query path (internal/storage/domain/db) reads no cap at all, so a
request carrying one would come back as the FULL uncapped answer with nothing on
it to say so — a caller that set a circuit breaker handed exactly the runaway
query it was guarding against. It refuses instead, naming the operation and the
backend. `bd list --max-rows --proxied-server` has always refused one layer up
in the CLI for that reason; this is the same refusal for the callers that are
not the CLI. RunReaderListMaxRowsIsHonoredOrRefused mirrors
RunReaderOffsetIsHonoredOrRefused, including the never-silently-ignored clause,
and asserts the complement too: a cap the result set FITS inside must still come
back as an ordinary page, or a body that refused every cap out of hand would
pass.

MAXROWSSOURCE is the third field and the bead named two. It is attribution
only — it decides no answer — but `handleMaxRowsError` falls back to
"BEADS_MAX_ROWS" when it is empty, so a request that carried the number without
the source would make stage 2's route flip start telling operators to raise the
wrong knob. The contract asserts it comes back on the cap error.

SKIPCOUNTS is the SkipLabels precedent one column over: the three cardinality
joins are dropped and DependencyCount/DependentCount/CommentCount come back
zero, to be read as unknown rather than as none. It has to land WITH MaxRows —
stage 2 moves `bd list`'s TEXT path onto the role, and that path calls
SearchIssues today and projects no counts at all, so arriving on a counted page
without a way to opt out is a straight perf regression. The expensive member is
the reverse-blocker aggregate, which joins on a COALESCE key the pure-Go
analyzer cannot auto-index — the known embedded sore point, and the reason the
knob is worth having at all.

The contract's second half is the load-bearing one: NOTHING ELSE MOVES. Same
rows, same order, same has-more, same Parent — asserted by running the identical
request both ways rather than against a written-out expectation. Parent is the
tripwire: it rides the same mega-query and is not a cardinality, so an
implementation that made an aggregate join inner, or suppressed the parent join
too, would answer a strict subset and still look like it had "skipped the
counts".

WHAT THE SQL DOES. sqlbuild.SearchCountsSQL's two trailing hydration bools
become one CountsHydration value, so a path cannot pick up one opt-out and drop
the other, and both stores plus the unit-of-work repository read the pair
through one helper. A suppressed aggregate is projected as a constant IN PLACE
rather than removed: the scan reads the six extra columns positionally, so the
shape is invariant. Ready work passes the zero value at every call site —
types.WorkFilter carries neither knob, which is what "SkipLabels and SkipCounts
are not carried onto the ReadyFlag arm" means, now stated where a caller reads
it. MaxRows IS carried there; reader_ready_scope.go already claimed so, and this
is the commit that makes the claim true, since until now the field existed only
on the filter.

ONE HAND-ROLL DELETED. `bd list` built the filter through the shared builder and
then reached in and stamped filter.MaxRows/MaxRowsSource onto it — the
"build it, then change it" half-step this programme exists to make unreachable,
and the reason the cap was invisible to every implementation of Reader.List. The
cap is resolved in gatherListInput onto the request, BuildListFilter is now the
only writer of those two filter fields, and the proxied refusal reads the
already-resolved value (rejectResolvedMaxRowsUnderProxiedServer) so a malformed
BEADS_MAX_ROWS still warns exactly once.

PROVABLY INERT AT THE CLI, measured rather than argued: 22 `bd list` / `bd
children` invocations — every output mode, both max-rows knobs, the malformed
and negative cases — run against a binary built from integration/facade-wave-2
and one built from this commit, over ONE shared workspace so both read identical
data, differ on exactly one line of 617. `bd list --max-rows -1 --status bogus`
now reports the malformed flag instead of the invalid status; both exit 1, it
needs two bad arguments to reach, and it is recorded as A-lst1-3.

NO OPENAPI OPERATION AND NO NEW QUERY PARAMETER, deliberately, recorded as
A-lst1-1. `bd list`'s operation (GET /v0/beads/issues) already exists and is
already on the role, and neither field can be published on it yet: `bd serve`
always builds a provider-backed server, which REFUSES max_rows, so the parameter
would be one the reference server can never honor; and skip_counts would set
three unconditional integers on a PINNED response component to zero, leaving a
client unable to tell "no dependencies" from "not computed" — the failure
comments_omitted exists to prevent on the detail view. `make api-check`
regenerates nothing.

Verified: build, vet, gofmt clean; golangci-lint 0 issues; the two new cases at
dolt, embeddeddolt (BEADS_TEST_EMBEDDED_DOLT=1) and uow, plus the whole Reader
contract at all three; the builder golden (35 recorded cases plus two new ones
for the new fields) and the counts-SQL shape test; internal/httpapi and
make api-check; internal/storage/{issueops,domain/...}, internal/workapi,
internal/types, internal/telemetry, the root package; the embedded
`bd list`/`bd children`/max-rows CLI suites, TestProxiedServerList under
BEADS_TEST_PROXIED_SERVER=1 (including reject_max_rows_flag,
reject_max_rows_env and allow_max_rows_zero), TestProxiedLookup*, and the
protocol corpus package.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 16:36:31 +00:00

126 lines
6.8 KiB
Go

package issueops
import (
"fmt"
"strings"
)
// readyScopeField is one ListRequest field the ReadyFlag arm cannot carry,
// paired with the `bd list` flag that sets it. Naming both is the point of the
// refusal: a library caller looks for the struct field and a CLI caller for
// the flag, and neither should have to map one onto the other to learn which
// part of their request could not be honored.
type readyScopeField struct {
name string
flag string
set func(ListRequest) bool
}
// readyScopeFields is the drop set: every field a list request can set that
// does not survive the trip to the blocker-aware ready query.
//
// It was read off the two functions between this request and that query —
// internal/workapi.BuildListFilter, which turns the request into a storage
// filter, and internal/workapi.ReadyFilterFromIssueFilter, which projects that
// filter onto the narrower ready-work filter — and it is exactly the
// intersection: fields the builder copies onto the filter and the projection
// then discards.
//
// Four groups are deliberately ABSENT, because listing them here would refuse
// requests that are answered correctly today:
//
// - What the projection carries: IssueType, all five label forms, Assignee,
// NoAssignee, the exact Priority, ParentID, MolType, WispType,
// MetadataFields, HasMetadataKey, ExcludeTypes (and with it IncludeGates
// and IncludeInfra's type suppression), Limit, Offset, and the MaxRows cap
// with its attribution.
//
// - THE HYDRATION KNOBS, SkipLabels and SkipCounts. They are the one group
// the "exactly the intersection" rule above would otherwise sweep in: the
// builder does copy them onto the filter and the projection does discard
// them. They stay out because they select what is HYDRATED rather than
// which rows match, so a ReadyFlag request that sets one is answered with
// the rows it asked for and merely pays for a column it did not want.
// Refusing that would be refusing a correct answer over its cost, and the
// promise is already stated where a caller reads it (ListRequest.ReadyFlag).
//
// - Status and AllFlag. The builder resolves both to "open" under ReadyFlag
// before the projection ever runs, so IssueFilter.Statuses is never
// populated on this path and there is nothing for the projection to drop.
// Ready work is open work; that override is pinned by the builder's golden
// file (internal/workapi/testdata/list_filter_golden.json,
// ready_flag_overrides_status).
//
// - NoPinnedFlag. Pinned is dropped by the projection, but the ready-work
// WHERE clause excludes pinned rows unconditionally
// (internal/storage/sqlbuild/ready.go), so a caller who asks for the
// pinned rows to be left out gets exactly that. The opposite request,
// PinnedFlag, asks for pinned rows only and would be answered with a set
// that can never contain one — it is in the list below.
var readyScopeFields = []readyScopeField{
{"IDFilter", "--id", func(r ListRequest) bool { return r.IDFilter != "" }},
{"TitleSearch", "--title", func(r ListRequest) bool { return r.TitleSearch != "" }},
{"SpecPrefix", "--spec", func(r ListRequest) bool { return r.SpecPrefix != "" }},
{"TitleContains", "--title-contains", func(r ListRequest) bool { return r.TitleContains != "" }},
{"DescContains", "--desc-contains", func(r ListRequest) bool { return r.DescContains != "" }},
{"NotesContains", "--notes-contains", func(r ListRequest) bool { return r.NotesContains != "" }},
{"ExternalContains", "--external-contains", func(r ListRequest) bool { return r.ExternalContains != "" }},
{"ExternalRef", "--external-ref", func(r ListRequest) bool { return r.ExternalRef != "" }},
{"CreatedAfter", "--created-after", func(r ListRequest) bool { return r.CreatedAfter != nil }},
{"CreatedBefore", "--created-before", func(r ListRequest) bool { return r.CreatedBefore != nil }},
{"UpdatedAfter", "--updated-after", func(r ListRequest) bool { return r.UpdatedAfter != nil }},
{"UpdatedBefore", "--updated-before", func(r ListRequest) bool { return r.UpdatedBefore != nil }},
{"ClosedAfter", "--closed-after", func(r ListRequest) bool { return r.ClosedAfter != nil }},
{"ClosedBefore", "--closed-before", func(r ListRequest) bool { return r.ClosedBefore != nil }},
{"DeferAfter", "--defer-after", func(r ListRequest) bool { return r.DeferAfter != nil }},
{"DeferBefore", "--defer-before", func(r ListRequest) bool { return r.DeferBefore != nil }},
{"DueAfter", "--due-after", func(r ListRequest) bool { return r.DueAfter != nil }},
{"DueBefore", "--due-before", func(r ListRequest) bool { return r.DueBefore != nil }},
{"DeferredFlag", "--deferred", func(r ListRequest) bool { return r.DeferredFlag }},
{"OverdueFlag", "--overdue", func(r ListRequest) bool { return r.OverdueFlag }},
{"EmptyDesc", "--empty-description", func(r ListRequest) bool { return r.EmptyDesc }},
{"NoLabels", "--no-labels", func(r ListRequest) bool { return r.NoLabels }},
{"NoParent", "--no-parent", func(r ListRequest) bool { return r.NoParent }},
{"PinnedFlag", "--pinned", func(r ListRequest) bool { return r.PinnedFlag }},
{"PriorityMin", "--priority-min", func(r ListRequest) bool { return r.PriorityMin != nil }},
{"PriorityMax", "--priority-max", func(r ListRequest) bool { return r.PriorityMax != nil }},
// The keyset position is a pair and only the timestamp half decides
// whether one was supplied; AfterID alone is not a position.
{"AfterCreatedAt/AfterID", "cursor", func(r ListRequest) bool { return r.AfterCreatedAt != nil }},
}
// ValidateReadyFlagScope refuses a list request that combines ReadyFlag with a
// filter the blocker-aware ready query cannot carry, naming every field it
// could not honor. A generic refusal would leave the caller to bisect their
// own request.
//
// This is the enforcement half of ListRequest.ReadyFlag's promise; the other
// half is the doc comment there. It lives beside that promise rather than in
// any implementation, and it is called from the single builder every
// implementation of Reader runs (internal/workapi.BuildListFilter), so no
// backend can be missing it — a per-backend copy is the drift this role exists
// to remove.
//
// A request without ReadyFlag is never refused here: every field below is
// honored by the ordinary listing.
func ValidateReadyFlagScope(req ListRequest) error {
if !req.ReadyFlag {
return nil
}
var named []string
for _, f := range readyScopeFields {
if f.set(req) {
named = append(named, f.name+" ("+f.flag+")")
}
}
if len(named) == 0 {
return nil
}
return fmt.Errorf("%w: --ready cannot filter on %s; the blocker-aware ready query carries only part of the list vocabulary, so answering would return every ready issue rather than the ones asked for — drop --ready, or drop what it cannot carry",
ErrValidation, strings.Join(named, ", "))
}