beads/internal/workapi/storequerier/querier.go
Julian Knutsen e29abaea37
Converge Offset and MaxRows on all three legs, and fix the panic and the breaker hole under them (#5435)
Offset and MaxRows were mirror-image splits: the unit-of-work seam honored
Offset and refused MaxRows; the two store legs did the opposite. Three contract
cases absorbed that with an "either HONORED or REFUSED with a typed
*ErrUnsupported" disjunction.

A contract that asserts a capability is either honored or refused is not pinning
semantics — it is ratifying a split. All three are gone, along with
assertReaderUnsupported. Converging upward rather than uow-matches-server is the
owner's one ratified exception, because the server refusing MaxRows was a
capability gap rather than a semantics choice.

Offset now runs in the shared page epilogue on every leg rather than in whichever
seam could render it: the skip must happen in the caller's display order, which
is not SQL-expressible for --sort id, and a row the database skips is a row the
query matched.

Two bugs fixed under it.

The panic: domain/db rendered LIMIT 18446744073709551615 OFFSET k for an
unbounded query, and Dolt sized a buffer from limit+offset and returned a
recovered makeslice panic instead of rows. The contract case had been shaped
around it, bounding every request, with a comment calling it a storage-seam bug
that predates the role. It now drives the unbounded shape.

The breaker hole, found by review: proxied bd list --watch with an offset and a
cap counted the cap against post-skip rows while the page route counted
pre-skip, so the same flags produced opposite verdicts — L=10, k=2, M=3 over 5
rows returned a page on one route and ErrTooManyRows on the other. Newly
reachable since 3b2385922 removed the proxied --max-rows rejection ahead of the
watch dispatch, and it falsified the comment claiming no caller combines an
offset with a cap.

MaxRows semantics are now ratified and documented: the cap counts the rows the
query TOUCHED (offset+limit), not the rows the caller receives. A skipped row is
still a matched row. Review reported the Limit+Offset == MaxRows boundary as an
off-by-one; measured under those semantics the code was already correct and the
doc was wrong, so the fix was the doc plus pinning the behaviour.

A seventh cannot-fail test was caught mid-slice: an unreachable "under a
defensive cap" branch in searchWindowFor absorbed the exact regression the new
MaxRows-behind-offset arm exists to catch, and the mutation returned
INCONCLUSIVE. Removed.

Equivalence of the epilogue skip to a SQL OFFSET was checked rather than
assumed. One narrow uncovered exception stands: under --sort title, SQL
collation and Go byte-compare can disagree on non-ASCII and then pick different
skip sets. Conformance seeds ASCII.
2026-08-08 11:37:09 -07:00

69 lines
3 KiB
Go

// Package storequerier holds the store-backed implementation of
// issueops.Querier: one shared body that every store-shaped backend's Querier
// accessor hands back.
//
// It is a package of its own for the reason internal/workapi/storereader is —
// see that package's doc. Down here the only importers are the two Dolt store
// packages, and the cmd-bd-role-constructors depguard rule in .golangci.yml
// makes a front door importing it a lint failure rather than a review comment.
package storequerier
import (
"context"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/workapi"
"github.com/steveyegge/beads/issueops"
)
// New returns the boolean-query surface backed by a store handle. *DoltStore
// and *EmbeddedDoltStore answer identically because the difference between
// them is below storage.DoltStorage, not above it.
func New(store storage.DoltStorage) (issueops.Querier, error) {
if store == nil {
return nil, &issueops.ErrUnsupported{Op: "storequerier.New", Backend: "nil"}
}
return &storeQuerier{store: store}, nil
}
type storeQuerier struct{ store storage.DoltStorage }
var _ issueops.Querier = (*storeQuerier)(nil)
// THE OFFSET IS UNIFORM, not per-expression. This seam renders LIMIT without
// OFFSET, so the skip happens in Go — but it happens for BOTH shapes of query
// and it always skips MATCHES, never candidates. Which shape an expression
// takes is the evaluator's decision, so an Offset that behaved differently for
// `type=bug OR type=task` than for `type=bug` would be unpredictable from the
// outside (issueops/querier.go:70-86). A filter-expressible query reaches past
// the skipped rows in SQL; a predicate query already reads every candidate row,
// so its skip costs nothing.
func (q *storeQuerier) Query(ctx context.Context, req issueops.QueryRequest) (issueops.IssuePage, error) {
plan, err := workapi.BuildQueryPlan(req)
if err != nil {
return issueops.IssuePage{}, err
}
filter := plan.Filter
if !plan.RequiresPredicate() {
// The store seam has no HasMore of its own, so ask for one row past the
// page — and past the rows the offset skips — and let its presence be
// the answer. A predicate query carries no row limit to extend: its
// verdict comes from the count of MATCHES.
filter = workapi.WithFetchOneExtra(workapi.WithRowsBeforeThePage(filter, plan.Offset))
}
rows, err := q.store.SearchIssuesWithCounts(ctx, "", filter)
if err != nil {
return issueops.IssuePage{}, err
}
rows = workapi.ApplyQueryPredicate(rows, plan.Predicate)
// The shared epilogue: the sort, the skip, the cut and the verdict written
// out longhand is how two routes of one command came to disagree about
// `--sort id --limit 5`. A query request refuses an Offset under a display
// order (workapi.BuildQueryPlan), so the sort below is always a no-op when
// the skip is not — which is why the two can share one function here.
items, hasMore := workapi.FinishPageAt(rows, plan.SortBy, plan.Reverse, plan.Offset, plan.Limit, false)
return issueops.IssuePage{Items: items, HasMore: hasMore}, nil
}