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>
This commit is contained in:
CI Bot 2026-08-05 16:12:21 +00:00
commit aa10a725e5
21 changed files with 778 additions and 80 deletions

View file

@ -9,6 +9,7 @@ import (
"testing"
"time"
storageops "github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
publicops "github.com/steveyegge/beads/issueops"
)
@ -758,6 +759,194 @@ func RunReaderListEmptyPageIsWellFormed(t *testing.T, ctx context.Context, fixtu
}
}
// RunReaderListMaxRowsIsHonoredOrRefused pins what every implementation owes on
// ListRequest.MaxRows (reader.go:288-308): a non-zero cap over a result set
// that exceeds it is either HONORED — no page, an error — or REFUSED with a
// typed *ErrUnsupported, and never SILENTLY IGNORED.
//
// It is the MIRROR of RunReaderOffsetIsHonoredOrRefused above, one field over
// and pointing the other way: there the unit-of-work body honors and the
// store-backed one refuses, here the store-backed one honors and the
// unit-of-work one refuses. Which does which is a per-backend fact asserted at
// the wirings, not here, and the shared assertion is deliberately the weaker
// one — the two bodies disagree by design, so a case written to either
// behavior would fail the other.
//
// The never-silently clause is the whole value, exactly as it is for Offset. A
// cap is a CIRCUIT BREAKER: a caller sets it because it would rather fail than
// wait, so a body that accepts the field and answers the unbounded query hands
// that caller the runaway result it was guarding against, with nothing on the
// answer to say so. That is the failure this pins, and it is the one the
// unit-of-work query path would have had — it reads no MaxRows at all — if the
// field had been added without a refusal beside it.
//
// The complement is asserted too: the SAME request under a cap the result set
// fits inside must come back as an ordinary page everywhere. Without it a body
// that refused every non-zero MaxRows out of hand would pass.
func RunReaderListMaxRowsIsHonoredOrRefused(t *testing.T, ctx context.Context, fixture ReaderFixture) {
t.Helper()
var ids []string
for _, tag := range []string{"a", "b", "c"} {
id := readerID(fixture, "maxrows", tag)
ids = append(ids, id)
seedReaderIssue(t, ctx, fixture, readerIssue(id, types.TypeTask, ""))
}
idScope := readerIDFilter(ids...)
// A cap the three seeded rows fit inside. Answered as an ordinary page by
// the body that honors caps, and refused by the body that honors none —
// which is why the refusal branch is accepted here as well.
const roomyWhat = "List under a cap the result set fits inside"
roomy, err := fixture.Reader.List(ctx, publicops.ListRequest{
IDFilter: idScope, SortBy: "created", MaxRows: len(ids) + 1, MaxRowsSource: "--max-rows",
})
if err != nil {
assertReaderUnsupported(t, roomyWhat, err)
} else {
assertReaderPageIDSet(t, roomyWhat, roomy, ids)
}
// A cap the result set exceeds. Honored means an error carrying the cap;
// refused means *ErrUnsupported; a PAGE means the field was ignored.
tight, err := fixture.Reader.List(ctx, publicops.ListRequest{
IDFilter: idScope, SortBy: "created", MaxRows: len(ids) - 1, MaxRowsSource: "--max-rows",
})
if err == nil {
t.Fatalf("List under MaxRows=%d over %d matching rows returned the page %v and no error: the cap was silently ignored",
len(ids)-1, len(ids), readerPageIDs(tight))
}
var unsupported *publicops.ErrUnsupported
if errors.As(err, &unsupported) {
assertReaderUnsupported(t, "List under a cap the result set exceeds", err)
return
}
// The honoring branch. The leaf names the answer — *ErrTooManyRows — so a
// caller can tell "the cap fired" from any other failure without reading
// error text, and that is what is asserted rather than a message.
var tooMany *storageops.ErrTooManyRows
if !errors.As(err, &tooMany) {
t.Fatalf("List honored MaxRows and failed with %v; an honored cap has to answer with *ErrTooManyRows a caller can classify", err)
}
if tooMany.Cap != len(ids)-1 {
t.Errorf("the cap error reports Cap = %d, want the %d the request asked for", tooMany.Cap, len(ids)-1)
}
if tooMany.Found <= tooMany.Cap {
t.Errorf("the cap error reports Found = %d against Cap = %d; a cap that fired saw more rows than it allows", tooMany.Found, tooMany.Cap)
}
// The whole job of MaxRowsSource (reader.go:309-313): the attribution the
// request supplied comes back on the refusal, so the caller that set the
// cap can say which of its own knobs did.
if tooMany.Source != "--max-rows" {
t.Errorf("the cap error reports Source = %q, want the %q the request supplied: MaxRowsSource decides nothing else",
tooMany.Source, "--max-rows")
}
}
// RunReaderListSkipCountsDropsTheCardinalitiesAndNothingElse pins
// ListRequest.SkipCounts (reader.go:160-175). Two halves, and the second is
// the load-bearing one:
//
// - the three cardinalities come back ZERO on a row that genuinely has each
// of them, so the knob demonstrably reached the query rather than being
// accepted and dropped; and
// - NOTHING ELSE MOVES. Same rows, same order, same Parent, same has-more
// verdict as the identical request without the knob. This is a HYDRATION
// opt-out, and the way it could go wrong is by changing which rows match —
// the aggregates hang off outer joins, so an implementation that made one
// of them inner would answer with a strict subset and still look like it
// had "skipped the counts".
//
// The comparison is against the SAME request run both ways rather than against
// a written-out expectation, so the case says exactly what the doc says: this
// field changes what is hydrated and not what is returned.
//
// Zero is asserted rather than "unknown" because zero is what the wire and the
// struct can carry; the doc's instruction to READ it as unknown is a promise to
// the caller, not something an implementation can express differently.
func RunReaderListSkipCountsDropsTheCardinalitiesAndNothingElse(t *testing.T, ctx context.Context, fixture ReaderFixture) {
t.Helper()
subject := readerID(fixture, "skipcounts", "subject")
blocker := readerID(fixture, "skipcounts", "blocker")
dependent := readerID(fixture, "skipcounts", "dependent")
parent := readerID(fixture, "skipcounts", "parent")
for _, id := range []string{subject, blocker, dependent, parent} {
seedReaderIssue(t, ctx, fixture, readerIssue(id, types.TypeTask, ""))
}
// One outgoing blocks edge, one incoming one, and a parent-child edge, so
// the subject row carries a nonzero DependencyCount, DependentCount and
// Parent at once. Parent rides the same mega-query as the counts and is
// NOT a count, which is what makes it the tripwire for a knob that
// suppressed too much.
for _, edge := range []*types.Dependency{
{IssueID: subject, DependsOnID: blocker, Type: types.DepBlocks},
{IssueID: dependent, DependsOnID: subject, Type: types.DepBlocks},
{IssueID: subject, DependsOnID: parent, Type: types.DepParentChild},
} {
if err := fixture.AddDependency(ctx, edge, "seed"); err != nil {
t.Fatalf("seed edge %s -> %s: %v", edge.IssueID, edge.DependsOnID, err)
}
}
if err := fixture.AddComment(ctx, subject, "seed", "so the comment count is nonzero"); err != nil {
t.Fatalf("seed the comment: %v", err)
}
idScope := readerIDFilter(subject, blocker, dependent, parent)
req := publicops.ListRequest{IDFilter: idScope, SortBy: "created"}
hydrated, err := fixture.Reader.List(ctx, req)
if err != nil {
t.Fatalf("List with the counts hydrated: %v", err)
}
hydratedRow := readerRowByID(t, "List with the counts hydrated", hydrated, subject)
if hydratedRow == nil {
return
}
// The premise. If the seeded row has no counts to suppress and no parent to
// keep, the second half of this case proves nothing either way.
if hydratedRow.DependencyCount == 0 || hydratedRow.DependentCount == 0 || hydratedRow.CommentCount == 0 {
t.Fatalf("the seeded subject came back with counts (%d, %d, %d); this case needs all three nonzero before it can assert they are suppressed",
hydratedRow.DependencyCount, hydratedRow.DependentCount, hydratedRow.CommentCount)
}
if hydratedRow.Parent == nil {
t.Fatalf("the seeded subject came back with no Parent; this case needs one before Parent can be the tripwire for a knob that suppressed too much")
}
req.SkipCounts = true
skipped, err := fixture.Reader.List(ctx, req)
if err != nil {
t.Fatalf("List with SkipCounts: %v", err)
}
skippedRow := readerRowByID(t, "List with SkipCounts", skipped, subject)
if skippedRow == nil {
return
}
for _, got := range []struct {
what string
count int
}{
{"DependencyCount", skippedRow.DependencyCount},
{"DependentCount", skippedRow.DependentCount},
{"CommentCount", skippedRow.CommentCount},
} {
if got.count != 0 {
t.Errorf("List with SkipCounts returned %s = %d, want 0: the knob was accepted and the aggregate computed anyway", got.what, got.count)
}
}
// Nothing else moves.
if !slices.Equal(readerPageIDs(skipped), readerPageIDs(hydrated)) {
t.Errorf("List with SkipCounts returned %v, want the same page as without it, %v: this knob chooses what is hydrated, never which rows match",
readerPageIDs(skipped), readerPageIDs(hydrated))
}
if skipped.HasMore != hydrated.HasMore {
t.Errorf("List with SkipCounts reported HasMore = %v, want %v", skipped.HasMore, hydrated.HasMore)
}
if !readerSameParent(skippedRow.Parent, hydratedRow.Parent) {
t.Errorf("List with SkipCounts returned Parent = %v, want %v: Parent is not a cardinality and rides the same query",
readerParentText(skippedRow.Parent), readerParentText(hydratedRow.Parent))
}
}
// RunReaderGetResolvesTheExactIDAcrossBothPlanes pins GetRequest.ID
// (reader.go:273-276): the id is exact and canonical, the issue-to-wisp fallback
// happens inside, and there is no fuzzy, prefix or substring resolution. The
@ -1322,6 +1511,50 @@ func readerIDFilter(ids ...string) string {
func readerLimit(n int) *int { return &n }
// readerRowByID picks one row out of a page by id, failing the case rather than
// returning a zero row: an assertion about a row that is not there would
// otherwise read as an assertion that passed.
func readerRowByID(t *testing.T, what string, page publicops.IssuePage, id string) *types.IssueWithCounts {
t.Helper()
for _, item := range page.Items {
if item != nil && item.Issue != nil && item.ID == id {
return item
}
}
t.Errorf("%s returned %v, which does not contain %s", what, readerPageIDs(page), id)
return nil
}
// assertReaderUnsupported is the refusal shape every "honored or refused" case
// accepts: a typed *ErrUnsupported naming both the operation and the backend,
// so a caller can classify it with errors.As and knows where to go next.
func assertReaderUnsupported(t *testing.T, what string, err error) {
t.Helper()
var unsupported *publicops.ErrUnsupported
if !errors.As(err, &unsupported) {
t.Errorf("%s failed with %v; a refusal has to be a typed *ErrUnsupported a caller can classify", what, err)
return
}
if unsupported.Op == "" || unsupported.Backend == "" {
t.Errorf("%s refused with Op=%q Backend=%q; a refusal naming neither the operation nor the backend leaves the caller nowhere to go",
what, unsupported.Op, unsupported.Backend)
}
}
func readerSameParent(a, b *string) bool {
if a == nil || b == nil {
return a == nil && b == nil
}
return *a == *b
}
func readerParentText(p *string) string {
if p == nil {
return "<nil>"
}
return *p
}
func readerPageIDs(page publicops.IssuePage) []string {
out := make([]string, 0, len(page.Items))
for _, item := range page.Items {

View file

@ -191,7 +191,7 @@ func runListCore(cmd *cobra.Command, _ []string) error {
}
if usesProxiedServer() {
if err := rejectMaxRowsUnderProxiedServer(cmd); err != nil {
if err := rejectResolvedMaxRowsUnderProxiedServer(in.MaxRows); err != nil {
return err
}
if err := runListProxiedServer(cmd, rootCtx, in); err != nil {
@ -205,11 +205,15 @@ func runListCore(cmd *cobra.Command, _ []string) error {
}
// `bd list` builds the filter rather than calling IssueReader(), because
// this filter feeds --watch, the hierarchical --parent tree, the text
// renderings that want []*types.Issue rather than a counted page, and the
// --max-rows cap stamped on below — none of which the Reader role
// expresses, and routing only the JSON path through it would fork the
// command in two.
// this filter feeds --watch, the hierarchical --parent tree and the text
// renderings that want []*types.Issue rather than a counted page — none of
// which the Reader role expresses, and routing only the JSON path through
// it would fork the command in two.
//
// The --max-rows cap is no longer on that list. It used to be stamped onto
// the filter after this builder returned; it now rides on the request, so
// the builder is the only writer of the filter's two cap fields and the
// role expresses the cap too (issueops.ListRequest.MaxRows).
//
// It shares CONSTRUCTION with the role unconditionally: the same
// issueops.ListRequest through the same builder, pinned by the builder's
@ -230,12 +234,6 @@ func runListCore(cmd *cobra.Command, _ []string) error {
if err != nil {
return HandleError("%v", err)
}
maxRows, maxRowsSource, err := resolveMaxRows(cmd)
if err != nil {
return err
}
filter.MaxRows = maxRows
filter.MaxRowsSource = maxRowsSource
ctx := rootCtx

View file

@ -307,6 +307,21 @@ func gatherListInput(cmd *cobra.Command) (listInput, error) {
in.Offset = offset
}
// The defensive cap is part of the REQUEST, not something stamped onto the
// filter after the builder has produced it (issueops.ListRequest.MaxRows).
//
// Resolving it HERE also means it is resolved exactly once per invocation.
// resolveMaxRowsEnvOnly warns on a malformed BEADS_MAX_ROWS every time it
// runs, so runListCore's proxied-server refusal reads the value this
// resolved (rejectResolvedMaxRowsUnderProxiedServer) rather than resolving
// a second time and warning twice.
maxRows, maxRowsSource, err := resolveMaxRows(cmd)
if err != nil {
return in, err
}
in.MaxRows = maxRows
in.MaxRowsSource = maxRowsSource
in.repoOverride, _ = cmd.Flags().GetString("repo")
in.repoOverrideSet = cmd.Flags().Changed("repo")

View file

@ -38,6 +38,21 @@ func TestReaderOffsetIsHonoredOrRefused(t *testing.T) {
conformance.RunReaderOffsetIsHonoredOrRefused(t, ctx, fixture)
}
// The store-backed body is the arm that HONORS MaxRows: the cap rides the
// filter the shared builder produces and the search path enforces it after the
// scan. The refusing arm is the unit-of-work wiring.
func TestReaderListMaxRowsIsHonoredOrRefused(t *testing.T) {
fixture, ctx, cleanup := newDoltReaderFixture(t, "rdr")
defer cleanup()
conformance.RunReaderListMaxRowsIsHonoredOrRefused(t, ctx, fixture)
}
func TestReaderListSkipCountsDropsTheCardinalitiesAndNothingElse(t *testing.T) {
fixture, ctx, cleanup := newDoltReaderFixture(t, "rdr")
defer cleanup()
conformance.RunReaderListSkipCountsDropsTheCardinalitiesAndNothingElse(t, ctx, fixture)
}
func TestReaderReadySortPoliciesOrderTheSameRows(t *testing.T) {
fixture, ctx, cleanup := newDoltReaderFixture(t, "rdr")
defer cleanup()

View file

@ -65,7 +65,7 @@ func TestSearchCountsFilterBeforeJoinParity(t *testing.T) {
// Predicate form (nil ids): the form this PR reshapes. The by-IDs
// form keeps the plain driver and is unaffected.
newSQL, genArgs := sqlbuild.SearchCountsSQL(sqlbuild.IssuesFilterTables, nil, whereSQL, orderBy, limitSQL, true, tc.filter.SkipLabels)
newSQL, genArgs := sqlbuild.SearchCountsSQL(sqlbuild.IssuesFilterTables, nil, whereSQL, orderBy, limitSQL, true, sqlbuild.CountsHydration{SkipLabels: tc.filter.SkipLabels})
if genArgs != nil {
t.Fatalf("predicate form must not generate args, got %d", len(genArgs))
}

View file

@ -89,11 +89,11 @@ func (r *issueSQLRepositoryImpl) searchUnionWithCounts(ctx context.Context, quer
}
hasMore := page.trimToLimit(filter.Limit)
issuesByID, err := r.fetchCountsByIDs(ctx, page.issueIDs, issuesFilterTables, wispDepsExist, filter.SkipLabels)
issuesByID, err := r.fetchCountsByIDs(ctx, page.issueIDs, issuesFilterTables, wispDepsExist, hydrationFor(filter))
if err != nil {
return domain.SearchCountsPage{}, fmt.Errorf("search union with counts (hydrate issues): %w", err)
}
wispsByID, err := r.fetchCountsByIDs(ctx, page.wispIDs, wispsFilterTables, true, filter.SkipLabels)
wispsByID, err := r.fetchCountsByIDs(ctx, page.wispIDs, wispsFilterTables, true, hydrationFor(filter))
if err != nil && !dberrors.IsTableNotExist(err) {
return domain.SearchCountsPage{}, fmt.Errorf("search union with counts (hydrate wisps): %w", err)
}
@ -102,6 +102,14 @@ func (r *issueSQLRepositoryImpl) searchUnionWithCounts(ctx context.Context, quer
return domain.SearchCountsPage{Items: out, HasMore: hasMore}, nil
}
// hydrationFor reads the two hydration opt-outs off a search filter, matching
// the store-backed path's helper of the same name (internal/storage/issueops).
// Both bodies must read the same pair off the same filter or a caller that set
// one would get different columns from the two backends.
func hydrationFor(filter types.IssueFilter) sqlbuild.CountsHydration {
return sqlbuild.CountsHydration{SkipLabels: filter.SkipLabels, SkipCounts: filter.SkipCounts}
}
// fetchCountsByIDs hydrates counts rows for explicit IDs via the by-IDs form
// of the counts mega-query, which also constrains every aggregate subquery to
// the page (row order is restored by the caller from the union page). It must
@ -110,14 +118,14 @@ func (r *issueSQLRepositoryImpl) searchUnionWithCounts(ctx context.Context, quer
// clause would silently couple to the subquery's internal alias. The IDs are
// chunked so the by-IDs form's up-to-eightfold placeholder binding stays
// within per-statement limits (mirrors issueops.runReadyCountsInTx).
func (r *issueSQLRepositoryImpl) fetchCountsByIDs(ctx context.Context, ids []string, tables filterTables, includeWispReverseDeps bool, skipLabels bool) (map[string]*types.IssueWithCounts, error) {
func (r *issueSQLRepositoryImpl) fetchCountsByIDs(ctx context.Context, ids []string, tables filterTables, includeWispReverseDeps bool, hyd sqlbuild.CountsHydration) (map[string]*types.IssueWithCounts, error) {
out := make(map[string]*types.IssueWithCounts, len(ids))
for start := 0; start < len(ids); start += queryBatchSize {
end := start + queryBatchSize
if end > len(ids) {
end = len(ids)
}
countsSQL, args := sqlbuild.SearchCountsSQL(tables, ids[start:end], "", "", "", includeWispReverseDeps, skipLabels)
countsSQL, args := sqlbuild.SearchCountsSQL(tables, ids[start:end], "", "", "", includeWispReverseDeps, hyd)
items, err := r.scanCountsQuery(ctx, tables, countsSQL, args)
if err != nil {
return nil, err
@ -143,12 +151,12 @@ func (r *issueSQLRepositoryImpl) runFilterSearchQuery(ctx context.Context, query
}
orderBy := orderBySQL(filter.SortBy, filter.SortDesc, "i")
limitSQL := limitOffsetSQL(filter.Limit, filter.Offset)
return r.runSearchQuery(ctx, tables, whereSQL, orderBy, limitSQL, args, includeWispReverseDeps, filter.SkipLabels)
return r.runSearchQuery(ctx, tables, whereSQL, orderBy, limitSQL, args, includeWispReverseDeps, hydrationFor(filter))
}
//nolint:gosec // G201: SQL fragments are built from hardcoded table names and parameterized filters.
func (r *issueSQLRepositoryImpl) runSearchQuery(ctx context.Context, tables filterTables, whereSQL, orderBySQL, limitSQL string, args []any, includeWispReverseDeps bool, skipLabels bool) ([]*types.IssueWithCounts, error) {
searchSQL, _ := sqlbuild.SearchCountsSQL(tables, nil, whereSQL, orderBySQL, limitSQL, includeWispReverseDeps, skipLabels)
func (r *issueSQLRepositoryImpl) runSearchQuery(ctx context.Context, tables filterTables, whereSQL, orderBySQL, limitSQL string, args []any, includeWispReverseDeps bool, hyd sqlbuild.CountsHydration) ([]*types.IssueWithCounts, error) {
searchSQL, _ := sqlbuild.SearchCountsSQL(tables, nil, whereSQL, orderBySQL, limitSQL, includeWispReverseDeps, hyd)
return r.scanCountsQuery(ctx, tables, searchSQL, args)
}

View file

@ -7,6 +7,7 @@ import (
"github.com/steveyegge/beads/internal/storage/dberrors"
"github.com/steveyegge/beads/internal/storage/domain"
"github.com/steveyegge/beads/internal/storage/sqlbuild"
"github.com/steveyegge/beads/internal/types"
)
@ -115,13 +116,13 @@ func (r *issueSQLRepositoryImpl) getReadyWorkWithCountsUnion(ctx context.Context
return domain.SearchCountsPage{Items: nil, HasMore: hasMore}, nil
}
issuesByID, err := r.fetchCountsByIDs(ctx, page.issueIDs, issuesFilterTables, wispDepsExist, false)
issuesByID, err := r.fetchCountsByIDs(ctx, page.issueIDs, issuesFilterTables, wispDepsExist, sqlbuild.CountsHydration{})
if err != nil {
return domain.SearchCountsPage{}, fmt.Errorf("ready work union with counts: hydrate issues: %w", err)
}
var wispsByID map[string]*types.IssueWithCounts
if len(page.wispIDs) > 0 {
wispsByID, err = r.fetchCountsByIDs(ctx, page.wispIDs, wispsFilterTables, true, false)
wispsByID, err = r.fetchCountsByIDs(ctx, page.wispIDs, wispsFilterTables, true, sqlbuild.CountsHydration{})
if err != nil && !dberrors.IsTableNotExist(err) {
return domain.SearchCountsPage{}, fmt.Errorf("ready work union with counts: hydrate wisps: %w", err)
}

View file

@ -39,6 +39,22 @@ func TestEmbeddedReaderOffsetIsHonoredOrRefused(t *testing.T) {
conformance.RunReaderOffsetIsHonoredOrRefused(t, ctx, newEmbeddedReaderFixture(t, "rdr"))
}
// SkipCounts matters most HERE. The aggregate it drops is the reverse-blocker
// join, whose COALESCE key the pure-Go analyzer cannot auto-index — so this is
// the engine where the knob is worth having, and the one where an
// implementation that quietly ignored it would be least visible.
func TestEmbeddedReaderListMaxRowsIsHonoredOrRefused(t *testing.T) {
skipUnlessEmbeddedDolt(t)
ctx := t.Context()
conformance.RunReaderListMaxRowsIsHonoredOrRefused(t, ctx, newEmbeddedReaderFixture(t, "rdr"))
}
func TestEmbeddedReaderListSkipCountsDropsTheCardinalitiesAndNothingElse(t *testing.T) {
skipUnlessEmbeddedDolt(t)
ctx := t.Context()
conformance.RunReaderListSkipCountsDropsTheCardinalitiesAndNothingElse(t, ctx, newEmbeddedReaderFixture(t, "rdr"))
}
func TestEmbeddedReaderReadySortPoliciesOrderTheSameRows(t *testing.T) {
skipUnlessEmbeddedDolt(t)
ctx := t.Context()

View file

@ -21,7 +21,7 @@ func GetReadyWorkWithCountsInTx(ctx context.Context, tx *sql.Tx, filter types.Wo
if err != nil {
return nil, err
}
out, err := runReadyCountsInTx(ctx, tx, IssuesFilterTables, filter.Limit, issuePreds, wispDepsExist, false)
out, err := runReadyCountsInTx(ctx, tx, IssuesFilterTables, filter.Limit, issuePreds, wispDepsExist, sqlbuild.CountsHydration{})
if err != nil {
return nil, err
}
@ -41,7 +41,7 @@ func GetReadyWorkWithCountsInTx(ctx context.Context, tx *sql.Tx, filter types.Wo
if err != nil {
return nil, err
}
wisps, err := runReadyCountsInTx(ctx, tx, WispsFilterTables, filter.Limit, wispPreds, true, false)
wisps, err := runReadyCountsInTx(ctx, tx, WispsFilterTables, filter.Limit, wispPreds, true, sqlbuild.CountsHydration{})
if err != nil {
if isTableNotExistError(err) {
return finishReadyWorkWithCounts(out, filter)
@ -128,10 +128,15 @@ func finishReadyWorkWithCounts(items []*types.IssueWithCounts, filter types.Work
// For limit <= 0 (unbounded) there is no page to push down, so it runs the
// predicate-form mega-query unchanged.
//
// Both callers pass the ZERO hydration, so ready work is always fully
// hydrated. types.WorkFilter carries neither opt-out — the projection that
// builds it drops both — and issueops.ListRequest says so where a caller reads
// it: SkipLabels and SkipCounts are not carried onto the ReadyFlag arm.
//
//nolint:gosec // G201: whereSQL/orderBySQL/limitSQL are hardcoded fragments; user input rides ? placeholders.
func runReadyCountsInTx(ctx context.Context, tx *sql.Tx, tables FilterTables, limit int, preds *readyWorkPredicates, includeWispReverseDeps, skipLabels bool) ([]*types.IssueWithCounts, error) {
func runReadyCountsInTx(ctx context.Context, tx *sql.Tx, tables FilterTables, limit int, preds *readyWorkPredicates, includeWispReverseDeps bool, hyd sqlbuild.CountsHydration) ([]*types.IssueWithCounts, error) {
if limit <= 0 {
return runSearchQueryInTx(ctx, tx, tables, preds.whereSQL, preds.orderBySQL, preds.limitSQL, preds.args, includeWispReverseDeps, skipLabels)
return runSearchQueryInTx(ctx, tx, tables, preds.whereSQL, preds.orderBySQL, preds.limitSQL, preds.args, includeWispReverseDeps, hyd)
}
idQuery := fmt.Sprintf("SELECT id FROM %s %s %s %s", tables.Main, preds.whereSQL, preds.orderBySQL, preds.limitSQL)
@ -151,7 +156,7 @@ func runReadyCountsInTx(ctx context.Context, tx *sql.Tx, tables FilterTables, li
if end > len(pageIDs) {
end = len(pageIDs)
}
countsSQL, idArgs := sqlbuild.SearchCountsSQL(tables, pageIDs[start:end], "", "", "", includeWispReverseDeps, skipLabels)
countsSQL, idArgs := sqlbuild.SearchCountsSQL(tables, pageIDs[start:end], "", "", "", includeWispReverseDeps, hyd)
rows, scanErr := scanCountsRowsInTx(ctx, tx, tables.Main, countsSQL, idArgs)
if scanErr != nil {
return nil, scanErr

View file

@ -96,6 +96,13 @@ func SearchIssuesWithCountsInTx(ctx context.Context, tx *sql.Tx, query string, f
return finishSearchIssuesWithCounts(kept, filter)
}
// hydrationFor reads the two hydration opt-outs off a search filter. It is one
// function rather than two field reads at each call site so a path cannot pick
// up one of the pair and quietly drop the other.
func hydrationFor(filter types.IssueFilter) sqlbuild.CountsHydration {
return sqlbuild.CountsHydration{SkipLabels: filter.SkipLabels, SkipCounts: filter.SkipCounts}
}
func runFilterSearchQueryInTx(ctx context.Context, tx *sql.Tx, query string, filter types.IssueFilter, tables FilterTables, includeWispReverseDeps bool) ([]*types.IssueWithCounts, error) {
whereClauses, args, err := BuildIssueFilterClauses(query, filter, tables)
if err != nil {
@ -110,12 +117,12 @@ func runFilterSearchQueryInTx(ctx context.Context, tx *sql.Tx, query string, fil
limitSQL = fmt.Sprintf("LIMIT %d", eff)
}
orderBy := sqlbuild.OrderBy(filter.SortBy, filter.SortDesc, "i")
return runSearchQueryInTx(ctx, tx, tables, whereSQL, orderBy, limitSQL, args, includeWispReverseDeps, filter.SkipLabels)
return runSearchQueryInTx(ctx, tx, tables, whereSQL, orderBy, limitSQL, args, includeWispReverseDeps, hydrationFor(filter))
}
//nolint:gosec // G201: SQL fragments are caller-built from hardcoded shapes
func runSearchQueryInTx(ctx context.Context, tx *sql.Tx, tables FilterTables, whereSQL, orderBySQL, limitSQL string, args []interface{}, includeWispReverseDeps bool, skipLabels bool) ([]*types.IssueWithCounts, error) {
searchSQL, _ := sqlbuild.SearchCountsSQL(tables, nil, whereSQL, orderBySQL, limitSQL, includeWispReverseDeps, skipLabels)
func runSearchQueryInTx(ctx context.Context, tx *sql.Tx, tables FilterTables, whereSQL, orderBySQL, limitSQL string, args []interface{}, includeWispReverseDeps bool, hyd sqlbuild.CountsHydration) ([]*types.IssueWithCounts, error) {
searchSQL, _ := sqlbuild.SearchCountsSQL(tables, nil, whereSQL, orderBySQL, limitSQL, includeWispReverseDeps, hyd)
return scanCountsRowsInTx(ctx, tx, tables.Main, searchSQL, args)
}

View file

@ -20,6 +20,26 @@ const DepJSONObject = `JSON_OBJECT(
'thread_id', thread_id
)`
// CountsHydration selects which per-row aggregates the counts mega-query
// computes. Both members are opt-OUTs: the zero value hydrates everything,
// which is what every caller that has not been told otherwise wants.
//
// Neither one changes WHICH ROWS come back or in what order — the aggregates
// hang off LEFT JOINs that preserve every driver row, so dropping one drops a
// column's value and nothing else. Each also keeps the projection's SHAPE:
// the scan side (issueops.ScanReadyWorkRowWithCounts) reads the six extra
// columns positionally, so a suppressed aggregate is projected as a constant
// in place rather than removed.
//
// SkipLabels leaves labels_json NULL, which the scan turns into no labels.
// SkipCounts leaves the three cardinalities 0, which a caller must read as
// unknown rather than as none — the promise issueops.ListRequest.SkipCounts
// states for the callers above storage.
type CountsHydration struct {
SkipLabels bool
SkipCounts bool
}
// SearchCountsSQL renders the counts mega-query: full issue rows aliased "i"
// plus labels JSON, dep/rdep/comment counts, parent ID, and dependency JSON,
// for one table family. The scan side is issueops.ScanReadyWorkRowWithCounts,
@ -82,7 +102,9 @@ const DepJSONObject = `JSON_OBJECT(
//
// The reverse-blocker rc subquery unions wisp_dependencies only when the caller
// has probed that the table exists (includeWispReverseDeps).
func SearchCountsSQL(tables FilterTables, ids []string, whereSQL, orderBySQL, limitSQL string, includeWispReverseDeps, skipLabels bool) (string, []any) {
//
// hyd selects which aggregates are computed at all; see CountsHydration.
func SearchCountsSQL(tables FilterTables, ids []string, whereSQL, orderBySQL, limitSQL string, includeWispReverseDeps bool, hyd CountsHydration) (string, []any) {
byIDs := len(ids) > 0
inSQL, idArgs := InPlaceholders(ids)
@ -120,11 +142,46 @@ func SearchCountsSQL(tables FilterTables, ids []string, whereSQL, orderBySQL, li
%s
GROUP BY issue_id
) l ON l.issue_id = i.id`, tables.Labels, labelWhere)
if skipLabels {
if hyd.SkipLabels {
labelsSelect = "NULL AS labels_json"
labelsJoin = ""
}
countsSelect := `COALESCE(dc.cnt, 0) AS dep_count,
COALESCE(rc.cnt, 0) AS rdep_count,
COALESCE(cc.cnt, 0) AS comment_count`
countsJoins := fmt.Sprintf(`
LEFT JOIN (
SELECT issue_id, COUNT(*) AS cnt
FROM %s
WHERE type = 'blocks'%s
GROUP BY issue_id
) dc ON dc.issue_id = i.id
LEFT JOIN (
SELECT dep_id, COUNT(*) AS cnt FROM (
%s
) all_blockers GROUP BY dep_id
) rc ON rc.dep_id = i.id
LEFT JOIN (
SELECT issue_id, COUNT(*) AS cnt
FROM %s
%s
GROUP BY issue_id
) cc ON cc.issue_id = i.id`,
tables.Dependencies, depBlocksExtra,
reverseBlockerSelect,
tables.Comments, ccWhere)
if hyd.SkipCounts {
// Constants in the same three positions: the scan reads these
// columns by index, and the rc join above is the one the embedded
// engine cannot index (see the by-IDs rationale above), so dropping
// it is the whole point of the knob.
countsSelect = `0 AS dep_count,
0 AS rdep_count,
0 AS comment_count`
countsJoins = ""
}
// Predicate form with a filter: whereSQL filters the main table inside a
// derived table so the aggregate joins drive off the already-narrowed set;
// ORDER BY and LIMIT stay outer, after the joins. Everything else — empty
@ -146,31 +203,13 @@ func SearchCountsSQL(tables FilterTables, ids []string, whereSQL, orderBySQL, li
sqlText := fmt.Sprintf(`
SELECT %s,
%s,
COALESCE(dc.cnt, 0) AS dep_count,
COALESCE(rc.cnt, 0) AS rdep_count,
COALESCE(cc.cnt, 0) AS comment_count,
%s,
pc.parent_id AS parent_id,
d.deps_json AS deps_json
FROM %s
%s
%s
LEFT JOIN (
SELECT issue_id, COUNT(*) AS cnt
FROM %s
WHERE type = 'blocks'%s
GROUP BY issue_id
) dc ON dc.issue_id = i.id
LEFT JOIN (
SELECT dep_id, COUNT(*) AS cnt FROM (
%s
) all_blockers GROUP BY dep_id
) rc ON rc.dep_id = i.id
LEFT JOIN (
SELECT issue_id, COUNT(*) AS cnt
FROM %s
%s
GROUP BY issue_id
) cc ON cc.issue_id = i.id
%s
LEFT JOIN (
SELECT issue_id,
MIN(%s) AS parent_id
@ -188,12 +227,11 @@ func SearchCountsSQL(tables FilterTables, ids []string, whereSQL, orderBySQL, li
`,
ReadyWorkIssueColumns,
labelsSelect,
countsSelect,
driverSQL,
LeaseJoin("i"),
labelsJoin,
tables.Dependencies, depBlocksExtra,
reverseBlockerSelect,
tables.Comments, ccWhere,
countsJoins,
DepTargetExpr, tables.Dependencies, pcExtra,
DepJSONObject, tables.Dependencies, depWhere,
outerClause,
@ -204,18 +242,20 @@ func SearchCountsSQL(tables FilterTables, ids []string, whereSQL, orderBySQL, li
}
// args follow the placeholder order in sqlText: labels join (unless
// skipped), dc, rc dependencies branch, rc wisp branch (if any), cc, pc, d,
// then the driver.
// skipped), dc, rc dependencies branch, rc wisp branch (if any), cc (all
// four unless the counts are skipped), pc, d, then the driver.
args := make([]any, 0, len(idArgs)*8)
if !skipLabels {
if !hyd.SkipLabels {
args = append(args, idArgs...)
}
args = append(args, idArgs...) // dc
args = append(args, idArgs...) // rc dependencies
if includeWispReverseDeps {
args = append(args, idArgs...) // rc wisp_dependencies
if !hyd.SkipCounts {
args = append(args, idArgs...) // dc
args = append(args, idArgs...) // rc dependencies
if includeWispReverseDeps {
args = append(args, idArgs...) // rc wisp_dependencies
}
args = append(args, idArgs...) // cc
}
args = append(args, idArgs...) // cc
args = append(args, idArgs...) // pc
args = append(args, idArgs...) // d
args = append(args, idArgs...) // driver

View file

@ -238,7 +238,7 @@ func TestBuildReadyWorkWhereLabelRegex(t *testing.T) {
func TestSearchCountsSQLShape(t *testing.T) {
t.Parallel()
sql, args := SearchCountsSQL(WispsFilterTables, nil, "WHERE x = ?", "ORDER BY y", "LIMIT 5", true, false)
sql, args := SearchCountsSQL(WispsFilterTables, nil, "WHERE x = ?", "ORDER BY y", "LIMIT 5", true, CountsHydration{})
if args != nil {
t.Errorf("predicate form must not return generated args, got %d", len(args))
}
@ -286,7 +286,7 @@ func TestSearchCountsSQLShape(t *testing.T) {
}
}
noWispDeps, _ := SearchCountsSQL(IssuesFilterTables, nil, "", "", "", false, true)
noWispDeps, _ := SearchCountsSQL(IssuesFilterTables, nil, "", "", "", false, CountsHydration{SkipLabels: true})
if strings.Contains(noWispDeps, "UNION ALL") {
t.Error("counts SQL must not union wisp reverse deps when probe says absent")
}
@ -306,7 +306,7 @@ func TestSearchCountsSQLShape(t *testing.T) {
// By-IDs form: driver and every subquery are constrained to the ids, and the
// arg count matches the placeholder injection points (labels, dc, rc-deps,
// rc-wisp, cc, pc, d, driver = 8 for the wisp family with labels).
byIDs, idArgs := SearchCountsSQL(WispsFilterTables, []string{"a", "b"}, "", "", "", true, false)
byIDs, idArgs := SearchCountsSQL(WispsFilterTables, []string{"a", "b"}, "", "", "", true, CountsHydration{})
if !strings.Contains(byIDs, "WHERE i.id IN (?,?)") {
t.Errorf("by-IDs counts SQL missing driver id filter:\n%s", byIDs)
}
@ -325,10 +325,41 @@ func TestSearchCountsSQLShape(t *testing.T) {
// skipLabels drops the labels point and !includeWispReverseDeps drops the
// rc-wisp point, leaving 6 injection points (dc, rc-deps, cc, pc, d, driver).
_, idArgsNoLabels := SearchCountsSQL(IssuesFilterTables, []string{"a", "b"}, "", "", "", false, true)
_, idArgsNoLabels := SearchCountsSQL(IssuesFilterTables, []string{"a", "b"}, "", "", "", false, CountsHydration{SkipLabels: true})
if len(idArgsNoLabels) != 6*2 {
t.Errorf("by-IDs args (skipLabels, no wisp deps) = %d, want %d", len(idArgsNoLabels), 6*2)
}
// SkipCounts drops the three cardinality joins and projects constants in
// their place, so the six extra columns the scan reads positionally stay
// six and in the same order.
skipCounts, _ := SearchCountsSQL(IssuesFilterTables, nil, "", "", "", true, CountsHydration{SkipCounts: true})
for _, gone := range []string{"dc ON dc.issue_id", "rc ON rc.dep_id", "cc ON cc.issue_id", "COALESCE(dc.cnt, 0)", "UNION ALL"} {
if strings.Contains(skipCounts, gone) {
t.Errorf("counts SQL must drop %q when SkipCounts is set:\n%s", gone, skipCounts)
}
}
for _, want := range []string{"0 AS dep_count", "0 AS rdep_count", "0 AS comment_count", "pc.parent_id AS parent_id", "d.deps_json AS deps_json"} {
if !strings.Contains(skipCounts, want) {
t.Errorf("counts SQL missing %q under SkipCounts:\n%s", want, skipCounts)
}
}
// Labels survive SkipCounts: the two opt-outs are independent.
if !strings.Contains(skipCounts, "JSON_ARRAYAGG(label)") {
t.Error("SkipCounts must not drop the labels join")
}
// By-IDs: SkipCounts removes the dc, rc-deps, rc-wisp and cc injection
// points, leaving labels, pc, d and the driver.
_, idArgsNoCounts := SearchCountsSQL(WispsFilterTables, []string{"a", "b"}, "", "", "", true, CountsHydration{SkipCounts: true})
if len(idArgsNoCounts) != 4*2 {
t.Errorf("by-IDs args (skipCounts) = %d, want %d", len(idArgsNoCounts), 4*2)
}
// Both opt-outs together leave pc, d and the driver.
_, idArgsNeither := SearchCountsSQL(WispsFilterTables, []string{"a", "b"}, "", "", "", true, CountsHydration{SkipLabels: true, SkipCounts: true})
if len(idArgsNeither) != 3*2 {
t.Errorf("by-IDs args (skipLabels+skipCounts) = %d, want %d", len(idArgsNeither), 3*2)
}
}
func TestBuildReadyWorkWhereStatusFilter(t *testing.T) {

View file

@ -70,7 +70,26 @@ func (r *issueReader) Ready(ctx context.Context, req publicops.ReadyRequest) (pu
})
}
// listBackend names the backend a List refusal comes from. It is the provider
// seam rather than the engine underneath it: what cannot honor MaxRows is this
// query path (internal/storage/domain/db), which threads no cap, and every
// provider reaches the queries through it.
const listBackend = "uow-provider"
func (r *issueReader) List(ctx context.Context, req publicops.ListRequest) (publicops.IssuePage, error) {
// The MIRROR IMAGE of the store body's Offset refusal, one field over. The
// domain/db query path reads no MaxRows, so a request carrying a cap would
// come back as the FULL uncapped answer with no error on it — a caller who
// asked for a circuit breaker getting exactly the runaway query it was
// guarding against. Refusing is checked before the unit of work opens: a
// request that cannot be answered should not cost a transaction.
//
// `bd list --max-rows --proxied-server` already refuses one layer up
// (cmd/bd/max_rows.go, rejectMaxRowsUnderProxiedServer) for exactly this
// reason. This is the same refusal for the callers that are not the CLI.
if req.MaxRows != 0 {
return publicops.IssuePage{}, &publicops.ErrUnsupported{Op: "Reader.List(MaxRows)", Backend: listBackend}
}
return RunTxRead(ctx, r.provider, func(ctx context.Context, uw UnitOfWork) (publicops.IssuePage, error) {
// The config source comes from the unit of work this call already
// holds, so a caller reaching this method through the role has nothing

View file

@ -38,6 +38,15 @@ func TestReaderContract(t *testing.T) {
t.Run("OffsetIsHonoredOrRefused", func(t *testing.T) {
conformance.RunReaderOffsetIsHonoredOrRefused(t, ctx, fixture)
})
// The REFUSING arm of MaxRows, and the mirror image of the wiring above:
// this body honors Offset and refuses the cap, the store-backed one honors
// the cap and refuses Offset. Neither answers a question it cannot answer.
t.Run("ListMaxRowsIsHonoredOrRefused", func(t *testing.T) {
conformance.RunReaderListMaxRowsIsHonoredOrRefused(t, ctx, fixture)
})
t.Run("ListSkipCountsDropsTheCardinalitiesAndNothingElse", func(t *testing.T) {
conformance.RunReaderListSkipCountsDropsTheCardinalitiesAndNothingElse(t, ctx, fixture)
})
t.Run("ReadySortPoliciesOrderTheSameRows", func(t *testing.T) {
conformance.RunReaderReadySortPoliciesOrderTheSameRows(t, ctx, fixture)
})

View file

@ -1817,6 +1817,15 @@ type IssueFilter struct {
// Opt-in performance flag for the bd list --skip-labels code path.
SkipLabels bool
// SkipCounts suppresses cardinality hydration on the counts mega-query.
// When true the three aggregate joins behind DependencyCount,
// DependentCount and CommentCount are dropped and all three come back 0,
// which callers MUST read as unknown rather than as none. The rows, their
// order, Parent and Dependencies are unaffected. It is the counts-side
// twin of SkipLabels and is ignored by the paths that project no counts
// (SearchIssues, GetReadyWork).
SkipCounts bool
// Performance escape hatches
SkipWisps bool // Q2: skip wisps table merge entirely (for callers that never return ephemeral results)
NoIDShrink bool // Q3: force Pattern A (full 47-col scan) even when Limit > 0

View file

@ -202,6 +202,14 @@ func BuildListFilter(in issueops.ListRequest, cfg ListConfig) (types.IssueFilter
SortDesc: in.Reverse,
AfterCreatedAt: in.AfterCreatedAt,
AfterID: in.AfterID,
// The defensive cap travels ON the request, so this builder is the
// only writer of the filter's two cap fields. `bd list` used to stamp
// them onto the filter after the builder returned, which is the
// "build it, then reach in and change it" half-step the role exists to
// make unreachable — and it left the cap invisible to every
// implementation of Reader.List.
MaxRows: in.MaxRows,
MaxRowsSource: in.MaxRowsSource,
}
if in.ReadyFlag {
@ -306,6 +314,9 @@ func BuildListFilter(in issueops.ListRequest, cfg ListConfig) (types.IssueFilter
if in.SkipLabels {
filter.SkipLabels = true
}
if in.SkipCounts {
filter.SkipCounts = true
}
if in.PriorityMin != nil {
p := *in.PriorityMin

View file

@ -23,6 +23,12 @@ type listFilterGoldenCase struct {
// builder before it was deleted, so a green run here is the proof that moving
// the logic into this package changed nothing — and it keeps pinning the
// filter shape for every later change to BuildListFilter.
//
// Two cases at the END of the file are NOT recorded: max_rows_cap and
// skip_counts pin fields that did not exist when the old builder did, so there
// was nothing to record them from. They pin what the leaf promises
// (issueops.ListRequest.MaxRows and .SkipCounts), which is the same standard
// the conformance contract holds the implementations to.
func TestBuildListFilterGolden(t *testing.T) {
blob, err := os.ReadFile(filepath.Join("testdata", "list_filter_golden.json"))
if err != nil {

View file

@ -35,8 +35,8 @@ import (
// today the store-backed role answers `bd show --json` on the direct route,
// and the HTTP surface and the proxied `bd show --json` reach the uow-backed
// one. `bd ready` and `bd list` still call the workapi builders directly —
// they consume the FILTER for the max-rows cap, --claim, --watch, the
// hierarchical --parent tree and the text renderings — so Ready and List below
// they consume the FILTER for --claim, --watch, the hierarchical --parent tree
// and the text renderings — so Ready and List below
// are reached only by tests until a front door moves. They are covered by
// reader_test.go for exactly that reason, and their page epilogue is
// workapi.FinishPage, which `bd list` DOES run in every mode but the
@ -98,6 +98,15 @@ func (r *storeReader) Ready(ctx context.Context, req issueops.ReadyRequest) (iss
return issueops.IssuePage{Items: items, HasMore: hasMore}, nil
}
// List answers one issue listing.
//
// The two knobs this body and its unit-of-work sibling answer differently sit
// side by side here and point opposite ways. Offset is refused below because
// this seam renders LIMIT without OFFSET. MaxRows is HONORED, and nothing
// below mentions it: the cap rides on the filter the shared builder produces,
// and the search path enforces it after the scan (internal/storage/issueops,
// EnforceMaxRowsCap), so the answer is *ErrTooManyRows instead of a page. The
// sibling refuses it, for the reason stated there.
func (r *storeReader) List(ctx context.Context, req issueops.ListRequest) (issueops.IssuePage, error) {
if req.Offset != 0 {
return issueops.IssuePage{}, refuseOffset("Reader.List(Offset)")

View file

@ -70,6 +70,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -149,6 +150,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -228,6 +230,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -307,6 +310,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -389,6 +393,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -468,6 +473,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -547,6 +553,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -626,6 +633,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -700,6 +708,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": false,
"NoIDShrink": false,
"Offset": 0,
@ -787,6 +796,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -885,6 +895,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -964,6 +975,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -1044,6 +1056,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -1126,6 +1139,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -1206,6 +1220,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -1286,6 +1301,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -1368,6 +1384,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -1449,6 +1466,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -1531,6 +1549,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": false,
"NoIDShrink": false,
"Offset": 0,
@ -1619,6 +1638,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -1698,6 +1718,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": false,
"NoIDShrink": false,
"Offset": 0,
@ -1778,6 +1799,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": false,
"NoIDShrink": false,
"Offset": 0,
@ -1857,6 +1879,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": false,
"NoIDShrink": false,
"Offset": 0,
@ -1934,6 +1957,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": false,
"NoIDShrink": false,
"Offset": 0,
@ -2018,6 +2042,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": false,
"NoIDShrink": false,
"Offset": 0,
@ -2104,6 +2129,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": false,
"NoIDShrink": false,
"Offset": 0,
@ -2188,6 +2214,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -2277,6 +2304,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -2389,6 +2417,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -2407,6 +2436,7 @@
"NoLabels": true,
"NoParent": true,
"SkipLabels": true,
"SkipCounts": false,
"Limit": 0
},
"config": {},
@ -2475,6 +2505,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": true,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -2559,6 +2590,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -2652,6 +2684,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -2735,6 +2768,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -2824,6 +2858,7 @@
"HasMetadataKey": "owner",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
@ -2908,6 +2943,7 @@
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 14,
@ -2917,5 +2953,172 @@
"MaxRowsSource": "",
"Lite": false
}
},
{
"name": "max_rows_cap",
"params": {
"Limit": 50,
"MaxRows": 25,
"MaxRowsSource": "--max-rows"
},
"config": {},
"filter": {
"Status": null,
"Statuses": null,
"Priority": null,
"IssueType": null,
"Assignee": null,
"Labels": null,
"LabelsAny": null,
"ExcludeLabels": null,
"LabelPattern": "",
"LabelRegex": "",
"TitleSearch": "",
"IDs": null,
"IDPrefix": "",
"SpecIDPrefix": "",
"Limit": 50,
"TitleContains": "",
"DescriptionContains": "",
"NotesContains": "",
"ExternalRefContains": "",
"ExternalRef": null,
"CreatedAfter": null,
"CreatedBefore": null,
"UpdatedAfter": null,
"UpdatedBefore": null,
"ClosedAfter": null,
"ClosedBefore": null,
"StartedAfter": null,
"StartedBefore": null,
"AfterCreatedAt": null,
"AfterID": "",
"EmptyDescription": false,
"NoAssignee": false,
"NoLabels": false,
"PriorityMin": null,
"PriorityMax": null,
"SourceRepo": null,
"Ephemeral": null,
"Pinned": false,
"IsBlocked": null,
"IsTemplate": false,
"ParentID": null,
"NoParent": false,
"MolType": null,
"WispType": null,
"ExcludeStatus": [
"closed",
"pinned"
],
"ExcludeTypes": [
"gate",
"agent",
"role",
"message"
],
"Deferred": false,
"DeferAfter": null,
"DeferBefore": null,
"DueAfter": null,
"DueBefore": null,
"Overdue": false,
"MetadataFields": null,
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": false,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
"SortBy": "",
"SortDesc": false,
"MaxRows": 25,
"MaxRowsSource": "--max-rows",
"Lite": false
}
},
{
"name": "skip_counts",
"params": {
"Limit": 50,
"SkipCounts": true
},
"config": {},
"filter": {
"Status": null,
"Statuses": null,
"Priority": null,
"IssueType": null,
"Assignee": null,
"Labels": null,
"LabelsAny": null,
"ExcludeLabels": null,
"LabelPattern": "",
"LabelRegex": "",
"TitleSearch": "",
"IDs": null,
"IDPrefix": "",
"SpecIDPrefix": "",
"Limit": 50,
"TitleContains": "",
"DescriptionContains": "",
"NotesContains": "",
"ExternalRefContains": "",
"ExternalRef": null,
"CreatedAfter": null,
"CreatedBefore": null,
"UpdatedAfter": null,
"UpdatedBefore": null,
"ClosedAfter": null,
"ClosedBefore": null,
"StartedAfter": null,
"StartedBefore": null,
"AfterCreatedAt": null,
"AfterID": "",
"EmptyDescription": false,
"NoAssignee": false,
"NoLabels": false,
"PriorityMin": null,
"PriorityMax": null,
"SourceRepo": null,
"Ephemeral": null,
"Pinned": false,
"IsBlocked": null,
"IsTemplate": false,
"ParentID": null,
"NoParent": false,
"MolType": null,
"WispType": null,
"ExcludeStatus": [
"closed",
"pinned"
],
"ExcludeTypes": [
"gate",
"agent",
"role",
"message"
],
"Deferred": false,
"DeferAfter": null,
"DeferBefore": null,
"DueAfter": null,
"DueBefore": null,
"Overdue": false,
"MetadataFields": null,
"HasMetadataKey": "",
"IncludeDependencies": false,
"SkipLabels": false,
"SkipCounts": true,
"SkipWisps": true,
"NoIDShrink": false,
"Offset": 0,
"SortBy": "",
"SortDesc": false,
"MaxRows": 0,
"MaxRowsSource": "",
"Lite": false
}
}
]

View file

@ -157,6 +157,22 @@ type ListRequest struct {
NoAssignee bool
NoLabels bool
SkipLabels bool
// SkipCounts suppresses the CARDINALITY hydration exactly as SkipLabels
// suppresses the label one: DependencyCount, DependentCount and
// CommentCount come back ZERO, and a caller must read a zero as UNKNOWN
// rather than as none. Nothing else about the page moves — the rows, their
// order, Parent and the has-more verdict are what they would have been —
// because this chooses what is HYDRATED, never which rows match.
//
// It is here for the renderings that print a page without those three
// numbers. Each is its own aggregate join, and the reverse-blocker one is
// the expensive member: it joins on an expression the embedded engine's
// planner cannot index, which is the per-call cost that makes a counted
// page the wrong shape for a listing that shows no counts.
//
// Like SkipLabels it is NOT carried onto the ReadyFlag arm; the counts are
// hydrated there either way, which costs time and not correctness.
SkipCounts bool
// Priority is exact; PriorityMin and PriorityMax bound a range. All three
// are pointers for the same reason ReadyRequest.Priority is.
@ -211,7 +227,8 @@ type ListRequest struct {
// WHAT IT CARRIES: IssueType, all five label forms, Assignee, NoAssignee,
// the exact Priority, ParentID, MolType, WispType, MetadataFields,
// HasMetadataKey, the type exclusions (ExcludeTypes, and with them
// IncludeGates and IncludeInfra), Limit and Offset. SortBy and Reverse
// IncludeGates and IncludeInfra), Limit, Offset and the MaxRows cap with
// its attribution. SortBy and Reverse
// still apply, because the display order is applied to the page after the
// query rather than inside it. Status and AllFlag are resolved to "open"
// and have no further effect: ready work is open work.
@ -231,8 +248,9 @@ type ListRequest struct {
// all, so this request's default template exclusion does not reach it and
// IncludeTemplates changes nothing here: a template is left out of a
// ReadyFlag listing only when its issue type is one the ready query
// already excludes. SkipLabels is likewise not carried — labels are
// hydrated either way, which costs time and not correctness.
// already excludes. SkipLabels and SkipCounts are likewise not carried —
// labels and cardinalities are hydrated either way, which costs time and
// not correctness.
AllFlag bool
ReadyFlag bool
@ -266,6 +284,36 @@ type ListRequest struct {
// transport concern and never reaches this contract.
AfterCreatedAt *time.Time
AfterID string
// MaxRows is a DEFENSIVE CAP rather than a page. It bounds how many rows
// the query may match before the whole answer is refused; 0 disables it.
// A request whose result set exceeds it comes back as
// *internal/storage/issueops.ErrTooManyRows — carrying the count observed,
// the cap, and MaxRowsSource's attribution — and NO PAGE. That is the
// difference from Limit, whose overflow is an ordinary truncated page with
// HasMore set. It is a circuit breaker for a caller that would rather fail
// than wait. The type is named here rather than left as "an error" so a
// caller can tell the cap firing from any other failure with errors.As;
// this leaf does not import it, and no answer depends on that.
//
// It is HONORED by the store-backed implementation and REFUSED by the
// unit-of-work one, with a typed *ErrUnsupported naming the operation and
// the backend. That is the exact INVERSE of Offset above, and for the same
// kind of reason: the unit-of-work query path threads no cap, so a body
// that accepted the field would answer an uncapped query to a caller who
// asked for a circuit breaker. What no implementation does is silently
// ignore it, so a caller either gets the cap it asked for or an error it
// can classify with errors.As. `bd list --max-rows --proxied-server`
// already refuses one layer up, in the CLI; this is the same refusal for
// the callers that are not the CLI.
//
// Unlike SkipCounts and SkipLabels it IS carried onto the ReadyFlag arm.
MaxRows int
// MaxRowsSource attributes the cap to whatever knob set it — "--max-rows",
// "BEADS_MAX_ROWS", or empty for a library caller — and that attribution is
// what the refusal text reads back. It decides no answer: a request is
// refused on MaxRows alone, and this only decides how the refusal reads.
MaxRowsSource string
}
// GetRequest describes one issue-detail lookup.
@ -370,11 +418,14 @@ type IssuePage struct {
//
// - `bd ready` and `bd list` are NOT, on either route, and they will not be
// until there are more roles to route them through. They consume the
// FILTER itself for things this role does not express — the --max-rows
// cap, --claim, --gated, --explain, --mol, --watch, the hierarchical
// --parent tree, and the text renderings that want []*types.Issue rather
// than a counted page. Routing only their JSON paths through the role
// would fork each command in two, which is more drift, not less. Two of
// FILTER itself for things this role does not express — --claim, --gated,
// --explain, --mol, --watch, the hierarchical --parent tree, and the text
// renderings that want []*types.Issue rather than a counted page. Routing
// only their JSON paths through the role would fork each command in two,
// which is more drift, not less. The --max-rows cap USED to be on that
// list and no longer is: it is MaxRows below, so `bd list` resolves it
// onto the request and the builder is the only thing that writes it onto a
// filter. Two of
// `bd ready`'s questions HAVE left the filter behind, each for the role
// that owns it: --claim is ReadyClaimer's, and the published total is
// ReadyCounter's, on both routes.
@ -392,7 +443,9 @@ type IssuePage struct {
// output, which renders the recursive walk's own result and reaches no
// epilogue on either route. Where the epilogue does run, what is left
// differing between a CLI listing and an HTTP one is presentation and the
// --max-rows cap.
// --max-rows cap — and the cap is now a difference in what each surface
// SENDS rather than one in what they can say, since MaxRows is a field of
// the request both build.
// - EXECUTION, for `bd ready`, on the PROXIED route only. The direct route
// keeps an epilogue of its own and cannot give it up: it answers the
// strictly larger question "how many rows did the limit hide" and

View file

@ -26,13 +26,23 @@ type readyScopeField struct {
// intersection: fields the builder copies onto the filter and the projection
// then discards.
//
// Three groups are deliberately ABSENT, because listing them here would refuse
// 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 MaxRows.
// 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