test(cli,storage): BEADS_MAX_ROWS behavioral + opt-out gate tests (be-x42v) (#4160)

* feat(storage): be-x42v.1 BEADS_MAX_ROWS defensive cap foundation

Add IssueFilter.MaxRows + IssueFilter.MaxRowsSource and a typed
issueops.ErrTooManyRows error. searchTableInTx routes its LIMIT through
EffectiveSearchLimit (LIMIT MaxRows+1 when MaxRows>0, with Limit
preserved otherwise); SearchIssuesInTx checks EnforceMaxRowsCap after
the issues+wisps merge so the cap reflects the count returned to the
caller. Both helpers are exported so future PG-backend support can
reuse the same logic.

Default MaxRows=0 disables the cap and is byte-identical to today at
every existing call site. Limit semantics are unchanged: Limit=0 still
means unlimited at the contract level.

PG backend is not on origin/main yet; PG cap support is a follow-up
when the postgres backend merges. Validator's per-backend bead exercises
the issueops path via Dolt/embedded fixtures.

Refs: be-x42v (designer §3/§6.2), be-jp5s (architecture D1/R-03).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(cli): be-x42v.2 wire --max-rows / BEADS_MAX_ROWS on CLI surface

Adds cmd/bd/max_rows.go with three helpers: addMaxRowsFlag registers
--max-rows int with the designer's spec help text, resolveMaxRows
picks flag > env > 0 (negative flag → exit 1, bad env → warn-and-ignore),
and handleMaxRowsError pattern-matches *issueops.ErrTooManyRows to
emit the two-line stderr message and exit 2 with stdout empty.

The flag is wired on bd list, bd ready, bd dep tree, bd find-duplicates,
and bd graph (designer §4). The env-only resolveMaxRowsEnvOnly variant
is wired on bd lint and the SearchIssues paths inside bd doctor
(conventions + pollution checks). bd cleanup, bd gc, bd export,
bd export --auto, bd migrate-issues, and bd jira explicitly set
MaxRows=0 / MaxRowsSource="" in code so a misconfigured env can't
abort a data-integrity sweep partway through.

bd ready needed storage-layer support too: WorkFilter gains MaxRows +
MaxRowsSource and GetReadyWorkInTx routes its LIMIT through
EffectiveSearchLimit and enforces the cap via EnforceMaxRowsCap on
the row count returned to the caller. bd dep tree applies the cap at
the CLI layer on the TreeNode count since the tree walk doesn't go
through IssueFilter.

bd config show gains a standalone-env collector so BEADS_MAX_ROWS
shows up alongside BEADS_DIR etc. when set. The Viper-managed env
detection skips it because BEADS_MAX_ROWS isn't bound to a config key.

Adds a CONTRIBUTING.md section documenting the opt-out rule for new
IssueFilter sites that aren't on designer §4's wired-up list, with a
pointer to the validator's opt-out test gates (be-x42v.4).

Smoke-tested against the rig database (298 issues):
- bd list --max-rows 5 → exit 2, "--max-rows=5"
- BEADS_MAX_ROWS=5 bd list → exit 2, "BEADS_MAX_ROWS=5"
- BEADS_MAX_ROWS=banana bd list --limit 3 → warn + exit 0
- BEADS_MAX_ROWS=5 bd list --max-rows 0 --limit 3 → exit 0
- bd list --max-rows -1 → exit 1, "must be non-negative"
- bd ready --max-rows 5 → exit 2 (storage layer fires)
- bd dep tree be-jp5s --max-rows 1 → exit 2 (CLI-layer count)
- bd find-duplicates --max-rows 5 → exit 2
- bd graph --all --max-rows 5 → exit 2
- BEADS_MAX_ROWS=5 bd lint → exit 2 (env-only)
- BEADS_MAX_ROWS=5 bd export → exit 0, 299 lines (opt-out)
- BEADS_MAX_ROWS=10 bd config show → lists BEADS_MAX_ROWS

The 10 CLI behavioral test scenarios for bd list are owned by
be-x42v.3 (validator). Coverage for the non-list paths, the env-only
doctor family, and config show is filed as be-u8z9 (needs-tests,
routed to validator).

Refs: be-x42v (designer §2-§5), be-x42v.1 (foundation).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: release gate PASS for be-x42v.1 + be-x42v.2 (BEADS_MAX_ROWS)

Documents PASS evaluation across the six gate criteria for the
storage foundation (be-x42v.1, 3900c1bdc) and the CLI wiring
(be-x42v.2, dea537c56) shipping together. Review verdicts: be-xf0o
(foundation) and be-2p12 (CLI), both PASS from Opus 4.7 reviewer.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: regenerate CLI reference for --max-rows flag

* docs: revert federation to pure-go stub in CLI_REFERENCE.md

CI's check-doc-flags freshness check runs generate-cli-docs.sh with
CGO_ENABLED=0. The previous regeneration used a CGO binary, expanding
the federation section with subcommands. Revert to the requires-CGO
stub that the pure-go binary produces.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: revert website federation.md pages to pure-go stub (be-x42v)

Three website cli-reference/federation.md files still had CGO-enabled
content after CLI_REFERENCE.md was reverted. This commit brings them
into sync with the pure-go stub, resolving the Check doc flags freshness
CI failure on PR #3908.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(cli): be-u8z9 BEADS_MAX_ROWS non-list command paths + config show

Locks down the manually-verified behavior shipped in be-x42v.2 across the
CLI surface beyond `bd list`.

cmd/bd/max_rows_test.go (new):
  - ReadyMaxRows_FlagOverCap_Exits2  - bd ready --max-rows N → exit 2
  - ReadyMaxRows_EnvOverCap_Exits2   - BEADS_MAX_ROWS=N bd ready → exit 2
  - DepTreeMaxRows_TreeNodes_Exits2  - tree-node count cap in dep tree
  - FindDuplicatesMaxRows_Exits2     - find-duplicates --max-rows N
  - GraphAllMaxRows_Exits2           - graph --all --max-rows N
  - LintMaxRows_EnvOnly_Exits2       - bd lint with BEADS_MAX_ROWS=N
  - LintMaxRows_NoFlagAccepted       - cobra rejects --max-rows on lint
  - ConfigShow_ListsBeadsMaxRows     - bd config show surfaces the env var
  - ConventionsMaxRows_EnvOnly       - skipped (bd doctor needs server mode,
                                       follow-up filed as be-pc8c)
  - PollutionMaxRows_EnvOnly         - skipped (same reason)

cmd/bd/ready_max_rows_test.go (new):
  - TestGetReadyWork_MaxRowsSuite — exercises WorkFilter.MaxRows in
    GetReadyWork (under cap / over cap / zero disabled / with Limit
    matrix), via newTestStore. Companion to the SearchIssues parity
    work in be-x42v.3.

Refs: be-u8z9 (this bead), be-x42v.2 (builder), be-pc8c (follow-up).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(cli,storage): be-x42v.3 BEADS_MAX_ROWS bd list scenarios + backend parity

Covers the 10 CLI scenarios from designer §6.1 against `bd list` and the
5 storage scenarios from designer §6.2 against both Dolt-server and
embedded backends.

cmd/bd/max_rows_test.go (extended):
  TestEmbeddedMaxRowsList — 10 subtests on a shared 21-issue rig:
    - Disabled_NoEnv             (baseline, no cap)
    - Flag_UnderCap              (--max-rows 100 over 21 rows → success)
    - Flag_OverCap               (--max-rows 5 → exit 2, source attribution, empty stdout)
    - Env_OverCap                (BEADS_MAX_ROWS=5 → exit 2, env source)
    - Flag_OverridesEnv          (env=5 flag=100 → success)
    - Flag_Zero_OverridesEnv     (env=5 --max-rows 0 → success, explicit disable)
    - BadEnv_LogsAndIgnores      (env=banana → warning + normal output, exit 0)
    - Negative_FlagRejected      (--max-rows -1 → "must be non-negative", exit 1)
    - LimitSet_CapTighter        (--limit 100 --max-rows 5 → exit 2)
    - LimitSet_CapLooser         (--limit 5 --max-rows 100 → 5 rows, exit 0)

internal/storage/embeddeddolt/search_max_rows_test.go (new):
  TestSearchIssues_MaxRows_{NotExceeded,Exceeded,Zero_NoCap,WithLimit}
  Exercises SearchIssues end-to-end against the embedded backend on a
  6-row fixture, including the four-quadrant (Limit, MaxRows) matrix.

internal/storage/dolt/search_max_rows_test.go (new):
  Identical scenarios against the dolt-server backend. Per-backend
  parity is implicit: both SearchIssues entry points wrap
  issueops.SearchIssuesInTx, so cap behavior is shared by construction.
  Same fixture + same assertions ensures divergence cannot ship silently.

PG backend coverage is deferred until the postgres-backend branch lands
(per PR #3908 description and parent designer notes).

Refs: be-x42v.3 (this bead), be-x42v.2 (builder), be-u8z9 (sibling validator for non-list paths).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(cli): be-x42v.4 opt-out gate tests for data-integrity commands

Add filterCapturingStore spy and four MaxRows=0 gate tests asserting
that bd export, bd export --auto, bd jira sync, and bd migrate-issues
always construct IssueFilter with MaxRows=0 / MaxRowsSource="" per
designer §4.1 opt-out rule. A BEADS_MAX_ROWS env var on these paths
would corrupt backups, sync state, or migration runs mid-flight.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(cli): be-x42v.4 add TestExport_BypassesBeadsMaxRows behavioral gate

End-to-end belt-and-suspenders test (designer §6.4): sets BEADS_MAX_ROWS=1,
seeds 5 task issues, runs runExport, and asserts 5 JSONL lines in the output.
Completes the be-x42v.4 acceptance criteria for the bypass behavioral test
alongside the filter-spy gate already committed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(cli): be-pc8c server-mode BEADS_MAX_ROWS gate for bd doctor --check={conventions,pollution}

TestDoctorConventionsMaxRows_EnvOnly_Exits2 and TestDoctorPollutionMaxRows_EnvOnly_Exits2
cover the two subtests that were skipped in max_rows_test.go because bd doctor refuses
to run in embedded mode (doctor.go:188). Both tests seed 6 open issues against the
Dolt test server with BEADS_MAX_ROWS=3, assert exit 2, and confirm BEADS_MAX_ROWS=3
in the combined output.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(search): enforce MaxRows cap when wisps table is empty

SearchIssuesInTx skipped EnforceMaxRowsCap on the common empty-wisps
path: when filter.Ephemeral is nil/false and the wisps table is empty,
the early `return results, nil` returned before the post-merge cap check.
The issues-only result set (LIMIT cap+1) could exceed MaxRows yet never
trip ErrTooManyRows. Enforce the cap before the early return.

Fixes TestSearchIssues_MaxRows_Exceeded_ReturnsErrTooManyRows and
TestSearchIssues_MaxRows_WithLimit (internal/storage/embeddeddolt).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(rebase): re-home BEADS_MAX_ROWS enforcement onto post-rebase seams

Fixes gaps exposed by rebasing PR #4160 onto current upstream/main,
found by actually running the PR's own gate tests rather than just
resolving textual conflicts:

- internal/storage/issueops/search.go: the Q2 perf-escape-hatch
  SkipWisps early return (added by main's search perf work, landed
  after this PR's original design) skipped EnforceMaxRowsCap entirely.
  bd list sets SkipWisps=true by default, so `bd list --max-rows N`
  silently ignored the cap. Enforce the cap on that return path too,
  mirroring the existing empty-wisps-table fix alongside it.

- internal/storage/issueops/search_counts.go: SearchIssuesWithCountsInTx
  (the `--json` query path, already present at the PR's merge-base but
  never wired for MaxRows by the original be-x42v.1/.2 commits) neither
  sized its SQL LIMIT off the cap nor enforced it on the merged result.
  Thread filter.MaxRows through EffectiveSearchLimit for the query LIMIT
  and check EnforceMaxRowsCap in the shared finishSearchIssuesWithCounts
  terminal helper (now returns an error), which every exit path already
  routed through. Fixes be-x42v.3's TestEmbeddedMaxRowsList/Flag_OverCap
  (`bd list --json --max-rows 5`), which failed after the rebase.

- cmd/bd/jira_max_rows_gate_test.go,
  cmd/bd/migrate_issues_max_rows_gate_test.go: seed INSERTs predate
  migration 0049 (LONGTEXT NOT NULL on issues.description/design/
  acceptance_criteria/notes, no default) that landed on main after
  this branch's merge-base. Provide empty-string values for the
  now-required columns.

Not fixed (separate, pre-existing gap; no gate test in this PR
exercises it): GetReadyWorkWithCountsInTx (`bd ready --json` /
`bd list --ready --json`) also doesn't thread MaxRows. Left alone to
keep this rebase to conflict resolution rather than expanding scope;
worth a follow-up bead.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): address adjudicated cross-vendor review follow-up (be-x42v.4)

Works the MUST-FIX / SHOULD-FIX list from the adjudicated claude-opus +
codex-gpt-5.6-sol review on the rebase (25e35cc3e), landing coverage gaps
the vendors found in the feature's own promise rather than the rebase
mechanics.

MUST-FIX:

1. internal/storage/issueops/claim.go: ClaimReadyIssueInTx forwarded the
   caller's MaxRows/MaxRowsSource into its internal unbounded
   GetReadyWorkInTx scan, so a rig-wide cap (e.g. BEADS_MAX_ROWS=100 with
   150 ready issues) hard-failed a claim that only ever consumes one row.
   Bound the internal scan via Limit instead, then clear the cap fields.

2. cmd/bd/ready.go, internal/storage/issueops/ready_work_counts.go:
   GetReadyWorkWithCountsInTx (ready --json / list --ready --json) never
   enforced MaxRows at all — a pre-existing gap in the original PR (the
   function predates this branch's merge-base), not something the rebase
   introduced. Threaded EffectiveSearchLimit into its query LIMIT and added
   EnforceMaxRowsCap via a new finishReadyWorkWithCounts terminal helper,
   mirroring finishSearchIssuesWithCounts. Wired handleMaxRowsError on the
   bd ready --json error branch.

3. cmd/bd/max_rows.go + list/ready/graph/dep/find-duplicates: proxied-server
   mode silently ignored the cap (the proxied repository doesn't thread
   MaxRows through the UOW pipeline). Added rejectMaxRowsUnderProxiedServer,
   called on every command that registers --max-rows before it diverts to
   its *ProxiedServer path — an explicit --max-rows or BEADS_MAX_ROWS now
   errors out under --proxied-server instead of no-oping.

4. cmd/bd/list.go: `--limit N --max-rows N` errored instead of truncating.
   withFetchOneExtra unconditionally bumped Limit to N+1 for its own
   >N-matches truncation-hint probe, which then crossed EffectiveSearchLimit's
   `limit > maxRows` branch and tripped the cap on the probe row alone, even
   though the delivered set is always trimmed back to N. withFetchOneExtra
   now skips the bump when MaxRows is active and no looser than Limit;
   >N-matches semantics for limit<maxRows are unaffected.

5. cmd/bd/list.go: `bd list --watch` swallowed the initial-query cap error
   (logged to stderr, returned void, exited 0). watchIssues now returns the
   initial-query error instead of handling it itself; runListCore routes it
   through handleMaxRowsError for exit-code-2 semantics. Mid-poll refresh
   failures still just log and continue (interactive command, not a reason
   to kill the watch loop).

6. cmd/bd/max_rows.go + every call site: handleMaxRowsError and the
   --max-rows usage-error path in resolveMaxRows called os.Exit directly
   from deep inside RunE, bypassing both the command's own metrics defer
   and main()'s post-ExecuteC metrics.CloseAndFlush(). Converted both to
   return errors: resolveMaxRows now returns (int, string, error) and
   handleMaxRowsError returns error, both following the exact &exitError{Code:
   N}-via-RunE precedent already used elsewhere in this package (e.g.
   list_input.go's skip-labels-conflict check, HandleErrorRespectJSON).
   doctor_conventions.go's runConventionsLint (called from a "()
   []doctorCheck" advisory-checks aggregator with no error channel) needed
   its own (([]doctorCheck, error) signature to propagate the one non-advisory
   failure mode; every other call site was already RunE-adjacent.

SHOULD-FIX (both mechanical, done):

7. cmd/bd/graph.go: `bd graph <issue>` (no --all) never resolved the cap.
   loadGraphSubgraph is a BFS over per-ID GetDependents/GetDependencies
   lookups with no IssueFilter to thread MaxRows through, so — mirroring
   dep tree — the cap is now checked post-hoc against the final
   connected-component node count. Documented both graph's per-status
   (--all) and post-hoc (single-issue) cap semantics, and dep tree's
   post-hoc semantics, in their flag help text.

8. internal/storage/issueops/ready_work.go: getReadyWispsInTx's unbounded
   (Limit<=0) branch queried and hydrated the *entire* wisps table before
   the post-merge cap check in GetReadyWorkInTx ever ran, defeating the
   "circuit breaker against pathological queries" purpose for
   --include-ephemeral. readyWorkWispIssueFilter now propagates
   MaxRows/MaxRowsSource so EffectiveSearchLimit bounds that query to
   cap+1 up front.

Tests added: TestClaimReadyIssue_MaxRows_LargePoolUnderLowCap (1),
ReadyMaxRowsJSON_FlagOverCap_Exits2 + ListReadyMaxRowsJSON_FlagOverCap_Exits2
(2), reject_max_rows_flag + reject_max_rows_env + allow_max_rows_zero under
TestProxiedServerList (3), LimitEqualsCap_TruncatesNotErrors +
LimitEqualsCap_JSON_TruncatesNotErrors (4), Watch_FlagOverCap_Exits2 (5),
GraphSingleIssueMaxRows_NodeCount_Exits2 + _UnderCap_NoError (7),
ReadyIncludeEphemeralMaxRows_FlagOverCap_Exits2 (8).

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows sweep passes in both dolt-server and
BEADS_TEST_EMBEDDED_DOLT=1 modes (one dolt-testcontainer flake observed and
confirmed non-reproducing on retry, consistent with prior sessions);
TestProxiedServerList passes with BEADS_TEST_PROXIED_SERVER=1.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): address round-2 delta review regressions (be-x42v.4 round 3)

opus verified all eight round-2 items as implemented, but codex found three
regressions those fixes introduced, confirmed on adjudication. Common
thread: enforce the cap on the DELIVERED result, not on fetched/merged
intermediates, and don't let the safety rejection block one-row operations.

1. cmd/bd/ready.go: proxied `bd ready --claim` was rejected by
   rejectMaxRowsUnderProxiedServer before it could dispatch to
   runReadyProxiedClaim, even though --claim always delivers exactly one
   row and the direct-path fix (claim.go, round 2) already exempts claim
   from cap enforcement for that exact reason. Moved the claimReady flag
   parse before the proxied branch and exempt --claim from the rejection;
   bulk (non-claim) proxied `bd ready` still rejects an active cap. Added
   claim_succeeds_under_env_max_rows_cap plus
   reject_bulk_ready_under_max_rows_{flag,env} to
   ready_proxied_integration_test.go.

2. internal/storage/issueops/ready_work_counts.go: with --include-ephemeral,
   GetReadyWorkWithCountsInTx's issues and wisps queries are each
   independently bounded by EffectiveSearchLimit(filter.Limit,
   filter.MaxRows), so the merged pre-trim slice can hold up to ~2x that
   per-table bound even when filter.Limit <= filter.MaxRows (e.g. limit=2,
   cap=3, 2 rows/table -> merged 4 -> false "too many rows" even though the
   delivered page, trimmed to 2, is well within the cap). Reordered
   finishReadyWorkWithCounts to trim to Limit before checking the cap,
   mirroring GetReadyWorkInTx's non-counts path (mergeReadyWisps already
   trims before its caller's EnforceMaxRowsCap runs). Verified this
   reproduces "4 found, --max-rows=3 exceeded" on the pre-fix code and is
   fixed after. Added ReadyIncludeEphemeralMaxRowsJSON_MergedUnderLimit_NoError.

3. cmd/bd/list.go: round-2's fix for `--limit N --max-rows N` (skip the
   withFetchOneExtra probe-row bump entirely when Limit>=MaxRows) stopped
   the false cap error but also stopped fetching the extra row, so
   len(results) could never exceed effectiveLimit and the GH#3212
   truncation notice silently stopped firing — a partial result started
   presenting as complete. Restored the probe-row fetch (Limit still bumps
   to N+1) and instead bump MaxRows to N+1 in lockstep, but only in the
   exact Limit==MaxRows case: this keeps the probe row inside the
   (temporarily N+1) cap so EnforceMaxRowsCap doesn't trip on it, while the
   CLI's own len(results)>effectiveLimit check still sees the extra row and
   correctly reports truncated=true. Tighter-cap (Limit>MaxRows) and
   looser-cap (Limit<MaxRows) cases are unaffected — MaxRows is left
   unbumped there, so a genuine violation still reports the true cap value.
   printTruncationHint's text is gated on ui.IsStderrTerminal() and
   unconditionally suppressed for this subprocess test harness's piped
   stderr (matches the existing limit_truncation_hint subtest's documented
   constraint), so the fix is verified via 4 new unit tests asserting
   withFetchOneExtra's exact bump values directly
   (TestWithFetchOneExtra_LimitEqualsCap_BumpsBothForTruncationProbe et al.)
   rather than the unobservable hint text; extended
   LimitEqualsCap_TruncatesNotErrors's comment to document this and point
   to the unit tests.

Opus nits:

4. internal/storage/issueops/claim.go: bounding the claim scan at
   Limit=MaxRows (round 2) meant a BEADS_MAX_ROWS=1 rig would only attempt
   the single top-of-queue ready row and return "nothing to claim" if it
   was transiently unclaimable (e.g. a race with another agent), even with
   plenty of other ready work available. Restored the unbounded scan
   (Limit=0); the breaker's job is to bound delivered payloads, and a
   claim's payload is always exactly one row regardless of scan size.

5. cmd/bd/find_duplicates.go: replaced the inlined proxied-server rejection
   check with a call to rejectMaxRowsUnderProxiedServer so the message
   can't drift from the other 4 commands that use it.

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows + WithFetchOneExtra sweep passes in both dolt-server
and BEADS_TEST_EMBEDDED_DOLT=1 modes; TestProxiedServerList +
TestProxiedServerReady (full suites, ~200s) pass with
BEADS_TEST_PROXIED_SERVER=1; broader TestList|TestWatch|TestGraph|
TestDepTree|TestReady|TestClaim|TestFindDuplicates sweep clean except the
same pre-existing unrelated ICU-header build failure noted in the round-2
commit (confirmed via stash-based control test to reproduce identically
without this round's changes).

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): address round-3 delta review items (be-x42v.4 round 4)

Converging: four small items adjudicated from round-3 delta reviews.

1. internal/storage/issueops/search.go, search_counts.go: round 3's
   trim-before-cap fix landed in finishReadyWorkWithCounts but not on the
   sibling bd list search paths. `bd list --include-infra --limit 2
   --max-rows 5` (3 durable + 3 wisps) exited 2 in both output modes even
   though the delivered page is 2 rows, since --include-infra disables the
   default SkipWisps escape hatch so the wisps merge actually runs.
   Reproduced live: "6 found, --max-rows=5 exceeded" on the pre-fix code.
   Mirrored the ready remedy: trim to filter.Limit (guarded by Limit>0)
   before EnforceMaxRowsCap in searchInTx's four exit points (added a
   trimToSearchLimit helper) and in finishSearchIssuesWithCounts (swapped
   the cap/trim order). Fixed search_counts.go's doc comment, which still
   asserted the old cap-before-trim rationale and directly contradicted
   ready_work_counts.go's. Single-source results are unaffected (a lone
   query never exceeds Limit when Limit>0, so the trim there is a no-op);
   Limit=0 and genuine Limit>MaxRows overage still error. Added
   IncludeInfraMergedUnderLimit_NoError (both bd list output modes) to
   TestEmbeddedMaxRowsList.

2. cmd/bd/ready.go: the round-3 fix that exempts proxied `ready --claim`
   from rejectMaxRowsUnderProxiedServer also skipped resolveMaxRows
   entirely for that branch, so `--max-rows -1` was silently accepted
   under proxied claim (every other command, direct or proxied, rejects
   it with exit 1). Still call resolveMaxRows in the claim-exempt branch
   for its validation side effect, ignoring the resolved cap for the
   claim itself. Reproduced live (claim succeeded instead of failing) on
   the pre-fix code. Added claim_rejects_invalid_max_rows_flag to
   ready_proxied_integration_test.go.

3. cmd/bd/find_duplicates.go, cmd/bd/max_rows.go: find-duplicates resolved
   --max-rows twice under proxied mode (once to build its filter, again
   inside rejectMaxRowsUnderProxiedServer), doubling the malformed-env
   stderr warning. Split rejectMaxRowsUnderProxiedServer into itself plus
   a new rejectResolvedMaxRowsUnderProxiedServer(maxRows int) that takes
   an already-resolved value; find_duplicates.go now calls the latter with
   its existing resolved maxRows instead of re-resolving.

4. internal/storage/issueops/claim.go: added a comment sentence noting the
   unbounded-scan trade-off per the adjudication note — parity with
   pre-PR main and correctness-first (preserves claim's existing
   fairness/ordering across the ready set); a bounded, paged scan is a
   deliberate follow-up, not folded in here.

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows + WithFetchOneExtra sweep passes in both dolt-server
and BEADS_TEST_EMBEDDED_DOLT=1 modes (including the two new regression
tests); full TestProxiedServerReady suite (~211s) passes with
BEADS_TEST_PROXIED_SERVER=1; internal/storage/issueops unit tests pass;
broader TestList|TestWatch|TestGraph|TestDepTree|TestReady|TestClaim|
TestFindDuplicates sweep clean except the same pre-existing unrelated
ICU-header build failure noted in prior rounds. Both new regression tests
(item 1 and item 2) reproduce the reported failure on the pre-fix code via
git-stash and pass after.

Agent-Signature: claude-sonnet-medium on behalf of maphew

* fix(review): sort merged issues+wisps before trim in searchInTx (be-x42v.4 round 5)

codex P1, confirmed live: searchInTx's merge branch concatenates two
independently ORDER BY'd legs (`results = append(filtered,
wispResults...)`), and round-4's trimToSearchLimit then sliced that
UNSORTED concatenation. With Limit=N and durable rows alone filling N, a
higher-ranked wisp (per filter.SortBy/SortDesc) was silently dropped from
the page — before round 4 the CLI received the full merged set and its own
sort-then-trim produced correct page membership; round 4 moved a naive
prefix-trim into storage ahead of any global re-sort.

Fix: added a `less func(a, b T, sortBy string, sortDesc bool) bool` field
to searchProjection[T], populated for issueProjection via sqlbuild.Less
(the existing Go-side mirror of the SQL ORDER BY, already used correctly
by search_counts.go's sortSearchIssuesWithCounts). searchInTx's merge
branch now re-sorts the concatenation via a new sortMergedResults helper
before trimToSearchLimit runs, mirroring how finishSearchIssuesWithCounts
already orders before its own trim. idProjection (bare-ID search, no
sortable payload) leaves less nil — sortMergedResults no-ops in that case;
documented why this is safe today (no current caller combines Limit>0 with
a merged, non-SkipWisps ID-only search — see id_parser.go, which always
passes Limit=0) and where to look if that changes. The other three
trimToSearchLimit call sites in searchInTx are single-source (already
SQL-ordered), so they don't need this.

Checked the two round-3/round-4-cited "mirror" precedents per the
adjudication note, since this bug's shape (unsorted-concat-then-trim) could
plausibly recur there: GetReadyWorkInTx's mergeReadyWisps already calls
sortReadyIssues(kept, filter.SortPolicy) before its own Limit trim, and
GetReadyWorkWithCountsInTx / SearchIssuesWithCountsInTx both already sort
(sortIssuesWithCountsByPolicy / sortSearchIssuesWithCounts) before their
finish* trim-then-cap helpers. All three were already globally ordered
before trimming; only searchInTx had the bug.

Added IncludeInfraMerged_WispOutranksDurable_InDeliveredPage to
TestEmbeddedMaxRowsList: 3 durable P2 issues + 1 wisp at P0 (outranks under
the default priority-ASC sort), --limit 1 in both bd list output modes —
asserts the P0 wisp is the delivered row, not an arbitrary P2 durable row.
Reproduces exactly against 77227aa67 (the durable row is returned instead
of the wisp) and passes after the fix.

Verified: go build/vet clean; full MaxRows-named + FilterHasZeroMaxRows +
BypassesBeadsMaxRows + WithFetchOneExtra + Search sweep passes in both
dolt-server and BEADS_TEST_EMBEDDED_DOLT=1 modes (including the new
regression test); internal/storage/issueops unit tests pass.

Agent-Signature: claude-sonnet-medium on behalf of matt wilkie

* docs: remove --max-rows lines from pinned-generator CLI docs (be-x42v.4 CI fix)

CI's "Check doc flags freshness" job compares docs/CLI_REFERENCE.md and
docs/cli-reference/*.md against bd built from the pin in
docs/cli-docs.pin (v1.1.0), which predates --max-rows/BEADS_MAX_ROWS —
the same pinned-doc-generator trap that hit PRs 3920 and 4022 in this
sweep. Any doc lines this PR added for the new flag are flagged stale
against that older pinned build, and the failure cascades into "PR
Policy (wrapper timing)" via make ci-pr-policy.

Applied CI's own generated fix verbatim (downloaded the
cli-docs-freshness-patch artifact from the failing job
https://github.com/gastownhall/beads/actions/runs/30067827283/job/89403539322,
git apply --check passed cleanly, applied as-is — no manual edits).
Removes the six --max-rows generated-doc lines (bd list, bd ready, bd dep
tree, bd find-duplicates, bd graph — CLI_REFERENCE.md and the matching
cli-reference/*.md) plus the incidental column-width realignment in the
bd graph flag tables that removing the widest flag name triggers.

The flag help strings themselves (cmd/bd/max_rows.go's addMaxRowsFlag)
are untouched — those are the source of truth for docs generation and
will regenerate correctly once docs/cli-docs.pin advances past this
PR's merge. This is a pinned-generator artifact of the CI pipeline, not
a statement that the flag is undocumented.

Agent-Signature: claude-sonnet-medium on behalf of maphew

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
This commit is contained in:
Jim Wordelman 2026-07-24 01:40:36 -07:00 • committed by GitHub
commit a9a48d6e36
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
42 changed files with 3433 additions and 65 deletions

View file

@ -486,6 +486,7 @@ gate that rc.1 introduced, and ships the validated upgrade documentation.
- **`dependencies.depends_on_id` is now a STORED generated column.** The polymorphic target has been split into three typed columns: `depends_on_issue_id`, `depends_on_wisp_id`, `depends_on_external`. `depends_on_id` remains as `COALESCE(...) STORED` for read paths; **writes to `depends_on_id` will fail** — code that inserts dependencies must populate exactly one typed column (enforced by a new `ck_dep_one_target` CHECK). Same split mirrored to `wisp_dependencies` with a corresponding `ck_wisp_dep_one_target`. Migrations `0041` (tracked) and `ignored/0003` (wisps) perform the column split, copy existing rows by classifying their targets against `issues` / `wisps`, and add the new typed-target indexes. ([#3952](https://github.com/gastownhall/beads/pull/3952))
- **Most existing dependency-table FKs now use `ON UPDATE CASCADE`.** Migration `0042` rebuilds `fk_dep_issue`, `fk_labels_issue`, `fk_comments_issue`, `fk_events_issue`, `fk_snapshots_issue`, and `fk_comp_snap_issue` to cascade on both delete and update. Same treatment for the wisp-side FKs in `ignored/0003`. Prefix rename and ID-update paths rely on this cascade instead of touching aux tables manually. ([#3952](https://github.com/gastownhall/beads/pull/3952))
- **Migrations `0041` and `0042` are intentionally irreversible.** The matching `.down.sql` files are documented no-ops because rebuilding the polymorphic column from typed columns would require schema-aware backfill that the storage layer no longer performs. Restore from a prior `dolt` commit if rollback is required. ([#3952](https://github.com/gastownhall/beads/pull/3952))
- **`BEADS_MAX_ROWS` / `--max-rows` defensive row cap** — ops can now set `BEADS_MAX_ROWS=N` (or pass `bd list --max-rows N`) to bound `SearchIssues` result sets. Default is disabled; on overage, `bd` exits with code 2 and writes a two-line error to stderr (stdout stays empty so `jq` pipelines don't get half-rendered JSON). The flag is wired on `bd list`, `bd ready`, `bd dep tree`, `bd find-duplicates`, and `bd graph`. The env var is also honored by `bd doctor`, `bd lint`, `bd doctor-conventions`, and `bd doctor-pollution`. `bd cleanup`, `bd gc`, `bd export`, `bd export --auto`, `bd migrate-issues`, and `bd jira` explicitly opt out so a misconfigured env can't abort a sweep partway. (be-x42v)
### Fixed

View file

@ -165,6 +165,28 @@ test and why (the test pyramid and tiering we follow), see
- Add inline code comments for complex logic
- Include examples in documentation
## Storage filter conventions
### `IssueFilter.MaxRows` opt-out rule (be-x42v)
`types.IssueFilter` carries a defensive row cap (`MaxRows int`,
`MaxRowsSource string`) that the storage layer enforces via
`*issueops.ErrTooManyRows`. The cap is wired from `--max-rows` /
`BEADS_MAX_ROWS` on user-facing commands listed in designer §4 of be-x42v
(`bd list`, `bd ready`, `bd dep tree`, `bd find-duplicates`, `bd graph`,
plus env-only on the doctor family).
**Rule for new code that builds an `IssueFilter`:** if your call site is
NOT on the designer's wired-up list, you **MUST** explicitly initialize
`filter.MaxRows = 0` and `filter.MaxRowsSource = ""`. This makes the
opt-out intentional in code review and survives future refactors that
might otherwise let the env var leak into a sweep path that must not
abort (export, gc, jira sync, migrate-issues, etc.).
The opt-out test gates (be-x42v.4) enforce this for the
export / migrate / jira / cleanup / gc paths today. New write-side or
round-trip paths should pattern-match on those tests.
## Feature Requests and Bug Reports
### Reporting Bugs

View file

@ -76,9 +76,14 @@ SEE ALSO:
ctx := rootCtx
// Build filter for closed issues. Cleanup is a scripted sweep — opt out
// of BEADS_MAX_ROWS (designer §4.1) so a misconfigured env doesn't abort
// cleanup mid-run and leave the database in an unswept state.
statusClosed := types.StatusClosed
filter := types.IssueFilter{
Status: &statusClosed,
Status: &statusClosed,
MaxRows: 0,
MaxRowsSource: "",
}
if olderThanDays > 0 {

View file

@ -94,6 +94,9 @@ func collectConfigEntries() []configEntry {
// 4. Git config (beads.role)
entries = append(entries, collectGitConfigEntries()...)
// 5. Standalone env vars not bound to Viper keys
entries = append(entries, collectStandaloneEnvEntries()...)
// Sort by key for stable output
sort.Slice(entries, func(i, j int) bool {
return entries[i].Key < entries[j].Key
@ -102,6 +105,22 @@ func collectConfigEntries() []configEntry {
return entries
}
// collectStandaloneEnvEntries returns entries for env vars that bd reads
// directly (without going through Viper). Keeping these out of Viper avoids
// polluting the default-value table for opt-in operator knobs.
func collectStandaloneEnvEntries() []configEntry {
var entries []configEntry
// BEADS_MAX_ROWS (be-x42v): defensive row cap for SearchIssues.
if raw, ok := os.LookupEnv("BEADS_MAX_ROWS"); ok && raw != "" {
entries = append(entries, configEntry{
Key: "BEADS_MAX_ROWS",
Value: raw,
Source: "env: BEADS_MAX_ROWS",
})
}
return entries
}
// collectViperEntries returns entries from all Viper-registered keys.
// Skips keys with empty default values that haven't been explicitly set.
func collectViperEntries() []configEntry {

View file

@ -15,6 +15,7 @@ import (
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/domain"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
)
@ -1017,7 +1018,11 @@ Examples:
bd dep tree gt-0iqq # Show what blocks gt-0iqq
bd dep tree gt-0iqq --direction=up # Show what gt-0iqq blocks
bd dep tree gt-0iqq --status=open # Only show open issues
bd dep tree gt-0iqq --depth=3 # Limit to 3 levels deep`,
bd dep tree gt-0iqq --depth=3 # Limit to 3 levels deep
--max-rows / BEADS_MAX_ROWS caveat: the tree walk has no query filter to
thread the cap through, so the full tree is always built first and the
node count is checked afterward (post-hoc), not during the walk.`,
Args: cobra.ExactArgs(1),
SilenceUsage: true,
SilenceErrors: true,
@ -1030,6 +1035,9 @@ Examples:
}()
if usesProxiedServer() {
if err := rejectMaxRowsUnderProxiedServer(cmd); err != nil {
return err
}
return runDepTreeProxiedServer(cmd, rootCtx, args)
}
@ -1091,6 +1099,24 @@ Examples:
tree = filterTreeByStatus(tree, types.Status(statusFilter))
}
// Apply defensive row cap (be-x42v) on the final tree-node count.
// Tree walks have no IssueFilter to thread through, so the cap is
// enforced at the CLI layer instead of in storage.
treeMaxRows, treeMaxRowsSource, err := resolveMaxRows(cmd)
if err != nil {
return err
}
if treeMaxRows > 0 && len(tree) > treeMaxRows {
if capErr := handleMaxRowsError(&issueops.ErrTooManyRows{
Found: len(tree),
Cap: treeMaxRows,
Source: treeMaxRowsSource,
}); capErr != nil {
return capErr
}
}
// Handle format presets (json handled earlier, near flag read)
if formatStr == "mermaid" {
outputMermaidTree(tree, args[0])
return nil
@ -1559,6 +1585,8 @@ func init() {
depTreeCmd.Flags().String("direction", "", "Tree direction: 'down' (dependencies), 'up' (dependents), or 'both'")
depTreeCmd.Flags().String("status", "", "Filter to only show issues with this status (open, in_progress, blocked, deferred, closed)")
depTreeCmd.Flags().String("format", "", "Output format: 'mermaid' for Mermaid.js flowchart")
// Defensive row cap (be-x42v): applied to TreeNode count after the tree is built.
addMaxRowsFlag(depTreeCmd)
// Note: --type flag intentionally omitted from depTreeCmd — TreeNode lacks
// dependency type info so filtering is not possible. Use 'bd dep list --type' instead.

View file

@ -21,7 +21,11 @@ func runConventionsCheck(path string) error {
var checks []doctorCheck
checks = append(checks, runConventionsLint()...)
lintChecks, err := runConventionsLint()
if err != nil {
return err
}
checks = append(checks, lintChecks...)
checks = append(checks, runConventionsStale()...)
checks = append(checks, runConventionsOrphans(path)...)
@ -88,26 +92,40 @@ func runConventionsCheck(path string) error {
}
// runConventionsLint checks open issues for missing template sections.
func runConventionsLint() []doctorCheck {
// runConventionsLint's doctorCheck results are advisory (per the composite
// comment above), but a MaxRows cap violation is a different kind of
// failure — an infrastructure circuit breaker, not a data-quality finding —
// so it returns a non-nil error instead of a doctorCheck in that one case.
// The caller must propagate it rather than folding it into the checks list.
func runConventionsLint() ([]doctorCheck, error) {
if store == nil {
return []doctorCheck{{
Name: "conventions.lint",
Status: statusWarning,
Message: "database not available",
Category: "Conventions",
}}
}}, nil
}
ctx := rootCtx
openStatus := types.StatusOpen
issues, err := store.SearchIssues(ctx, "", types.IssueFilter{Status: &openStatus})
// Env-only cap (designer §4): operator opt-in via BEADS_MAX_ROWS.
maxRows, maxRowsSource := resolveMaxRowsEnvOnly()
issues, err := store.SearchIssues(ctx, "", types.IssueFilter{
Status: &openStatus,
MaxRows: maxRows,
MaxRowsSource: maxRowsSource,
})
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return nil, capErr
}
return []doctorCheck{{
Name: "conventions.lint",
Status: statusWarning,
Message: fmt.Sprintf("error reading issues: %v", err),
Category: "Conventions",
}}
}}, nil
}
warningCount := 0
@ -123,7 +141,7 @@ func runConventionsLint() []doctorCheck {
Status: statusOK,
Message: fmt.Sprintf("all %d open issues pass template checks", len(issues)),
Category: "Conventions",
}}
}}, nil
}
return []doctorCheck{{
@ -132,7 +150,7 @@ func runConventionsLint() []doctorCheck {
Message: fmt.Sprintf("%d of %d open issues missing recommended sections", warningCount, len(issues)),
Fix: "bd lint",
Category: "Conventions",
}}
}}, nil
}
// runConventionsStale checks for issues with no recent activity.

View file

@ -10,7 +10,10 @@ func TestConventionsLint_NoStore(t *testing.T) {
store = nil
defer func() { store = origStore }()
checks := runConventionsLint()
checks, err := runConventionsLint()
if err != nil {
t.Fatalf("runConventionsLint: unexpected error: %v", err)
}
if len(checks) != 1 {
t.Fatalf("expected 1 check, got %d", len(checks))
}

View file

@ -0,0 +1,107 @@
//go:build cgo
// be-pc8c: Server-mode behavioral tests for BEADS_MAX_ROWS on
// `bd doctor --check=conventions` and `bd doctor --check=pollution`.
//
// Both commands call resolveMaxRowsEnvOnly() and pipe through
// handleMaxRowsError, so BEADS_MAX_ROWS in the environment should fire
// ErrTooManyRows → os.Exit(2) when the cap is exceeded. Unlike the
// embedded-dolt tests in max_rows_test.go these require the Dolt test server
// (testDoltServerPort != 0) because bd doctor refuses to run in embedded mode.
//
// Each test:
// - Creates a temp dir with a .beads/metadata.json pointing at the test server
// - Seeds 6 open issues (cap=3, so the cap fires)
// - Runs `bd doctor --check=<X>` via exec.Command with BEADS_MAX_ROWS=3
// - Asserts exit code 2 and BEADS_MAX_ROWS=3 in combined output
package main
import (
"context"
"os"
"path/filepath"
"strings"
"testing"
"github.com/steveyegge/beads/internal/testutil"
)
func TestDoctorConventionsMaxRows_EnvOnly_Exits2(t *testing.T) {
if testDoltServerPort == 0 {
t.Skip("Dolt test server not available")
}
if testutil.DoltContainerCrashed() {
t.Skipf("Dolt test server crashed: %v", testutil.DoltContainerCrashError())
}
bdBin := buildBDForInitTests(t)
tmpDir := t.TempDir()
beadsSubdir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsSubdir, 0755); err != nil {
t.Fatal(err)
}
// newTestStoreIsolatedDB creates a dedicated Dolt database and writes
// metadata.json into .beads/ so the bd subprocess opens the same DB.
s := newTestStoreIsolatedDB(t, filepath.Join(beadsSubdir, "dolt"), "dcmr")
ctx := context.Background()
for i := range 6 {
id := "dcmr-" + string(rune('a'+i))
if _, err := s.DB().ExecContext(ctx,
`INSERT INTO issues (id, title, description, design, acceptance_criteria, notes, status, priority, issue_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
id, "conventions max-rows seed", "", "", "", "", "open", 1, "task",
); err != nil {
t.Fatalf("seed issue %d: %v", i, err)
}
}
// BEADS_MAX_ROWS=3 with 6 open issues → cap fires → exit 2.
out, code := bdRunRaw(t, bdBin, tmpDir, []string{"BEADS_MAX_ROWS=3"}, "doctor", "--check=conventions")
if code != 2 {
t.Fatalf("be-pc8c: expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "BEADS_MAX_ROWS=3") {
t.Errorf("be-pc8c: stderr missing BEADS_MAX_ROWS=3 source attribution:\n%s", out)
}
}
func TestDoctorPollutionMaxRows_EnvOnly_Exits2(t *testing.T) {
if testDoltServerPort == 0 {
t.Skip("Dolt test server not available")
}
if testutil.DoltContainerCrashed() {
t.Skipf("Dolt test server crashed: %v", testutil.DoltContainerCrashError())
}
bdBin := buildBDForInitTests(t)
tmpDir := t.TempDir()
beadsSubdir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsSubdir, 0755); err != nil {
t.Fatal(err)
}
s := newTestStoreIsolatedDB(t, filepath.Join(beadsSubdir, "dolt"), "dpmr")
ctx := context.Background()
for i := range 6 {
id := "dpmr-" + string(rune('a'+i))
if _, err := s.DB().ExecContext(ctx,
`INSERT INTO issues (id, title, description, design, acceptance_criteria, notes, status, priority, issue_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
id, "pollution max-rows seed", "", "", "", "", "open", 1, "task",
); err != nil {
t.Fatalf("seed issue %d: %v", i, err)
}
}
out, code := bdRunRaw(t, bdBin, tmpDir, []string{"BEADS_MAX_ROWS=3"}, "doctor", "--check=pollution")
if code != 2 {
t.Fatalf("be-pc8c: expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "BEADS_MAX_ROWS=3") {
t.Errorf("be-pc8c: stderr missing BEADS_MAX_ROWS=3 source attribution:\n%s", out)
}
}

View file

@ -20,8 +20,17 @@ func runPollutionCheck(_ string, clean bool, yes bool) error {
ctx := rootCtx
allIssues, err := store.SearchIssues(ctx, "", types.IssueFilter{})
// Get all issues (env-only cap via BEADS_MAX_ROWS; designer §4: doctor
// family is env opt-in, no operator-facing flag).
maxRows, maxRowsSource := resolveMaxRowsEnvOnly()
allIssues, err := store.SearchIssues(ctx, "", types.IssueFilter{
MaxRows: maxRows,
MaxRowsSource: maxRowsSource,
})
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleError("fetching issues: %v", err)
}

View file

@ -109,7 +109,13 @@ func runExport(cmd *cobra.Command, args []string) error {
}
// Build filter for issues table. Export all statuses by default.
filter := types.IssueFilter{Limit: 0}
// Opt out of BEADS_MAX_ROWS (designer §4.1) — export is a data-integrity
// path and must never abort partway through an export run.
filter := types.IssueFilter{
Limit: 0,
MaxRows: 0,
MaxRowsSource: "",
}
// Exclude infra types by default (agents, roles, messages).
if !exportAll && !exportIncludeInfra {

View file

@ -318,7 +318,9 @@ func autoExportFilter(ctx context.Context) types.IssueFilter {
}
func buildAutoExportFilter(ctx context.Context) (types.IssueFilter, map[string]bool) {
filter := types.IssueFilter{Limit: 0}
// MaxRows: 0 opts out of BEADS_MAX_ROWS — auto-export is a data-integrity
// sweep and must not be capped (designer §4.1).
filter := types.IssueFilter{Limit: 0, MaxRows: 0}
var infraTypes []string
if store != nil {
infraSet := store.GetInfraTypes(ctx)

View file

@ -0,0 +1,97 @@
//go:build cgo
package main
import (
"context"
"os"
"path/filepath"
"testing"
"github.com/steveyegge/beads/internal/testutil"
)
// TestExportAuto_FilterHasZeroMaxRows is the be-x42v.4 opt-out gate for
// `bd export --auto` (the incremental auto-export run from
// PersistentPostRun). Asserts that exportToFile — the shared helper
// behind both `bd export -o` and auto-export, at cmd/bd/export_auto.go:140
// — never constructs an IssueFilter with MaxRows>0 or a non-empty
// MaxRowsSource.
//
// The auto-export path is particularly sensitive: it runs as a side
// effect of nearly every bd command and writes a git-tracked JSONL
// snapshot. If a stray BEADS_MAX_ROWS in CI tipped the filter into the
// cap branch, the auto-export would fail and every subsequent bd
// invocation would re-attempt it, propagating the error to every
// command-completion. This gate prevents that regression at write time.
//
// We invoke exportToFile directly (rather than maybeAutoExport, which
// runs guard checks first) so the test exercises the round-trip path
// without depending on config.export.auto being set in the test rig.
//
// Build tags: cgo (matches existing cgo cmd/bd tests).
func TestExportAuto_FilterHasZeroMaxRows(t *testing.T) {
if testDoltServerPort == 0 {
t.Skip("Dolt test server not available")
}
if testutil.DoltContainerCrashed() {
t.Skipf("Dolt test server crashed: %v", testutil.DoltContainerCrashError())
}
ensureTestMode(t)
saved := saveAndRestoreGlobals(t)
_ = saved
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
origWd, _ := os.Getwd()
if err := os.Chdir(tmpDir); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = os.Chdir(origWd) })
dbName := uniqueTestDBName(t)
testDBPath := filepath.Join(beadsDir, "dolt")
writeTestMetadata(t, testDBPath, dbName)
inner := newTestStore(t, testDBPath)
spy := newFilterCapturingStore(inner)
store = spy
storeMutex.Lock()
storeActive = true
storeMutex.Unlock()
t.Cleanup(func() {
store = nil
storeMutex.Lock()
storeActive = false
storeMutex.Unlock()
})
ctx := context.Background()
rootCtx = ctx
if _, err := inner.DB().ExecContext(ctx, `INSERT INTO issues (id, title, description, design, acceptance_criteria, notes, status, priority, issue_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
"gate-auto-mr-1", "Auto MaxRows gate seed", "body", "", "", "", "open", 1, "task"); err != nil {
t.Fatalf("seed: %v", err)
}
outPath := filepath.Join(tmpDir, "auto-export.jsonl")
if _, _, err := exportToFile(ctx, outPath, false); err != nil {
t.Fatalf("exportToFile: %v", err)
}
if spy.Calls() == 0 {
t.Fatal("exportToFile did not invoke SearchIssues; gate did not exercise the filter")
}
for i, f := range spy.AllFilters() {
if f.MaxRows != 0 {
t.Errorf("be-x42v.4 gate: SearchIssues call %d had filter.MaxRows=%d; bd export --auto must opt out (MaxRows=0) — designer §4.1 snapshot integrity", i, f.MaxRows)
}
if f.MaxRowsSource != "" {
t.Errorf("be-x42v.4 gate: SearchIssues call %d had filter.MaxRowsSource=%q; bd export --auto must opt out (MaxRowsSource=\"\")", i, f.MaxRowsSource)
}
}
}

View file

@ -0,0 +1,211 @@
//go:build cgo
package main
import (
"context"
"os"
"path/filepath"
"strconv"
"testing"
"github.com/steveyegge/beads/internal/testutil"
)
// TestExport_FilterHasZeroMaxRows is the be-x42v.4 opt-out gate for
// `bd export`. Asserts that runExport never constructs an IssueFilter
// with MaxRows>0 or a non-empty MaxRowsSource — both would let an
// inherited BEADS_MAX_ROWS env var abort the export mid-run and leave
// an incomplete JSONL backup on disk.
//
// Today's filter construction lives at cmd/bd/export.go:94-98:
//
// filter := types.IssueFilter{
// Limit: 0,
// MaxRows: 0,
// MaxRowsSource: "",
// }
//
// The two MaxRows fields are explicitly initialized to the zero values
// per the designer §4.1 opt-out rule for data-integrity paths. A future
// refactor that removes them — or pipes BEADS_MAX_ROWS through some
// shared resolver — would silently break round-trip integrity. This
// gate prevents that regression at SearchIssues call time.
//
// Failure modes this gate prevents:
//
// - A future "smart export" change starts honoring BEADS_MAX_ROWS to
// "warn the user on huge backups," silently corrupting backups when
// the env var is set in CI.
// - A future shared `IssueFilter` builder helper defaults MaxRows to
// the resolver value rather than 0.
// - A future MaxRowsSource normalization step prepends a non-empty
// source string and tips ErrTooManyRows into the "cap fired" branch.
//
// Build tags: cgo (matches existing cgo cmd/bd tests at e.g.
// export_test.go:1).
func TestExport_FilterHasZeroMaxRows(t *testing.T) {
if testDoltServerPort == 0 {
t.Skip("Dolt test server not available")
}
if testutil.DoltContainerCrashed() {
t.Skipf("Dolt test server crashed: %v", testutil.DoltContainerCrashError())
}
ensureTestMode(t)
saved := saveAndRestoreGlobals(t)
_ = saved
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
origWd, _ := os.Getwd()
if err := os.Chdir(tmpDir); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = os.Chdir(origWd) })
dbName := uniqueTestDBName(t)
testDBPath := filepath.Join(beadsDir, "dolt")
writeTestMetadata(t, testDBPath, dbName)
inner := newTestStore(t, testDBPath)
spy := newFilterCapturingStore(inner)
store = spy
storeMutex.Lock()
storeActive = true
storeMutex.Unlock()
t.Cleanup(func() {
store = nil
storeMutex.Lock()
storeActive = false
storeMutex.Unlock()
})
ctx := context.Background()
rootCtx = ctx
// Seed one row so runExport has something to iterate (defending
// against an early-return bail-out that would skip the spy capture).
if _, err := inner.DB().ExecContext(ctx, `INSERT INTO issues (id, title, description, design, acceptance_criteria, notes, status, priority, issue_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
"gate-mr-1", "MaxRows gate seed", "body", "", "", "", "open", 1, "task"); err != nil {
t.Fatalf("seed: %v", err)
}
exportOutput = filepath.Join(tmpDir, "out.jsonl")
exportAll = false
exportIncludeInfra = false
exportScrub = false
exportIncludeMemories = false
exportNoMemories = false
t.Cleanup(func() { exportOutput = "" })
if err := runExport(nil, nil); err != nil {
t.Fatalf("runExport: %v", err)
}
if spy.Calls() == 0 {
t.Fatal("runExport did not invoke SearchIssues; gate did not exercise the filter")
}
for i, f := range spy.AllFilters() {
if f.MaxRows != 0 {
t.Errorf("be-x42v.4 gate: SearchIssues call %d had filter.MaxRows=%d; bd export must opt out (MaxRows=0) — designer §4.1 round-trip integrity", i, f.MaxRows)
}
if f.MaxRowsSource != "" {
t.Errorf("be-x42v.4 gate: SearchIssues call %d had filter.MaxRowsSource=%q; bd export must opt out (MaxRowsSource=\"\") — a non-empty source would tip ErrTooManyRows into the cap-fired branch", i, f.MaxRowsSource)
}
}
}
// TestExport_BypassesBeadsMaxRows is the be-x42v.4 end-to-end behavioral
// test (designer §6.4) that verifies BEADS_MAX_ROWS=1 in the process
// environment does NOT limit the row count of `bd export`. Belt-and-
// suspenders alongside the filter spy above: the spy asserts on the
// internal filter construction; this test asserts on the observable
// output line count, catching any path where a shared resolver or an
// output-layer cap could still truncate the JSONL stream even when the
// SearchIssues filter is correct.
//
// The env var is set via t.Setenv so it is automatically restored after
// the test; it does NOT bleed into other tests in the suite.
func TestExport_BypassesBeadsMaxRows(t *testing.T) {
if testDoltServerPort == 0 {
t.Skip("Dolt test server not available")
}
if testutil.DoltContainerCrashed() {
t.Skipf("Dolt test server crashed: %v", testutil.DoltContainerCrashError())
}
t.Setenv("BEADS_MAX_ROWS", "1")
ensureTestMode(t)
saved := saveAndRestoreGlobals(t)
_ = saved
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
origWd, _ := os.Getwd()
if err := os.Chdir(tmpDir); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = os.Chdir(origWd) })
dbName := uniqueTestDBName(t)
testDBPath := filepath.Join(beadsDir, "dolt")
writeTestMetadata(t, testDBPath, dbName)
s := newTestStore(t, testDBPath)
store = s
storeMutex.Lock()
storeActive = true
storeMutex.Unlock()
t.Cleanup(func() {
store = nil
storeMutex.Lock()
storeActive = false
storeMutex.Unlock()
})
ctx := context.Background()
rootCtx = ctx
// Seed 5 regular task issues. bd export excludes infra types,
// templates, and ephemeral wisps by default — "task" rows pass all
// three filters and will appear in the JSONL output.
const wantRows = 5
for i := range wantRows {
id := "bypass-mr-" + strconv.Itoa(i+1)
if _, err := s.DB().ExecContext(ctx,
`INSERT INTO issues (id, title, description, design, acceptance_criteria, notes, status, priority, issue_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
id, "bypass seed "+strconv.Itoa(i+1), "body", "", "", "", "open", 1, "task",
); err != nil {
t.Fatalf("seed issue %d: %v", i+1, err)
}
}
exportFile := filepath.Join(tmpDir, "bypass-out.jsonl")
exportOutput = exportFile
exportAll = false
exportIncludeInfra = false
exportScrub = false
exportIncludeMemories = false
exportNoMemories = false
t.Cleanup(func() { exportOutput = "" })
if err := runExport(nil, nil); err != nil {
t.Fatalf("runExport: %v", err)
}
data, err := os.ReadFile(exportFile)
if err != nil {
t.Fatalf("read export file: %v", err)
}
lines := splitJSONL(data)
if len(lines) != wantRows {
t.Errorf("be-x42v.4 bypass: BEADS_MAX_ROWS=1 truncated export: got %d JSONL lines, want %d — bd export must ignore the env cap (designer §4.1 opt-out)", len(lines), wantRows)
}
}

View file

@ -65,6 +65,8 @@ func init() {
findDuplicatesCmd.Flags().StringP("status", "s", "", "Filter by status (default: non-closed)")
findDuplicatesCmd.Flags().IntP("limit", "n", 50, "Maximum number of pairs to show")
findDuplicatesCmd.Flags().String("model", "", "AI model to use (only with --method ai; default from config ai.model)")
// Defensive row cap (be-x42v): exits 2 on overage, default disabled.
addMaxRowsFlag(findDuplicatesCmd)
rootCmd.AddCommand(findDuplicatesCmd)
}
@ -104,18 +106,36 @@ func runFindDuplicates(cmd *cobra.Command, _ []string) error {
}
}
filter := types.IssueFilter{}
// Fetch issues
maxRows, maxRowsSource, err := resolveMaxRows(cmd)
if err != nil {
return err
}
filter := types.IssueFilter{
MaxRows: maxRows,
MaxRowsSource: maxRowsSource,
}
if status != "" && status != "all" {
s := types.Status(status)
filter.Status = &s
}
if usesProxiedServer() {
// maxRows was already resolved above (to build filter); reject using
// that value directly instead of re-resolving via
// rejectMaxRowsUnderProxiedServer, which would call resolveMaxRows a
// second time and double any malformed-env warning it emits.
if err := rejectResolvedMaxRowsUnderProxiedServer(maxRows); err != nil {
return err
}
return runFindDuplicatesProxiedServer(rootCtx, filter, status, method, threshold, limit, model)
}
issues, err := store.SearchIssues(rootCtx, "", filter)
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleErrorRespectJSON("fetching issues: %v", err)
}
issues = filterClosedIfNoStatus(issues, status)

View file

@ -79,9 +79,13 @@ Examples:
cutoffDays := gcOlderThan
cutoffTime := time.Now().UTC().AddDate(0, 0, -cutoffDays)
statusClosed := types.StatusClosed
// gc is a scripted internal sweep — opt out of BEADS_MAX_ROWS
// (designer §4.1) so a misconfigured env doesn't abort the sweep.
filter := types.IssueFilter{
Status: &statusClosed,
ClosedBefore: &cutoffTime,
Status: &statusClosed,
ClosedBefore: &cutoffTime,
MaxRows: 0,
MaxRowsSource: "",
}
closedIssues, err := store.SearchIssues(ctx, "", filter)

View file

@ -9,6 +9,7 @@ import (
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/metrics"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
"github.com/steveyegge/beads/internal/ui"
"github.com/steveyegge/beads/internal/utils"
@ -74,7 +75,14 @@ Examples:
bd graph --html issue-id > graph.html # Interactive browser view
bd graph --all --html > all.html # All issues, interactive
bd graph --open issue-id # Open issues only, layered by blocking order
bd graph --all --open # All open issues, compact layers`,
bd graph --all --open # All open issues, compact layers
--max-rows / BEADS_MAX_ROWS caveat: the cap is checked differently per mode.
Single-issue graphs (no --all) check the connected-component node count
after the BFS traversal completes — the whole subgraph is always walked
first, then rejected if it's over cap. --all checks each status
(open/in_progress/blocked) independently, so up to 3x the cap can be loaded
in total before any individual status trips it.`,
Args: cobra.RangeArgs(0, 1),
SilenceUsage: true,
SilenceErrors: true,
@ -94,6 +102,9 @@ Examples:
}
if usesProxiedServer() {
if err := rejectMaxRowsUnderProxiedServer(cmd); err != nil {
return err
}
return runGraphProxiedServer(rootCtx, args)
}
@ -103,8 +114,15 @@ Examples:
}
if graphAll {
subgraphs, err := loadAllGraphSubgraphs(ctx, store)
maxRows, maxRowsSource, err := resolveMaxRows(cmd)
if err != nil {
return err
}
subgraphs, err := loadAllGraphSubgraphs(ctx, store, maxRows, maxRowsSource)
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleErrorRespectJSON("loading all issues: %v", err)
}
return renderGraphAllSubgraphs(subgraphs)
@ -119,6 +137,26 @@ Examples:
if err != nil {
return HandleErrorRespectJSON("loading graph: %v", err)
}
// Apply the defensive row cap (be-x42v) on the connected-component
// node count. loadGraphSubgraph is a BFS over GetDependents/
// GetDependencies (per-ID lookups, no IssueFilter to thread MaxRows
// through), so — like `bd dep tree` — the cap is checked post-hoc
// against the final node set rather than during traversal.
graphMaxRows, graphMaxRowsSource, err := resolveMaxRows(cmd)
if err != nil {
return err
}
if graphMaxRows > 0 && len(subgraph.Issues) > graphMaxRows {
if capErr := handleMaxRowsError(&issueops.ErrTooManyRows{
Found: len(subgraph.Issues),
Cap: graphMaxRows,
Source: graphMaxRowsSource,
}); capErr != nil {
return capErr
}
}
return renderGraphSingleSubgraph(subgraph)
},
}
@ -311,6 +349,8 @@ func init() {
graphCmd.Flags().BoolVar(&graphDOT, "dot", false, "Output Graphviz DOT format (pipe to: dot -Tsvg > graph.svg)")
graphCmd.Flags().BoolVar(&graphHTML, "html", false, "Output self-contained interactive HTML (redirect to file)")
graphCmd.Flags().BoolVar(&graphOpen, "open", false, "Show only open issues (filters out closed/deferred), forces compact layer format")
// Defensive row cap (be-x42v): exits 2 on overage, default disabled.
addMaxRowsFlag(graphCmd)
graphCmd.ValidArgsFunction = issueIDCompletion
rootCmd.AddCommand(graphCmd)
graphCmd.AddCommand(graphCheckCmd)
@ -418,8 +458,10 @@ func loadGraphSubgraph(ctx context.Context, s storage.DoltStorage, issueID strin
}
// loadAllGraphSubgraphs loads all open issues and groups them by connected component
// Each component is a subgraph of issues that share dependencies
func loadAllGraphSubgraphs(ctx context.Context, s storage.DoltStorage) ([]*TemplateSubgraph, error) {
// Each component is a subgraph of issues that share dependencies. The defensive
// row cap (be-x42v) is propagated to each per-status SearchIssues call so any
// single status that exceeds the cap returns the typed error directly.
func loadAllGraphSubgraphs(ctx context.Context, s storage.DoltStorage, maxRows int, maxRowsSource string) ([]*TemplateSubgraph, error) {
if s == nil {
return nil, fmt.Errorf("no database connection")
}
@ -430,7 +472,9 @@ func loadAllGraphSubgraphs(ctx context.Context, s storage.DoltStorage) ([]*Templ
for _, status := range []types.Status{types.StatusOpen, types.StatusInProgress, types.StatusBlocked} {
statusCopy := status
issues, err := s.SearchIssues(ctx, "", types.IssueFilter{
Status: &statusCopy,
Status: &statusCopy,
MaxRows: maxRows,
MaxRowsSource: maxRowsSource,
})
if err != nil {
return nil, fmt.Errorf("failed to search issues: %w", err)

View file

@ -251,7 +251,12 @@ func runJiraStatus(cmd *cobra.Command, args []string) error {
configured := jiraURL != "" && len(projectKeys) > 0
allIssues, err := store.SearchIssues(ctx, "", types.IssueFilter{})
// jira sync is a round-trip path — opt out of BEADS_MAX_ROWS
// (designer §4.1) so a misconfigured env doesn't abort partway.
allIssues, err := store.SearchIssues(ctx, "", types.IssueFilter{
MaxRows: 0,
MaxRowsSource: "",
})
if err != nil {
return HandleErrorRespectJSON("%v", err)
}

View file

@ -0,0 +1,146 @@
//go:build cgo
package main
import (
"context"
"os"
"path/filepath"
"testing"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/testutil"
"github.com/steveyegge/beads/internal/tracker"
"github.com/steveyegge/beads/internal/types"
)
// TestJiraSync_FilterHasZeroMaxRows is the be-x42v.4 opt-out gate for
// the Jira sync path. Asserts that the sync engine's SearchIssues calls
// (internal/tracker/engine.go:246, :315, etc.) never carry MaxRows>0
// or a non-empty MaxRowsSource. A BEADS_MAX_ROWS-tripped sync would
// abort mid-conflict-detection or mid-push, leaving partial state on
// either side of the boundary.
//
// Path under test: tracker.Engine.DetectConflicts at engine.go:226. The
// engine builds its filter with `types.IssueFilter{}` (zero value),
// which gives MaxRows=0 / MaxRowsSource="" implicitly. This gate
// catches a future refactor that swaps in a builder helper that pulls
// MaxRows from the resolver — silent corruption of the sync contract.
//
// We construct a minimal stubMaxRowsTracker satisfying the
// tracker.IssueTracker interface (13 methods) rather than wiring a real
// Jira tracker. The tracker's only role in DetectConflicts is to scope
// external-ref matching; returning IsExternalRef=true makes every
// seeded row a candidate and exercises the SearchIssues call.
//
// Build tags: cgo (matches existing cgo cmd/bd tests).
func TestJiraSync_FilterHasZeroMaxRows(t *testing.T) {
if testDoltServerPort == 0 {
t.Skip("Dolt test server not available")
}
if testutil.DoltContainerCrashed() {
t.Skipf("Dolt test server crashed: %v", testutil.DoltContainerCrashError())
}
ensureTestMode(t)
saved := saveAndRestoreGlobals(t)
_ = saved
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
origWd, _ := os.Getwd()
if err := os.Chdir(tmpDir); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = os.Chdir(origWd) })
dbName := uniqueTestDBName(t)
testDBPath := filepath.Join(beadsDir, "dolt")
writeTestMetadata(t, testDBPath, dbName)
inner := newTestStore(t, testDBPath)
spy := newFilterCapturingStore(inner)
store = spy
storeMutex.Lock()
storeActive = true
storeMutex.Unlock()
t.Cleanup(func() {
store = nil
storeMutex.Lock()
storeActive = false
storeMutex.Unlock()
})
ctx := context.Background()
rootCtx = ctx
// last_sync seeded so DetectConflicts proceeds past the early
// "no previous sync" return at engine.go:235.
if err := inner.SetLocalMetadata(ctx, "stubmr.last_sync", "2026-01-01T00:00:00Z"); err != nil {
t.Fatalf("SetLocalMetadata: %v", err)
}
// Seed one row with an external ref so DetectConflicts has
// something to consider (defending against an early bail-out that
// would skip the spy capture).
if _, err := inner.DB().ExecContext(ctx, `INSERT INTO issues (id, title, description, design, acceptance_criteria, notes, status, priority, issue_type, external_ref) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
"jira-mr-1", "Jira MaxRows gate seed", "", "", "", "", "open", 1, "task", "https://stubmr.test/EXT-1"); err != nil {
t.Fatalf("seed: %v", err)
}
engine := tracker.NewEngine(&stubMaxRowsTracker{}, spy, "tester")
if _, err := engine.DetectConflicts(ctx); err != nil {
t.Fatalf("DetectConflicts: %v", err)
}
if spy.Calls() == 0 {
t.Fatal("DetectConflicts did not invoke SearchIssues; gate did not exercise the filter")
}
for i, f := range spy.AllFilters() {
if f.MaxRows != 0 {
t.Errorf("be-x42v.4 gate: SearchIssues call %d had filter.MaxRows=%d; jira sync must opt out (MaxRows=0) — designer §4.1 cross-system round-trip", i, f.MaxRows)
}
if f.MaxRowsSource != "" {
t.Errorf("be-x42v.4 gate: SearchIssues call %d had filter.MaxRowsSource=%q; jira sync must opt out (MaxRowsSource=\"\")", i, f.MaxRowsSource)
}
}
}
// stubMaxRowsTracker satisfies tracker.IssueTracker with no-op
// behavior. It exists solely to feed tracker.NewEngine in the
// be-x42v.4 MaxRows gate test; only the methods DetectConflicts
// actually touches (ConfigPrefix, IsExternalRef, DisplayName) produce
// non-trivial values. Every other method is a tracker-side no-op so
// the spy's storage-side capture is the only side effect of running
// DetectConflicts.
//
// Named distinctly from any be-uwvs.5 stubTracker so the two gate
// tests coexist in the same package once both beads land.
type stubMaxRowsTracker struct{}
func (*stubMaxRowsTracker) Name() string { return "stubmr" }
func (*stubMaxRowsTracker) DisplayName() string { return "StubMR" }
func (*stubMaxRowsTracker) ConfigPrefix() string { return "stubmr" }
func (*stubMaxRowsTracker) Init(_ context.Context, _ storage.Storage) error { return nil }
func (*stubMaxRowsTracker) Validate() error { return nil }
func (*stubMaxRowsTracker) Close() error { return nil }
func (*stubMaxRowsTracker) FieldMapper() tracker.FieldMapper { return nil }
func (*stubMaxRowsTracker) IsExternalRef(_ string) bool { return true }
func (*stubMaxRowsTracker) ExtractIdentifier(_ string) string { return "" }
func (*stubMaxRowsTracker) BuildExternalRef(_ *tracker.TrackerIssue) string { return "" }
func (*stubMaxRowsTracker) FetchIssues(_ context.Context, _ tracker.FetchOptions) ([]tracker.TrackerIssue, error) {
return nil, nil
}
func (*stubMaxRowsTracker) FetchIssue(_ context.Context, _ string) (*tracker.TrackerIssue, error) {
return nil, nil
}
func (*stubMaxRowsTracker) CreateIssue(_ context.Context, _ *types.Issue) (*tracker.TrackerIssue, error) {
return nil, nil
}
func (*stubMaxRowsTracker) UpdateIssue(_ context.Context, _ string, _ *types.Issue) (*tracker.TrackerIssue, error) {
return nil, nil
}

View file

@ -69,9 +69,16 @@ Examples:
if len(args) > 0 {
issues = lintCollectByIDs(ctx, args, store.GetIssue)
} else {
// Lint all matching issues (env-only cap; designer §4 doctor family).
filter := buildLintFilter(typeFilter, statusFilter)
filter.MaxRows, filter.MaxRowsSource = resolveMaxRowsEnvOnly()
var err error
issues, err = store.SearchIssues(ctx, "", buildLintFilter(typeFilter, statusFilter))
issues, err = store.SearchIssues(ctx, "", filter)
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleError("%v", err)
}
}

View file

@ -39,8 +39,36 @@ func withStorage(ctx context.Context, store storage.DoltStorage, dbPath string,
return fmt.Errorf("no storage available")
}
// withFetchOneExtra bumps Limit by one so the caller can detect "more
// results than the limit" (GH#3212) by comparing len(results) against the
// original limit.
//
// `--limit N --max-rows N` (equal) needs special handling so this bump
// doesn't collide with the MaxRows cap check: EffectiveSearchLimit treats
// Limit==MaxRows as "no overage sniff" (returns Limit verbatim, no +1 — see
// EffectiveSearchLimit's doc and the WithLimit_LimitAtCap_NoError storage
// test), but bumping Limit to N+1 alone flips that to Limit>MaxRows, which
// *does* sniff for overage — so the probe row itself would trip
// EnforceMaxRowsCap(N+1, N, ...) even though the delivered set is always
// trimmed back to N. Bumping MaxRows by one in lockstep, only in this exact
// N==M case, keeps the probe row inside the (temporarily N+1) cap so
// EnforceMaxRowsCap never fires on it while still fetching N+1 rows for the
// truncation check below. This can't false-negative a real violation: the
// query's own LIMIT is capped at N+1 either way, so "more than N+1 matches
// exist" was already undetectable at Limit==MaxRows before this bump ever
// existed (same "no overage detection above the equal cap" contract
// EffectiveSearchLimit documents for the unbumped case).
//
// This does not change the Limit>MaxRows (tighter-cap) or Limit<MaxRows
// cases: EffectiveSearchLimit's branch selection there is unaffected by a
// one-row bump to Limit, and MaxRows is left untouched, so a genuine
// tighter-cap violation still fires with the correct (unbumped) Cap value
// in the error message.
func withFetchOneExtra(filter types.IssueFilter) types.IssueFilter {
if filter.Limit > 0 {
if filter.MaxRows > 0 && filter.Limit == filter.MaxRows {
filter.MaxRows++
}
filter.Limit++
}
return filter
@ -62,6 +90,8 @@ func readyWorkFilterFromIssueFilter(filter types.IssueFilter) types.WorkFilter {
ExcludeTypes: filter.ExcludeTypes,
MetadataFields: filter.MetadataFields,
HasMetadataKey: filter.HasMetadataKey,
MaxRows: filter.MaxRows,
MaxRowsSource: filter.MaxRowsSource,
}
if filter.IssueType != nil {
wf.Type = string(*filter.IssueType)
@ -200,12 +230,18 @@ func displayWatchedIssueList(ctx context.Context, store watchListDependencyStore
displayPrettyListWithDeps(issues, true, allDeps)
}
func watchIssues(ctx context.Context, store storage.DoltStorage, filter types.IssueFilter, ready bool, parentID string, sortBy string, reverse bool, effectiveLimit int) {
// watchIssues returns an error only for the initial query — a failure there
// means bd list --watch never displayed anything, so (unlike a mid-poll
// refresh failure, which just logs and keeps the last good snapshot on
// screen) it must propagate to the caller. In particular this lets
// runListCore route a MaxRows cap violation through handleMaxRowsError for
// exit-code-2 semantics instead of watchIssues swallowing it and exiting 0
// (be-x42v.4 follow-up, review MUST-FIX 5).
func watchIssues(ctx context.Context, store storage.DoltStorage, filter types.IssueFilter, ready bool, parentID string, sortBy string, reverse bool, effectiveLimit int) error {
// Initial display
issues, err := loadWatchedIssues(ctx, store, filter, ready, parentID, sortBy, reverse)
if err != nil {
fmt.Fprintf(os.Stderr, "Error querying issues: %v\n", err)
return
return err
}
truncated := effectiveLimit > 0 && len(issues) > effectiveLimit
if truncated {
@ -230,7 +266,7 @@ func watchIssues(ctx context.Context, store storage.DoltStorage, filter types.Is
select {
case <-sigChan:
fmt.Fprintf(os.Stderr, "\nStopped watching.\n")
return
return nil
case <-ticker.C:
issues, err := loadWatchedIssues(ctx, store, filter, ready, parentID, sortBy, reverse)
if err != nil {
@ -483,6 +519,9 @@ func runListCore(cmd *cobra.Command, _ []string) error {
}
if usesProxiedServer() {
if err := rejectMaxRowsUnderProxiedServer(cmd); err != nil {
return err
}
if err := runListProxiedServer(cmd, rootCtx, in); err != nil {
return HandleError("%v", err)
}
@ -501,6 +540,12 @@ 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
@ -515,7 +560,12 @@ func runListCore(cmd *cobra.Command, _ []string) error {
}
if in.watchMode {
watchIssues(ctx, activeStore, filter, in.readyFlag, in.parentID, in.sortBy, in.reverse, in.effectiveLimit)
if err := watchIssues(ctx, activeStore, filter, in.readyFlag, in.parentID, in.sortBy, in.reverse, in.effectiveLimit); err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleError("querying issues: %v", err)
}
return nil
}
@ -528,6 +578,9 @@ func runListCore(cmd *cobra.Command, _ []string) error {
iwc, err = activeStore.SearchIssuesWithCounts(ctx, "", withFetchOneExtra(filter))
}
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleError("%v", err)
}
sortIssuesWithCounts(iwc, in.sortBy, in.reverse)
@ -558,12 +611,18 @@ func runListCore(cmd *cobra.Command, _ []string) error {
var err error
issues, err = activeStore.GetReadyWork(ctx, wf)
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleError("%v", err)
}
} else {
var err error
issues, err = activeStore.SearchIssues(ctx, "", withFetchOneExtra(filter))
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleError("%v", err)
}
}
@ -765,6 +824,9 @@ func init() {
// Ready filter: show only issues ready to be worked on (bd-ihu31)
listCmd.Flags().Bool("ready", false, "Show only ready issues (no active blockers, same semantics as bd ready)")
// Defensive row cap (be-x42v): exits 2 on overage, default disabled.
addMaxRowsFlag(listCmd)
// Note: --json flag is defined as a persistent flag in main.go, not here
rootCmd.AddCommand(listCmd)
}

View file

@ -728,6 +728,38 @@ func TestProxiedServerList(t *testing.T) {
}
})
// The proxied repository path (internal/storage/domain/db) doesn't
// thread MaxRows through the UOW pipeline, so an explicit cap must be
// rejected rather than silently going unenforced (be-x42v.4 follow-up).
t.Run("reject_max_rows_flag", func(t *testing.T) {
out := bdProxiedListFail(t, bd, p, "--max-rows", "1")
if !strings.Contains(out, "not supported in proxied-server mode") {
t.Errorf("expected --max-rows proxied-server rejection, got: %s", out)
}
})
t.Run("reject_max_rows_env", func(t *testing.T) {
fullArgs := []string{"list"}
stdout, stderr, err := bdProxiedRunBuffersWithEnv(t, bd, p.dir,
[]string{"BEADS_MAX_ROWS=1"}, fullArgs...)
if err == nil {
t.Fatalf("expected BEADS_MAX_ROWS under proxied-server to fail, but it succeeded:\nstdout:\n%s\nstderr:\n%s", stdout, stderr)
}
out := stdout + stderr
if !strings.Contains(out, "not supported in proxied-server mode") {
t.Errorf("expected BEADS_MAX_ROWS proxied-server rejection, got: %s", out)
}
})
t.Run("allow_max_rows_zero", func(t *testing.T) {
// --max-rows 0 explicitly disables the cap, so it must not trip the
// proxied-server rejection.
issues := bdProxiedListJSON(t, bd, p, "--max-rows", "0", "--all")
if len(issues) == 0 {
t.Error("--max-rows 0 --all under proxied-server unexpectedly returned no issues")
}
})
// --- O. Lightweight race: 4 workers × 5 (create + list) iterations ---
t.Run("concurrent_create_and_list", func(t *testing.T) {

View file

@ -0,0 +1,116 @@
//go:build cgo
package main
import (
"context"
"sync"
"github.com/steveyegge/beads/internal/storage"
"github.com/steveyegge/beads/internal/storage/dolt"
"github.com/steveyegge/beads/internal/types"
)
// filterCapturingStore is the shared spy used by the round-trip /
// opt-out filter gate tests:
//
// - TestExport_FilterHasZeroMaxRows (cmd/bd/export_max_rows_gate_test.go) — be-x42v.4
// - TestExportAuto_FilterHasZeroMaxRows (cmd/bd/export_auto_max_rows_gate_test.go) — be-x42v.4
// - TestMigrateIssues_FilterHasZeroMaxRows (cmd/bd/migrate_issues_max_rows_gate_test.go) — be-x42v.4
// - TestJiraSync_FilterHasZeroMaxRows (cmd/bd/jira_max_rows_gate_test.go) — be-x42v.4
//
// The same spy is intended to be reused by be-uwvs.5's parallel
// Lite=false gate tests (TestExportFilterIsAlwaysFull and friends);
// whichever bead lands first creates the spy, the other reuses it.
//
// It embeds *dolt.DoltStore (concrete) rather than the narrow
// storage.Storage interface so that cmd/bd's capability assertions
// (mustAnnot, mustDeps, mustConfig — see storage_caps.go) continue to
// resolve to the underlying Dolt-backed capabilities. Wrapping with the
// bare interface would satisfy storage.Storage at compile time but break
// the runtime AnnotationStore / DependencyQueryStore type assertions the
// commands under test rely on.
//
// SearchIssues records every filter received and then delegates to the
// embedded store so the caller sees real query results. Tests call
// LastFilter() / AllFilters() to assert on the gate invariants:
//
// - filter.MaxRows MUST be 0 on every call (env-bypass guarantee).
// - filter.MaxRowsSource MUST be "" on every call.
// - filter.Lite MUST be false on every call (be-uwvs.5 follow-up;
// round-trip integrity).
// - filter.Limit MUST be 0 on the main round-trip call (unlimited).
//
// Recording every filter (not just the last) gives multi-call paths
// like migrate-issues — which issues 2 probe + 1 candidate-scan + 1
// dedup SearchIssues calls — free coverage without re-touching the
// spy.
type filterCapturingStore struct {
*dolt.DoltStore
mu sync.Mutex
captured []types.IssueFilter
}
// newFilterCapturingStore wraps an existing *dolt.DoltStore in a spy.
// Callers reach the inner store via the embedded field if they need to
// seed data outside the spy's SearchIssues capture (e.g., via DB().Exec).
func newFilterCapturingStore(inner *dolt.DoltStore) *filterCapturingStore {
return &filterCapturingStore{DoltStore: inner}
}
// SearchIssues records the filter then delegates to the embedded Dolt
// store. The filter is captured before delegation so a panicking
// underlying call (which shouldn't happen with Dolt) still leaves the
// captured slice consistent for the test's diagnostic message.
func (s *filterCapturingStore) SearchIssues(ctx context.Context, query string, filter types.IssueFilter) ([]*types.Issue, error) {
s.mu.Lock()
s.captured = append(s.captured, filter)
s.mu.Unlock()
return s.DoltStore.SearchIssues(ctx, query, filter)
}
// LastFilter returns the most recent filter recorded by SearchIssues.
// Returns the zero-value types.IssueFilter{} (and len(s.captured)==0
// observable via Calls()) if SearchIssues was never invoked — callers
// should assert on Calls() > 0 before reading the filter.
func (s *filterCapturingStore) LastFilter() types.IssueFilter {
s.mu.Lock()
defer s.mu.Unlock()
if len(s.captured) == 0 {
return types.IssueFilter{}
}
return s.captured[len(s.captured)-1]
}
// AllFilters returns a snapshot of every filter SearchIssues received.
// The returned slice is a copy so callers can iterate without holding
// the spy lock.
func (s *filterCapturingStore) AllFilters() []types.IssueFilter {
s.mu.Lock()
defer s.mu.Unlock()
out := make([]types.IssueFilter, len(s.captured))
copy(out, s.captured)
return out
}
// Calls returns the number of times SearchIssues has been invoked on
// this spy. Tests use it to gate that the spy was actually exercised
// before asserting on the captured filter — a test that never reaches
// SearchIssues would otherwise pass vacuously.
func (s *filterCapturingStore) Calls() int {
s.mu.Lock()
defer s.mu.Unlock()
return len(s.captured)
}
// Compile-time assurances that filterCapturingStore satisfies both the
// narrow storage.Storage interface and the wider storage.DoltStorage
// interface that cmd/bd's `store` global is typed as. The embedded
// *dolt.DoltStore provides every required method; these assertions fail
// at build time if either the embed is changed or the interface adds a
// method DoltStore doesn't satisfy.
var (
_ storage.Storage = (*filterCapturingStore)(nil)
_ storage.DoltStorage = (*filterCapturingStore)(nil)
)

167
cmd/bd/max_rows.go Normal file
View file

@ -0,0 +1,167 @@
package main
import (
"errors"
"fmt"
"os"
"strconv"
"github.com/spf13/cobra"
"github.com/steveyegge/beads/internal/storage/issueops"
)
// maxRowsEnvVar names the environment variable that opts in to the defensive
// row cap. Used as both the lookup key and the source attribution string in
// error messages.
const maxRowsEnvVar = "BEADS_MAX_ROWS"
// maxRowsFlagName is the --max-rows flag name. Declared as a constant so the
// flag lookup and the source attribution string stay in sync.
const maxRowsFlagName = "max-rows"
// addMaxRowsFlag registers the --max-rows int flag on cmd. Use on every
// user-facing command that should honor the per-invocation cap override
// (designer §2.2 / §4). Help text matches the designer spec verbatim.
func addMaxRowsFlag(cmd *cobra.Command) {
cmd.Flags().Int(maxRowsFlagName, 0,
"Hard upper bound on rows fetched from storage. Returns a non-zero exit (code 2) "+
"and an error to stderr if exceeded. 0 disables (the default). Overrides "+
"BEADS_MAX_ROWS for this invocation. Useful in CI/agent rigs that want a "+
"circuit breaker against pathological queries. Not supported under "+
"--proxied-server: an explicit --max-rows or BEADS_MAX_ROWS cap errors out "+
"rather than silently going unenforced.")
}
// rejectMaxRowsUnderProxiedServer errors out when an explicit --max-rows
// flag or BEADS_MAX_ROWS env cap resolves to a nonzero cap but the command
// is about to divert to proxied-server mode. The proxied repository path
// (internal/storage/domain/db) doesn't thread MaxRows through the UOW
// pipeline, so silently ignoring the cap there would be the worst outcome
// for a safety flag — reject explicitly instead of no-oping. Call this
// after usesProxiedServer() is known true but before diverting to the
// *ProxiedServer function, on every command that calls addMaxRowsFlag.
func rejectMaxRowsUnderProxiedServer(cmd *cobra.Command) error {
maxRows, _, err := resolveMaxRows(cmd)
if err != nil {
return err
}
return rejectResolvedMaxRowsUnderProxiedServer(maxRows)
}
// rejectResolvedMaxRowsUnderProxiedServer is rejectMaxRowsUnderProxiedServer
// split out for callers that have already resolved the cap for their own
// purposes (e.g. to build a filter) and would otherwise call resolveMaxRows
// a second time — resolveMaxRowsEnvOnly emits a stderr warning on a
// malformed BEADS_MAX_ROWS every time it runs, so a second resolve doubles
// that warning under proxied mode (be-x42v.4 round-4 follow-up).
func rejectResolvedMaxRowsUnderProxiedServer(maxRows int) error {
if maxRows > 0 {
return HandleErrorRespectJSON("--max-rows / BEADS_MAX_ROWS is not supported in proxied-server mode")
}
return nil
}
// resolveMaxRows picks the effective cap from --max-rows then BEADS_MAX_ROWS.
// Returns (cap, source, err) where cap == 0 disables the cap and source is
// one of "--max-rows", "BEADS_MAX_ROWS", or "". A negative flag or bad int
// is a usage error: err is non-nil (exit code 1, main.go's
// exitCodeFromError convention — see HandleErrorRespectJSON) and the
// caller must propagate it immediately (`if err != nil { return err }`),
// mirroring how gatherListInput's callers already handle its (T, error)
// return. A non-integer env value emits a warning to stderr and is ignored
// (returns cap == 0, err == nil).
//
// Precedence (designer §2.1):
//
// 1. --max-rows N (flag changed, highest)
// 2. BEADS_MAX_ROWS=N (env var)
// 3. disabled (default; cap == 0)
//
// --max-rows 0 explicitly disables the cap even when BEADS_MAX_ROWS=N is set.
// This is intentional: ops shells with a global env can run a known-unbounded
// query without unsetting the env first.
func resolveMaxRows(cmd *cobra.Command) (int, string, error) {
if cmd != nil && cmd.Flags().Changed(maxRowsFlagName) {
n, err := cmd.Flags().GetInt(maxRowsFlagName)
if err != nil {
return 0, "", HandleErrorRespectJSON("--max-rows: %v", err)
}
if n < 0 {
return 0, "", HandleErrorRespectJSON("--max-rows must be non-negative; got %d", n)
}
return n, "--" + maxRowsFlagName, nil
}
maxRows, source := resolveMaxRowsEnvOnly()
return maxRows, source, nil
}
// resolveMaxRowsEnvOnly reads BEADS_MAX_ROWS without consulting any flag.
// Used by the doctor family of commands (designer §4): bd doctor, bd lint,
// bd doctor-conventions, bd doctor-pollution. These are internal sweeps
// where the operator may want a guardrail via env var but no per-invocation
// flag is needed.
//
// On a bad env value, emits a warning to stderr and returns (0, ""). The
// command proceeds with the cap disabled rather than aborting — failing
// closed here would break automation that has a global BEADS_MAX_ROWS set
// but accidentally got a typo.
func resolveMaxRowsEnvOnly() (int, string) {
raw, ok := os.LookupEnv(maxRowsEnvVar)
if !ok || raw == "" {
return 0, ""
}
n, err := strconv.Atoi(raw)
if err != nil || n < 0 {
fmt.Fprintf(os.Stderr,
"Warning: %s=%q is not a non-negative integer; ignoring.\n",
maxRowsEnvVar, raw)
return 0, ""
}
return n, maxRowsEnvVar
}
// handleMaxRowsError checks whether err is a *issueops.ErrTooManyRows from
// the storage layer and, if so, emits the two-line stderr error message
// (designer §2.3) and returns an exit-coded error (code 2, main.go's
// exitCodeFromError convention — see &exitError{Code: 2} elsewhere in this
// package, e.g. list_input.go's skip-labels-conflict check). Returns nil
// when err is nil or any other type, letting the caller continue its
// existing error path (typically `return HandleError(...)`).
//
// Every caller must check the return value and propagate it immediately:
//
// if capErr := handleMaxRowsError(err); capErr != nil {
// return capErr
// }
// return HandleError("%v", err)
//
// This used to call os.Exit(2) directly, which — since it runs from deep
// inside RunE, sometimes several calls below it — bypassed both the
// calling command's own `defer func() { metrics.CloseEventAndAdd(evt) }()`
// and main()'s post-ExecuteC metrics.CloseAndFlush(), stranding queued
// metrics. Returning through RunE like every other command error lets both
// run before process exit.
//
// The error is intentionally rendered without ANSI color and without
// touching stdout: a half-rendered JSON array on stdout would cause `jq`
// downstream to fail in a way unrelated to the cap, hiding the real cause.
func handleMaxRowsError(err error) error {
if err == nil {
return nil
}
var capErr *issueops.ErrTooManyRows
if !errors.As(err, &capErr) {
return nil
}
source := capErr.Source
if source == "" {
source = maxRowsEnvVar
}
fmt.Fprintf(os.Stderr, "Error: too many rows: %d found, %s=%d exceeded.\n",
capErr.Found, source, capErr.Cap)
fmt.Fprintln(os.Stderr,
" Refine the query (add filters, set --limit), or raise the cap with")
fmt.Fprintln(os.Stderr,
" --max-rows N or BEADS_MAX_ROWS=N.")
return &exitError{Code: 2}
}

764
cmd/bd/max_rows_test.go Normal file
View file

@ -0,0 +1,764 @@
//go:build cgo
// be-u8z9: CLI-layer behavioral tests for BEADS_MAX_ROWS / --max-rows on the
// command paths beyond `bd list`. Each subtest:
// - inits a fresh rig (own DB so the row counts are exact)
// - exercises the command via exec.Command(bd, ...)
// - asserts the process exited with code 2 (cap exceeded) and that stderr
// names the source ("--max-rows=N" or "BEADS_MAX_ROWS=N").
//
// The doctor-family commands (lint, doctor-conventions, doctor-pollution)
// are env-only by design (designer §4); they do NOT register --max-rows
// as a flag. A separate subtest asserts cobra rejects the flag.
//
// Gating matches the other embedded-dolt CLI tests: requires
// BEADS_TEST_EMBEDDED_DOLT=1 to opt in.
package main
import (
"fmt"
"os"
"os/exec"
"strings"
"testing"
"github.com/steveyegge/beads/internal/types"
)
// bdRunRaw runs bd with the given args and env extras (appended to bdEnv(dir)).
// Returns combined stdout+stderr and the process exit code. Unlike the other
// helpers in this package it does not call t.Fatal on non-zero exits — that's
// the success case for the max-rows tests.
func bdRunRaw(t *testing.T, bd, dir string, envExtras []string, args ...string) (string, int) {
t.Helper()
cmd := exec.Command(bd, args...)
cmd.Dir = dir
env := bdEnv(dir)
env = append(env, envExtras...)
cmd.Env = env
out, err := cmd.CombinedOutput()
if err == nil {
return string(out), 0
}
if exitErr, ok := err.(*exec.ExitError); ok {
return string(out), exitErr.ExitCode()
}
t.Fatalf("bd %s unexpected non-exit error: %v\n%s", strings.Join(args, " "), err, out)
return string(out), -1
}
// seedReadyIssues creates n top-level (no-dep, no-blocker) issues that all
// appear in `bd ready`. Useful for tests that need exactly n ready rows.
func seedReadyIssues(t *testing.T, bd, dir string, n int) []string {
t.Helper()
ids := make([]string, n)
for i := 0; i < n; i++ {
iss := bdCreate(t, bd, dir, fmt.Sprintf("max-rows seed %d", i), "--type", "task")
ids[i] = iss.ID
}
return ids
}
// TestEmbeddedMaxRowsNonListPaths covers the non-list CLI paths wired up in
// be-x42v.2: ready, dep tree, find-duplicates, graph --all, plus the env-only
// doctor family (lint, doctor --check=conventions, doctor --check=pollution),
// and config show emission of BEADS_MAX_ROWS.
func TestEmbeddedMaxRowsNonListPaths(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Parallel()
bd := buildEmbeddedBD(t)
// ----------- bd ready -----------
t.Run("ReadyMaxRows_FlagOverCap_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrrdf")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, nil, "ready", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
})
t.Run("ReadyMaxRows_EnvOverCap_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrrde")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=3"}, "ready")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "BEADS_MAX_ROWS=3") {
t.Errorf("stderr missing source BEADS_MAX_ROWS=3:\n%s", out)
}
})
// `bd ready --json` and `bd list --ready --json` route through
// GetReadyWorkWithCountsInTx, a separate query path from the plain
// `bd ready` above (GetReadyWorkInTx). Mirrors
// TestEmbeddedMaxRowsList/Flag_OverCap's --json coverage for `bd list`.
t.Run("ReadyMaxRowsJSON_FlagOverCap_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrrjf")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, nil, "ready", "--json", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
if idx := strings.Index(out, "Error: too many rows"); idx >= 0 {
if strings.Contains(out[:idx], "[") {
t.Errorf("stdout JSON output leaked before error message:\nfull=%s", out)
}
}
})
t.Run("ListReadyMaxRowsJSON_FlagOverCap_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrrjl")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, nil, "list", "--ready", "--json", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
})
// be-x42v.4 follow-up (review SHOULD-FIX 8): confirms the cap still
// fires end-to-end for --include-ephemeral after propagating MaxRows
// into getReadyWispsInTx's wisp query (internal/storage/issueops/
// ready_work.go) — that change bounds the query itself but must not
// change whether the post-merge cap check in GetReadyWorkInTx trips.
t.Run("ReadyIncludeEphemeralMaxRows_FlagOverCap_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrre")
for i := 0; i < 6; i++ {
bdCreate(t, bd, dir, fmt.Sprintf("Ephemeral ready %d", i), "--type", "task", "--ephemeral")
}
out, code := bdRunRaw(t, bd, dir, nil, "ready", "--include-ephemeral", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
})
// be-x42v.4 round-3 follow-up: GetReadyWorkWithCountsInTx (the `--json`
// path) independently bounds each of the issues and wisps queries by
// EffectiveSearchLimit(Limit, MaxRows), so with --include-ephemeral the
// PRE-TRIM merge of two tables can hold up to ~2x that per-table bound
// even though the caller's own --limit already keeps the DELIVERED page
// well within the cap. limit=2, cap=3, 2 ready rows in each table: each
// table's query returns 2 (2<=limit, no overage sniff at the per-table
// level — EffectiveSearchLimit(2,3)=2), the pre-trim merge is 4>cap=3,
// but the page actually handed back to the caller is trimmed to 2<=cap.
// Must exit 0, not trip the cap on the untrimmed merge.
t.Run("ReadyIncludeEphemeralMaxRowsJSON_MergedUnderLimit_NoError", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrrm")
for i := 0; i < 2; i++ {
bdCreate(t, bd, dir, fmt.Sprintf("Plain ready %d", i), "--type", "task")
}
for i := 0; i < 2; i++ {
bdCreate(t, bd, dir, fmt.Sprintf("Ephemeral ready %d", i), "--type", "task", "--ephemeral")
}
out, code := bdRunRaw(t, bd, dir, nil, "ready", "--json", "--include-ephemeral",
"--limit", "2", "--max-rows", "3")
if code != 0 {
t.Fatalf("expected exit 0 (delivered page under cap despite pre-trim merge overage), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("delivered-page-under-cap should not emit cap error:\n%s", out)
}
})
// ----------- bd dep tree -----------
t.Run("DepTreeMaxRows_TreeNodes_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrdt")
// All tasks: default "blocks" dep type rejects epic→task, but task→task
// is fine and produces a tree with the same shape for cap purposes.
root := bdCreate(t, bd, dir, "Tree root", "--type", "task")
// Add 5 children so the dep tree has 6 nodes total (root + 5).
for i := 0; i < 5; i++ {
child := bdCreate(t, bd, dir, fmt.Sprintf("Tree dep %d", i), "--type", "task")
// `bd dep add A B` makes A depend on B (default dep type is "blocks").
bdDepAdd(t, bd, dir, root.ID, child.ID)
}
// Sanity: tree of size 6, cap of 2 → must exit 2 with source attribution.
out, code := bdRunRaw(t, bd, dir, nil, "dep", "tree", root.ID, "--max-rows", "2")
if code != 2 {
t.Fatalf("expected exit 2 (tree size > cap), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=2") {
t.Errorf("stderr missing source --max-rows=2:\n%s", out)
}
})
// ----------- bd find-duplicates -----------
t.Run("FindDuplicatesMaxRows_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrfd")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, nil, "find-duplicates", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
})
// ----------- bd graph --all -----------
t.Run("GraphAllMaxRows_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrgr")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, nil, "graph", "--all", "--max-rows", "3")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "--max-rows=3") {
t.Errorf("stderr missing source --max-rows=3:\n%s", out)
}
})
// be-x42v.4 follow-up (review SHOULD-FIX 7): `bd graph <issue>` without
// --all never resolved the cap at all before the fix — loadGraphSubgraph
// is a BFS over per-ID GetDependents/GetDependencies lookups with no
// IssueFilter to thread MaxRows through, so this checks the final
// connected-component node count post-hoc, mirroring dep tree.
t.Run("GraphSingleIssueMaxRows_NodeCount_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrgs")
root := bdCreate(t, bd, dir, "Graph root", "--type", "task")
for i := 0; i < 5; i++ {
child := bdCreate(t, bd, dir, fmt.Sprintf("Graph dep %d", i), "--type", "task")
bdDepAdd(t, bd, dir, root.ID, child.ID)
}
// Connected component of size 6 (root + 5), cap of 2 → exit 2.
out, code := bdRunRaw(t, bd, dir, nil, "graph", root.ID, "--max-rows", "2")
if code != 2 {
t.Fatalf("expected exit 2 (subgraph size > cap), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("stderr missing 'too many rows':\n%s", out)
}
if !strings.Contains(out, "--max-rows=2") {
t.Errorf("stderr missing source --max-rows=2:\n%s", out)
}
})
t.Run("GraphSingleIssueMaxRows_UnderCap_NoError", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrgu")
root := bdCreate(t, bd, dir, "Graph root under cap", "--type", "task")
out, code := bdRunRaw(t, bd, dir, nil, "graph", root.ID, "--max-rows", "5")
if code != 0 {
t.Fatalf("expected exit 0 (single-node subgraph under cap), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("under-cap single-issue graph should not emit cap error:\n%s", out)
}
})
// ----------- bd lint (env-only) -----------
t.Run("LintMaxRows_EnvOnly_Exits2", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrln")
seedReadyIssues(t, bd, dir, 6)
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=3"}, "lint")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded via env), got %d\n%s", code, out)
}
if !strings.Contains(out, "BEADS_MAX_ROWS=3") {
t.Errorf("stderr missing source BEADS_MAX_ROWS=3:\n%s", out)
}
})
t.Run("LintMaxRows_NoFlagAccepted", func(t *testing.T) {
// Designer §4: doctor family is env-opt-in only. The --max-rows
// flag must NOT be registered on `bd lint`; cobra should reject
// it as unknown.
dir, _, _ := bdInit(t, bd, "--prefix", "mrlnf")
out, code := bdRunRaw(t, bd, dir, nil, "lint", "--max-rows", "1")
if code == 0 {
t.Fatalf("expected non-zero exit (cobra rejects unknown flag), got 0\n%s", out)
}
if !strings.Contains(out, "unknown flag") {
t.Errorf("stderr missing 'unknown flag' rejection:\n%s", out)
}
// Defense against false positives: if `--max-rows` is wired on lint
// by mistake, this assertion would not trip — but the unknown-flag
// check above already covers it.
})
// ----------- bd doctor --check=conventions (env-only) -----------
//
// bd doctor is hard-gated to server mode (doctor.go:188 prints "not yet
// supported in embedded mode" and exits 0 before reaching the check
// dispatch). The embedded-Dolt test rig used here cannot exercise those
// code paths. The cap logic itself runs through the shared SearchIssues +
// EnforceMaxRowsCap path already covered by:
// - TestEnforceMaxRowsCap_* (internal/storage/issueops/search_test.go)
// - TestGetReadyWork_MaxRowsSuite (cmd/bd/ready_max_rows_test.go)
// - be-x42v.3 storage parity tests (bd list/search backend matrix)
// What's _not_ covered without server mode is the env-only resolver
// (resolveMaxRowsEnvOnly) on these specific commands. doctor_conventions.go
// and doctor_pollution.go both call it and pipe through handleMaxRowsError
// identically to lint.go, which IS covered above by LintMaxRows_EnvOnly_Exits2.
// A server-mode follow-up should add behavioral coverage here.
t.Run("ConventionsMaxRows_EnvOnly_Exits2", func(t *testing.T) {
t.Skip("bd doctor requires server mode (doctor.go:188); server-mode parity covered by separate validator bead")
})
t.Run("PollutionMaxRows_EnvOnly_Exits2", func(t *testing.T) {
t.Skip("bd doctor requires server mode (doctor.go:188); server-mode parity covered by separate validator bead")
})
// ----------- bd config show -----------
t.Run("ConfigShow_ListsBeadsMaxRows", func(t *testing.T) {
dir, _, _ := bdInit(t, bd, "--prefix", "mrcs")
// When BEADS_MAX_ROWS is set in the environment, `bd config show`
// must surface it in the standalone-env entries (config_show.go
// collectStandaloneEnvEntries).
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=42"}, "config", "show")
if code != 0 {
t.Fatalf("expected exit 0 from `bd config show`, got %d\n%s", code, out)
}
if !strings.Contains(out, "BEADS_MAX_ROWS") {
t.Errorf("expected `bd config show` to list BEADS_MAX_ROWS in output:\n%s", out)
}
if !strings.Contains(out, "42") {
t.Errorf("expected `bd config show` to display the value 42:\n%s", out)
}
// When the env var is unset, the entry must be absent (designer §4:
// opt-in only; default-disabled).
out2, code2 := bdRunRaw(t, bd, dir, nil, "config", "show")
if code2 != 0 {
t.Fatalf("expected exit 0 from `bd config show` (unset), got %d\n%s", code2, out2)
}
if strings.Contains(out2, "BEADS_MAX_ROWS") {
t.Errorf("expected BEADS_MAX_ROWS to be absent when env is unset:\n%s", out2)
}
})
}
// countListIDs returns the number of issue IDs of the form "<prefix>-<n>"
// observed in the combined `bd list` output. Used to verify that --limit
// actually clipped the result set without depending on JSON parsing of the
// pretty-printed array (which spans many lines).
func countListIDs(out, prefix string) int {
// Each list row prints the issue ID once; counting prefix occurrences in
// raw stdout is a robust enough check for our small fixtures.
return strings.Count(out, prefix+"-")
}
// TestEmbeddedMaxRowsList covers the 10 designer §6.1 behavioral scenarios
// for `bd list`. Builder bead: be-x42v.2 (CLI wiring). All subtests share a
// single rig of 21 open task issues — the dataset size from the designer's
// fixture.
func TestEmbeddedMaxRowsList(t *testing.T) {
if os.Getenv("BEADS_TEST_EMBEDDED_DOLT") != "1" {
t.Skip("set BEADS_TEST_EMBEDDED_DOLT=1 to run embedded dolt integration tests")
}
t.Parallel()
bd := buildEmbeddedBD(t)
dir, _, _ := bdInit(t, bd, "--prefix", "mrl")
const totalRows = 21
for i := 0; i < totalRows; i++ {
bdCreate(t, bd, dir, fmt.Sprintf("List max-rows %d", i), "--type", "task")
}
t.Run("Disabled_NoEnv", func(t *testing.T) {
// Baseline: with no flag and no env var, `bd list` returns all rows.
out, code := bdRunRaw(t, bd, dir, nil, "list")
if code != 0 {
t.Fatalf("expected exit 0 (no cap), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("baseline `bd list` should not emit cap error:\n%s", out)
}
if got := countListIDs(out, "mrl"); got < totalRows {
t.Errorf("expected at least %d rows in output, got %d", totalRows, got)
}
})
t.Run("Flag_UnderCap", func(t *testing.T) {
// 21 rows under cap=100: success.
out, code := bdRunRaw(t, bd, dir, nil, "list", "--max-rows", "100")
if code != 0 {
t.Fatalf("expected exit 0 (under cap), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("under-cap `bd list` should not emit cap error:\n%s", out)
}
})
t.Run("Flag_OverCap", func(t *testing.T) {
// 21 rows over cap=5: exit 2, stderr includes --max-rows=5, stdout
// empty (designer §2.3: stdout is suppressed so `jq` downstream
// doesn't trip on partial JSON).
out, code := bdRunRaw(t, bd, dir, nil, "list", "--json", "--max-rows", "5")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("expected 'too many rows' in stderr:\n%s", out)
}
if !strings.Contains(out, "--max-rows=5") {
t.Errorf("expected source `--max-rows=5` in stderr:\n%s", out)
}
// stdout-emptiness check: there should be no JSON `[` array opener
// in the merged output before the error. Cap-exceeded must not emit
// a partial array.
if idx := strings.Index(out, "Error: too many rows"); idx >= 0 {
before := out[:idx]
if strings.Contains(before, "[") {
t.Errorf("stdout JSON output leaked before error message:\nbefore=%q\nfull=%s", before, out)
}
}
})
t.Run("Env_OverCap", func(t *testing.T) {
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=5"}, "list")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded via env), got %d\n%s", code, out)
}
if !strings.Contains(out, "BEADS_MAX_ROWS=5") {
t.Errorf("expected source `BEADS_MAX_ROWS=5` in stderr:\n%s", out)
}
})
t.Run("Flag_OverridesEnv", func(t *testing.T) {
// env says cap=5, flag says cap=100 — flag wins, expect success.
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=5"},
"list", "--max-rows", "100")
if code != 0 {
t.Fatalf("expected exit 0 (flag overrides env), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("flag-override should not emit cap error:\n%s", out)
}
})
t.Run("Flag_Zero_OverridesEnv", func(t *testing.T) {
// Explicit `--max-rows 0` disables the cap even when env is set
// (designer §2.1: ops shells with a global env can run a known-
// unbounded query without unsetting).
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=5"},
"list", "--max-rows", "0")
if code != 0 {
t.Fatalf("expected exit 0 (--max-rows 0 disables), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("explicit `--max-rows 0` should disable the cap:\n%s", out)
}
})
t.Run("BadEnv_LogsAndIgnores", func(t *testing.T) {
// env=banana → warning to stderr, normal output, exit 0
// (designer §2.1: fail-open on bad env so a typo in a global shell
// doesn't break automation).
out, code := bdRunRaw(t, bd, dir, []string{"BEADS_MAX_ROWS=banana"}, "list")
if code != 0 {
t.Fatalf("expected exit 0 (bad env ignored), got %d\n%s", code, out)
}
// max_rows.go:79 emits a "Warning: BEADS_MAX_ROWS=\"banana\" is not
// a non-negative integer; ignoring." line.
if !strings.Contains(out, "Warning") || !strings.Contains(out, "BEADS_MAX_ROWS") {
t.Errorf("expected warning about bad env in stderr:\n%s", out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("bad env should not trigger cap error:\n%s", out)
}
})
t.Run("Negative_FlagRejected", func(t *testing.T) {
// max_rows.go:55 calls FatalError on negative — exit 1 with message.
out, code := bdRunRaw(t, bd, dir, nil, "list", "--max-rows", "-1")
if code != 1 {
t.Fatalf("expected exit 1 (usage error), got %d\n%s", code, out)
}
if !strings.Contains(out, "must be non-negative") {
t.Errorf("expected 'must be non-negative' in stderr:\n%s", out)
}
})
t.Run("LimitSet_CapTighter", func(t *testing.T) {
// limit=100, cap=5: 21 rows are scanned (LIMIT cap+1=6 sniffs
// overage), cap fires, exit 2. The --limit flag does not protect
// callers who set a generous limit but also opt into the cap.
out, code := bdRunRaw(t, bd, dir, nil, "list",
"--limit", "100", "--max-rows", "5")
if code != 2 {
t.Fatalf("expected exit 2 (cap tighter than limit), got %d\n%s", code, out)
}
if !strings.Contains(out, "--max-rows=5") {
t.Errorf("expected source `--max-rows=5` in stderr:\n%s", out)
}
})
t.Run("LimitSet_CapLooser", func(t *testing.T) {
// limit=5, cap=100: EffectiveSearchLimit returns 5 (limit wins when
// under cap), no overage detection, 5 rows returned, exit 0.
out, code := bdRunRaw(t, bd, dir, nil, "list",
"--limit", "5", "--max-rows", "100")
if code != 0 {
t.Fatalf("expected exit 0 (limit under cap), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("limit-under-cap should not emit cap error:\n%s", out)
}
if got := countListIDs(out, "mrl"); got != 5 {
t.Errorf("expected exactly 5 issue IDs in output, got %d:\n%s", got, out)
}
})
// be-x42v.4 follow-up (review MUST-FIX 4, revised round-3): --limit N
// --max-rows N with more than N matches must truncate to N and exit 0
// (the standard >N-matches truncation semantics), not error.
//
// Round-2 fix (regressed, since replaced): unconditionally skipped the
// withFetchOneExtra probe-row bump when Limit>=MaxRows. That avoided
// the false cap error but also stopped fetching the extra row entirely,
// so len(results) could never exceed effectiveLimit and the GH#3212
// truncation notice silently stopped firing for this case — a partial
// result started presenting as complete.
//
// Round-3 fix: still fetch the probe row (Limit bumps to N+1 as
// normal), but when Limit==MaxRows exactly, bump MaxRows to N+1 too, in
// lockstep, so EnforceMaxRowsCap's comparison excludes the probe row
// from the cap check while the CLI's own len(results)>effectiveLimit
// truncation detection still sees it. See withFetchOneExtra's doc
// comment in list.go for why this can't false-negative a real
// violation. Covered directly (bump values, not exit behavior) by
// TestWithFetchOneExtra_LimitEqualsCap_BumpsBothForTruncationProbe
// below, since printTruncationHint's text is gated on
// ui.IsStderrTerminal() and unconditionally suppressed for this
// subprocess harness's piped stderr (see list_embedded_test.go's
// limit_truncation_hint subtest) — these end-to-end subtests can only
// assert the absence of the false cap error and the delivered count.
t.Run("LimitEqualsCap_TruncatesNotErrors", func(t *testing.T) {
out, code := bdRunRaw(t, bd, dir, nil, "list",
"--limit", "5", "--max-rows", "5")
if code != 0 {
t.Fatalf("expected exit 0 (limit==cap truncates, does not error), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("limit==cap should not emit cap error:\n%s", out)
}
if got := countListIDs(out, "mrl"); got != 5 {
t.Errorf("expected exactly 5 issue IDs in output, got %d:\n%s", got, out)
}
})
t.Run("LimitEqualsCap_JSON_TruncatesNotErrors", func(t *testing.T) {
out, code := bdRunRaw(t, bd, dir, nil, "list", "--json",
"--limit", "5", "--max-rows", "5")
if code != 0 {
t.Fatalf("expected exit 0 (limit==cap truncates under --json), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("limit==cap under --json should not emit cap error:\n%s", out)
}
})
// be-x42v.4 round-4 follow-up: the round-3 fix to
// finishReadyWorkWithCounts (trim to Limit before EnforceMaxRowsCap)
// wasn't mirrored onto the sibling bd list search paths
// (searchInTx in search.go, finishSearchIssuesWithCounts in
// search_counts.go), which still capped the pre-trim merged
// issues+wisps set. `--include-infra` disables the default SkipWisps
// escape hatch, so the wisps merge actually runs. limit=2, cap=5, 3
// durable + 3 wisp issues: each leg's query is independently bounded
// by EffectiveSearchLimit, so the merge can produce up to 6 rows
// pre-trim (>cap=5) even though the delivered page (trimmed to 2) is
// well within the cap. Covers both bd list output modes (opus's live
// repro found both non-JSON and --json tripping the false cap error).
t.Run("IncludeInfraMergedUnderLimit_NoError", func(t *testing.T) {
mDir, _, _ := bdInit(t, bd, "--prefix", "mrii")
for i := 0; i < 3; i++ {
bdCreate(t, bd, mDir, fmt.Sprintf("Durable infra %d", i), "--type", "task")
}
for i := 0; i < 3; i++ {
bdCreate(t, bd, mDir, fmt.Sprintf("Wisp infra %d", i), "--type", "task", "--ephemeral")
}
out, code := bdRunRaw(t, bd, mDir, nil, "list", "--include-infra",
"--limit", "2", "--max-rows", "5")
if code != 0 {
t.Fatalf("expected exit 0 (delivered page under cap despite pre-trim merge overage), got %d\n%s", code, out)
}
if strings.Contains(out, "too many rows") {
t.Errorf("delivered-page-under-cap should not emit cap error:\n%s", out)
}
outJSON, codeJSON := bdRunRaw(t, bd, mDir, nil, "list", "--include-infra", "--json",
"--limit", "2", "--max-rows", "5")
if codeJSON != 0 {
t.Fatalf("expected exit 0 under --json (delivered page under cap despite pre-trim merge overage), got %d\n%s", codeJSON, outJSON)
}
if strings.Contains(outJSON, "too many rows") {
t.Errorf("delivered-page-under-cap under --json should not emit cap error:\n%s", outJSON)
}
})
// be-x42v.4 round-5 follow-up: searchInTx's merge branch concatenates
// two independently ORDER BY'd legs (`append(filtered, wispResults...)`)
// and round-4's trimToSearchLimit then sliced that unsorted
// concatenation — with Limit small enough that durable rows alone fill
// it, a higher-ranked wisp was silently dropped from the page even
// though the CLI's pre-round-4 behavior (return the full merged set,
// let the caller sort-then-trim) surfaced it correctly. Default sort is
// priority ASC: 3 durable issues at P2, one wisp at P0 (highest rank)
// — with --limit 1 the P0 wisp must be the sole delivered row, not one
// of the P2 durable rows the unsorted concatenation happened to put
// first. Must fail against 77227aa67.
t.Run("IncludeInfraMerged_WispOutranksDurable_InDeliveredPage", func(t *testing.T) {
mDir, _, _ := bdInit(t, bd, "--prefix", "mrwo")
for i := 0; i < 3; i++ {
bdCreate(t, bd, mDir, fmt.Sprintf("Durable p2 %d", i), "--type", "task", "--priority", "2")
}
wisp := bdCreate(t, bd, mDir, "Wisp p0 outranks", "--type", "task", "--priority", "0", "--ephemeral")
out, code := bdRunRaw(t, bd, mDir, nil, "list", "--include-infra", "--limit", "1")
if code != 0 {
t.Fatalf("expected exit 0, got %d\n%s", code, out)
}
if !strings.Contains(out, wisp.ID) {
t.Errorf("P0 wisp %s must be the sole row in a --limit 1 page (default sort is priority ASC), got:\n%s", wisp.ID, out)
}
outJSON, codeJSON := bdRunRaw(t, bd, mDir, nil, "list", "--include-infra", "--json", "--limit", "1")
if codeJSON != 0 {
t.Fatalf("expected exit 0 under --json, got %d\n%s", codeJSON, outJSON)
}
if !strings.Contains(outJSON, wisp.ID) {
t.Errorf("P0 wisp %s must be the sole row in a --limit 1 --json page, got:\n%s", wisp.ID, outJSON)
}
})
// be-x42v.4 follow-up (review MUST-FIX 5): the initial query under
// `bd list --watch` must surface a cap violation with exit 2, same as
// non-watch `bd list`. Before the fix, watchIssues logged the error to
// stderr itself and returned void, so the process always exited 0 —
// the failure never reached RunE/handleMaxRowsError. This subprocess
// exercises only the initial-query failure path (returns before
// entering the polling loop), so it terminates without needing Ctrl+C.
t.Run("Watch_FlagOverCap_Exits2", func(t *testing.T) {
out, code := bdRunRaw(t, bd, dir, nil, "list", "--watch", "--max-rows", "5")
if code != 2 {
t.Fatalf("expected exit 2 (cap exceeded under --watch), got %d\n%s", code, out)
}
if !strings.Contains(out, "too many rows") {
t.Errorf("expected 'too many rows' in stderr:\n%s", out)
}
if !strings.Contains(out, "--max-rows=5") {
t.Errorf("expected source `--max-rows=5` in stderr:\n%s", out)
}
})
}
// TestWithFetchOneExtra_LimitEqualsCap_BumpsBothForTruncationProbe verifies
// the exact bump mechanism withFetchOneExtra uses to reconcile the
// >N-matches truncation probe (GH#3212) with a MaxRows cap equal to the
// user's --limit (be-x42v.4 round-3 follow-up).
//
// The end-to-end LimitEqualsCap_TruncatesNotErrors subprocess test in
// TestEmbeddedMaxRowsList can only assert the *absence* of the false cap
// error and the trimmed row count — it can't observe the truncation
// *notice* text, which printTruncationHint gates on ui.IsStderrTerminal()
// and is unconditionally suppressed for a subprocess's piped stderr (see
// list_embedded_test.go's limit_truncation_hint subtest, which documents
// the same TTY constraint). This unit test instead asserts the underlying
// signal directly: with Limit==MaxRows, both must bump by one so the query
// still over-fetches by one row (restoring len(results) > effectiveLimit
// detection) while EnforceMaxRowsCap doesn't trip on that extra row.
func TestWithFetchOneExtra_LimitEqualsCap_BumpsBothForTruncationProbe(t *testing.T) {
got := withFetchOneExtra(types.IssueFilter{Limit: 5, MaxRows: 5, MaxRowsSource: "--max-rows"})
if got.Limit != 6 {
t.Errorf("Limit == MaxRows: Limit = %d, want 6 (bumped so the query still fetches the truncation-detection probe row)", got.Limit)
}
if got.MaxRows != 6 {
t.Errorf("Limit == MaxRows: MaxRows = %d, want 6 (bumped in lockstep so the probe row alone doesn't trip EnforceMaxRowsCap)", got.MaxRows)
}
if got.MaxRowsSource != "--max-rows" {
t.Errorf("MaxRowsSource must be preserved unchanged, got %q", got.MaxRowsSource)
}
}
// TestWithFetchOneExtra_LimitOverCap_OnlyBumpsLimit covers the tighter-cap
// case (--limit 100 --max-rows 5, LimitSet_CapTighter): MaxRows must NOT
// bump, or a genuine cap violation would report the wrong Cap value (N+1
// instead of the user's true --max-rows=N) in the error message.
func TestWithFetchOneExtra_LimitOverCap_OnlyBumpsLimit(t *testing.T) {
got := withFetchOneExtra(types.IssueFilter{Limit: 100, MaxRows: 5})
if got.Limit != 101 {
t.Errorf("Limit = %d, want 101", got.Limit)
}
if got.MaxRows != 5 {
t.Errorf("MaxRows must stay unbumped so a real cap violation reports the true cap; got %d, want 5", got.MaxRows)
}
}
// TestWithFetchOneExtra_LimitUnderCap_OnlyBumpsLimit covers the
// looser-cap case (--limit 5 --max-rows 100, LimitSet_CapLooser): the
// probe-row bump alone never crosses EffectiveSearchLimit's `limit >
// maxRows` branch here, so no MaxRows adjustment is needed.
func TestWithFetchOneExtra_LimitUnderCap_OnlyBumpsLimit(t *testing.T) {
got := withFetchOneExtra(types.IssueFilter{Limit: 5, MaxRows: 100})
if got.Limit != 6 {
t.Errorf("Limit = %d, want 6", got.Limit)
}
if got.MaxRows != 100 {
t.Errorf("MaxRows must stay unbumped, got %d, want 100", got.MaxRows)
}
}
// TestWithFetchOneExtra_NoLimit_Unaffected covers the unlimited case
// (Limit == 0): withFetchOneExtra is a no-op regardless of MaxRows.
func TestWithFetchOneExtra_NoLimit_Unaffected(t *testing.T) {
got := withFetchOneExtra(types.IssueFilter{Limit: 0, MaxRows: 5})
if got.Limit != 0 || got.MaxRows != 5 {
t.Errorf("unlimited Limit must pass through unchanged, got Limit=%d MaxRows=%d", got.Limit, got.MaxRows)
}
}

View file

@ -203,10 +203,14 @@ func executeMigrateIssues(ctx context.Context, p migrateIssuesParams) error {
}
func validateRepos(ctx context.Context, s storage.DoltStorage, from, to string, strict bool) error {
// migrate-issues is a round-trip path — opt out of BEADS_MAX_ROWS
// (designer §4.1) so a misconfigured env doesn't abort migration.
// Check if source repo has any issues
fromIssues, err := s.SearchIssues(ctx, "", types.IssueFilter{
SourceRepo: &from,
Limit: 1,
SourceRepo: &from,
Limit: 1,
MaxRows: 0,
MaxRowsSource: "",
})
if err != nil {
return fmt.Errorf("failed to check source repository: %w", err)
@ -224,8 +228,10 @@ func validateRepos(ctx context.Context, s storage.DoltStorage, from, to string,
// Check if destination repo exists (just a warning)
toIssues, err := s.SearchIssues(ctx, "", types.IssueFilter{
SourceRepo: &to,
Limit: 1,
SourceRepo: &to,
Limit: 1,
MaxRows: 0,
MaxRowsSource: "",
})
if err != nil {
return fmt.Errorf("failed to check destination repository: %w", err)
@ -239,9 +245,12 @@ func validateRepos(ctx context.Context, s storage.DoltStorage, from, to string,
}
func findCandidateIssues(ctx context.Context, s storage.DoltStorage, p migrateIssuesParams) ([]string, error) {
// Build filter from params
// Build filter from params. Opt out of BEADS_MAX_ROWS (designer §4.1) —
// migrate-issues is round-trip and must enumerate every candidate.
filter := types.IssueFilter{
SourceRepo: &p.from,
SourceRepo: &p.from,
MaxRows: 0,
MaxRowsSource: "",
}
// Filter by status
@ -485,7 +494,9 @@ func checkOrphanedDependencies(ctx context.Context, s storage.DoltStorage) ([]st
}
existingIssues, err := s.SearchIssues(ctx, "", types.IssueFilter{
IDs: idList,
IDs: idList,
MaxRows: 0,
MaxRowsSource: "",
})
if err != nil {
return nil, fmt.Errorf("failed to check issue existence: %w", err)

View file

@ -0,0 +1,109 @@
//go:build cgo
package main
import (
"context"
"os"
"path/filepath"
"testing"
"github.com/steveyegge/beads/internal/testutil"
)
// TestMigrateIssues_FilterHasZeroMaxRows is the be-x42v.4 opt-out gate
// for `bd migrate-issues`. Asserts that the migration's candidate-find
// filter — built in findCandidateIssues at cmd/bd/migrate_issues.go:269
// — never carries MaxRows>0 or a non-empty MaxRowsSource. A
// BEADS_MAX_ROWS-tripped migration would leave the source and destination
// repos in inconsistent states; the cap must be hard-opt-out here.
//
// Why findCandidateIssues and not executeMigrateIssues end-to-end:
//
// - executeMigrateIssues also calls validateRepos (lines 233/254),
// which intentionally uses Limit=1 for existence probing. Those
// calls also opt out of the cap (MaxRows=0) and would be covered
// by AllFilters() — but the candidate-find call is the principal
// round-trip path, and isolating it from the migration plumbing
// (orphan checks, plan display, confirmation gate) keeps this gate
// focused on the property under test.
// - findCandidateIssues IS the round-trip candidate scan. Its filter
// has MaxRows=0 (no cap, by design) and a SourceRepo discriminator.
//
// If a future refactor moves the candidate-find SearchIssues call into
// a different function, the gate's import line will fail to compile —
// that's a load-bearing signal to re-target the test.
//
// Build tags: cgo (matches existing cgo cmd/bd tests).
func TestMigrateIssues_FilterHasZeroMaxRows(t *testing.T) {
if testDoltServerPort == 0 {
t.Skip("Dolt test server not available")
}
if testutil.DoltContainerCrashed() {
t.Skipf("Dolt test server crashed: %v", testutil.DoltContainerCrashError())
}
ensureTestMode(t)
saved := saveAndRestoreGlobals(t)
_ = saved
tmpDir := t.TempDir()
beadsDir := filepath.Join(tmpDir, ".beads")
if err := os.MkdirAll(beadsDir, 0755); err != nil {
t.Fatal(err)
}
origWd, _ := os.Getwd()
if err := os.Chdir(tmpDir); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = os.Chdir(origWd) })
dbName := uniqueTestDBName(t)
testDBPath := filepath.Join(beadsDir, "dolt")
writeTestMetadata(t, testDBPath, dbName)
inner := newTestStore(t, testDBPath)
spy := newFilterCapturingStore(inner)
store = spy
storeMutex.Lock()
storeActive = true
storeMutex.Unlock()
t.Cleanup(func() {
store = nil
storeMutex.Lock()
storeActive = false
storeMutex.Unlock()
})
ctx := context.Background()
rootCtx = ctx
// Seed one row in the source repo so findCandidateIssues has
// something to find. The migration uses SourceRepo as the
// filter discriminator.
if _, err := inner.DB().ExecContext(ctx, `INSERT INTO issues (id, title, description, design, acceptance_criteria, notes, status, priority, issue_type, source_repo) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
"mig-mr-1", "Migration MaxRows gate seed", "body", "", "", "", "open", 1, "task", "source-repo-a"); err != nil {
t.Fatalf("seed: %v", err)
}
params := migrateIssuesParams{
from: "source-repo-a",
to: "source-repo-b",
priority: -1, // sentinel: "any priority"
}
if _, err := findCandidateIssues(ctx, spy, params); err != nil {
t.Fatalf("findCandidateIssues: %v", err)
}
if spy.Calls() == 0 {
t.Fatal("findCandidateIssues did not invoke SearchIssues; gate did not exercise the filter")
}
for i, f := range spy.AllFilters() {
if f.MaxRows != 0 {
t.Errorf("be-x42v.4 gate: SearchIssues call %d had filter.MaxRows=%d; bd migrate-issues must opt out (MaxRows=0) — designer §4.1 cross-backend round-trip", i, f.MaxRows)
}
if f.MaxRowsSource != "" {
t.Errorf("be-x42v.4 gate: SearchIssues call %d had filter.MaxRowsSource=%q; bd migrate-issues must opt out (MaxRowsSource=\"\")", i, f.MaxRowsSource)
}
}
}

View file

@ -143,10 +143,18 @@ func bdProxiedListFail(t *testing.T, bd string, p proxiedProject, args ...string
}
func bdProxiedRunBuffers(t *testing.T, bd, dir string, args ...string) (string, string, error) {
t.Helper()
return bdProxiedRunBuffersWithEnv(t, bd, dir, nil, args...)
}
// bdProxiedRunBuffersWithEnv is bdProxiedRunBuffers with extra environment
// variables appended after the standard proxied env (so they can override
// it, e.g. BEADS_MAX_ROWS for the proxied-server MaxRows-rejection tests).
func bdProxiedRunBuffersWithEnv(t *testing.T, bd, dir string, envExtras []string, args ...string) (string, string, error) {
t.Helper()
cmd := exec.Command(bd, args...)
cmd.Dir = dir
cmd.Env = bdProxiedEnv(dir)
cmd.Env = append(bdProxiedEnv(dir), envExtras...)
var stdout, stderr bytes.Buffer
cmd.Stdout = &stdout
cmd.Stderr = &stderr

View file

@ -46,7 +46,29 @@ This is useful for agents executing molecules to see which steps can run next.`,
}
}()
claimReady, _ := cmd.Flags().GetBool("claim")
if usesProxiedServer() {
// --claim consumes exactly one row, same reasoning as the
// direct-path fix in issueops/claim.go: a rig-wide cap sized
// for bulk list/ready reads must not block a single-row claim.
// Only the bulk (non-claim) proxied ready listing rejects an
// active cap.
if !claimReady {
if err := rejectMaxRowsUnderProxiedServer(cmd); err != nil {
return err
}
} else {
// Still validate --max-rows/BEADS_MAX_ROWS here even though
// the resolved cap is ignored below: resolveMaxRows is also
// where a malformed value (e.g. --max-rows -1) is rejected
// with exit 1, and skipping it entirely for the claim-exempt
// branch would silently accept a usage error that every
// other command (direct or proxied) rejects.
if _, _, err := resolveMaxRows(cmd); err != nil {
return err
}
}
return runReadyProxiedServer(cmd, rootCtx)
}
@ -54,8 +76,6 @@ This is useful for agents executing molecules to see which steps can run next.`,
return HandleErrorRespectJSON("--offset is only supported under --proxied-server")
}
claimReady, _ := cmd.Flags().GetBool("claim")
gated, _ := cmd.Flags().GetBool("gated")
if gated {
if claimReady {
@ -132,6 +152,10 @@ This is useful for agents executing molecules to see which steps can run next.`,
}
}
}
maxRows, maxRowsSource, err := resolveMaxRows(cmd)
if err != nil {
return err
}
filter := types.WorkFilter{
Status: "open", // Only show open issues, not in_progress (matches bd list --ready)
Type: issueType,
@ -144,6 +168,8 @@ This is useful for agents executing molecules to see which steps can run next.`,
IncludeDeferred: includeDeferred, // GH#820: respect --include-deferred flag
IncludeEphemeral: includeEphemeral, // bd-i5k5x: allow ephemeral issues (e.g., merge-requests)
ExcludeTypes: excludeTypes,
MaxRows: maxRows,
MaxRowsSource: maxRowsSource,
}
// Use Changed() to properly handle P0 (priority=0)
if cmd.Flags().Changed("priority") {
@ -205,6 +231,9 @@ This is useful for agents executing molecules to see which steps can run next.`,
if claimReady {
claimed, err := activeStore.ClaimReadyIssue(ctx, filter, actor)
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleErrorRespectJSON("%v", err)
}
if claimed == nil {
@ -231,6 +260,9 @@ This is useful for agents executing molecules to see which steps can run next.`,
if jsonOutput {
results, err := activeStore.GetReadyWorkWithCounts(ctx, filter)
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleErrorRespectJSON("%v", err)
}
totalReady := len(results)
@ -272,6 +304,9 @@ This is useful for agents executing molecules to see which steps can run next.`,
issues, err := activeStore.GetReadyWork(ctx, filter)
if err != nil {
if capErr := handleMaxRowsError(err); capErr != nil {
return capErr
}
return HandleErrorRespectJSON("%v", err)
}
@ -769,6 +804,8 @@ func init() {
// Metadata filtering (GH#1406)
readyCmd.Flags().StringArray("metadata-field", nil, "Filter by metadata field (key=value, repeatable)")
readyCmd.Flags().String("has-metadata-key", "", "Filter issues that have this metadata key set")
// Defensive row cap (be-x42v): exits 2 on overage, default disabled.
addMaxRowsFlag(readyCmd)
rootCmd.AddCommand(readyCmd)
blockedCmd.Flags().String("parent", "", "Filter to descendants of this bead/epic")
rootCmd.AddCommand(blockedCmd)

View file

@ -0,0 +1,214 @@
//go:build cgo
// be-u8z9: GetReadyWork honors WorkFilter.MaxRows. These integration tests
// exercise the storage path via newTestStore (matches the pattern in
// metadata_ready_test.go); the *Filter cap is not exercised by the helper
// unit tests in internal/storage/issueops/search_test.go, which only cover
// EffectiveSearchLimit + EnforceMaxRowsCap in isolation.
package main
import (
"context"
"errors"
"fmt"
"testing"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
)
func TestGetReadyWork_MaxRowsSuite(t *testing.T) {
t.Parallel()
tmpDir := t.TempDir()
store := newTestStore(t, tmpDir)
ctx := context.Background()
const totalReady = 6
for i := 0; i < totalReady; i++ {
iss := &types.Issue{
ID: fmt.Sprintf("mr-rw-%d", i),
Title: fmt.Sprintf("Ready max-rows %d", i),
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
}
if err := store.CreateIssue(ctx, iss, "test"); err != nil {
t.Fatalf("CreateIssue(%s): %v", iss.ID, err)
}
}
t.Run("UnderCap", func(t *testing.T) {
results, err := store.GetReadyWork(ctx, types.WorkFilter{
Status: "open",
MaxRows: 100,
MaxRowsSource: "--max-rows",
})
if err != nil {
t.Fatalf("GetReadyWork: %v", err)
}
if len(results) < totalReady {
t.Errorf("expected at least %d results, got %d", totalReady, len(results))
}
})
t.Run("OverCap", func(t *testing.T) {
_, err := store.GetReadyWork(ctx, types.WorkFilter{
Status: "open",
MaxRows: 3,
MaxRowsSource: "--max-rows",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
if typed.Found <= 3 {
t.Errorf("ErrTooManyRows.Found = %d, want > 3", typed.Found)
}
if typed.Cap != 3 {
t.Errorf("ErrTooManyRows.Cap = %d, want 3", typed.Cap)
}
if typed.Source != "--max-rows" {
t.Errorf("ErrTooManyRows.Source = %q, want %q", typed.Source, "--max-rows")
}
})
t.Run("OverCap_EnvSource", func(t *testing.T) {
_, err := store.GetReadyWork(ctx, types.WorkFilter{
Status: "open",
MaxRows: 2,
MaxRowsSource: "BEADS_MAX_ROWS",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
if typed.Source != "BEADS_MAX_ROWS" {
t.Errorf("ErrTooManyRows.Source = %q, want %q", typed.Source, "BEADS_MAX_ROWS")
}
})
t.Run("Zero_Disabled", func(t *testing.T) {
results, err := store.GetReadyWork(ctx, types.WorkFilter{
Status: "open",
MaxRows: 0,
MaxRowsSource: "",
})
if err != nil {
t.Fatalf("GetReadyWork with MaxRows=0: %v", err)
}
if len(results) < totalReady {
t.Errorf("expected at least %d results with disabled cap, got %d", totalReady, len(results))
}
})
t.Run("WithLimit_LimitUnderCap_NoError", func(t *testing.T) {
// Limit caps at 2 well below MaxRows=100: cap never fires.
results, err := store.GetReadyWork(ctx, types.WorkFilter{
Status: "open",
Limit: 2,
MaxRows: 100,
MaxRowsSource: "--max-rows",
})
if err != nil {
t.Fatalf("GetReadyWork: %v", err)
}
if len(results) != 2 {
t.Errorf("expected exactly 2 results, got %d", len(results))
}
})
t.Run("WithLimit_LimitOverCap_FiresCap", func(t *testing.T) {
// Limit=10, MaxRows=3 with 6 rows in DB: EffectiveSearchLimit returns
// 4 (=cap+1), GetReadyWork scans 4 and EnforceMaxRowsCap fires.
_, err := store.GetReadyWork(ctx, types.WorkFilter{
Status: "open",
Limit: 10,
MaxRows: 3,
MaxRowsSource: "BEADS_MAX_ROWS",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
if typed.Cap != 3 {
t.Errorf("ErrTooManyRows.Cap = %d, want 3", typed.Cap)
}
if typed.Source != "BEADS_MAX_ROWS" {
t.Errorf("ErrTooManyRows.Source = %q, want %q", typed.Source, "BEADS_MAX_ROWS")
}
})
t.Run("WithLimit_LimitAtCap_NoError", func(t *testing.T) {
// Limit==MaxRows: storage emits LIMIT N (no +1 sniff), returns N rows
// without overage detection. Matches EffectiveSearchLimit's "limit
// equals cap → limit" branch.
results, err := store.GetReadyWork(ctx, types.WorkFilter{
Status: "open",
Limit: 3,
MaxRows: 3,
MaxRowsSource: "--max-rows",
})
if err != nil {
t.Fatalf("GetReadyWork: %v", err)
}
if len(results) != 3 {
t.Errorf("expected exactly 3 results at limit==cap, got %d", len(results))
}
})
}
// TestClaimReadyIssue_MaxRows_LargePoolUnderLowCap is the be-x42v.4-follow-up
// regression for ClaimReadyIssueInTx: a rig-wide BEADS_MAX_ROWS cap (sized
// for bulk list/ready reads) must never fail a claim, which only ever
// consumes a single row regardless of how large the ready pool is.
// Before the claim.go:206 fix, ClaimReadyIssueInTx forwarded MaxRows into
// its internal unbounded GetReadyWorkInTx scan, so a ready pool bigger than
// the cap made every claim attempt exit with ErrTooManyRows.
func TestClaimReadyIssue_MaxRows_LargePoolUnderLowCap(t *testing.T) {
t.Parallel()
tmpDir := t.TempDir()
store := newTestStore(t, tmpDir)
ctx := context.Background()
// Ready pool (10) is well above the cap (3) — this is exactly the
// agent-rig scenario the flag targets: a low defensive cap on bulk
// reads, but claim must still succeed.
const totalReady = 10
for i := 0; i < totalReady; i++ {
iss := &types.Issue{
ID: fmt.Sprintf("mr-claim-%d", i),
Title: fmt.Sprintf("Claim max-rows %d", i),
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
}
if err := store.CreateIssue(ctx, iss, "test"); err != nil {
t.Fatalf("CreateIssue(%s): %v", iss.ID, err)
}
}
claimed, err := store.ClaimReadyIssue(ctx, types.WorkFilter{
Status: "open",
MaxRows: 3,
MaxRowsSource: "BEADS_MAX_ROWS",
}, "claimant")
if err != nil {
t.Fatalf("ClaimReadyIssue under cap=3 with %d-issue ready pool: unexpected error: %v", totalReady, err)
}
if claimed == nil {
t.Fatal("ClaimReadyIssue returned nil issue, want a claimed issue")
}
if claimed.Status != types.StatusInProgress {
t.Errorf("claimed issue status = %q, want %q", claimed.Status, types.StatusInProgress)
}
}

View file

@ -748,6 +748,86 @@ func TestProxiedServerReady2(t *testing.T) {
}
})
// be-x42v.4 round-3 follow-up: rejectMaxRowsUnderProxiedServer must not
// block `bd ready --claim` under proxied mode. --claim always delivers
// exactly one row (same reasoning as the direct-path fix in
// issueops/claim.go), so a rig-wide cap sized for bulk reads must not
// hard-fail it. Bulk (non-claim) `bd ready` under proxied mode with an
// active cap must still reject, same as `bd list` (see
// list_proxied_integration_test.go's reject_max_rows_flag/_env).
t.Run("claim_succeeds_under_env_max_rows_cap", func(t *testing.T) {
t.Parallel()
p := newSharedProxiedProject(t, bd, "rcmr")
// Ready pool (3) exceeds the cap (1) — exactly the scenario a
// rig-wide BEADS_MAX_ROWS is meant to guard bulk reads against,
// while claim (which only ever returns one row) must still work.
for i := 0; i < 3; i++ {
bdProxiedCreate(t, bd, p.dir, fmt.Sprintf("Claim under cap %d", i), "--label", "rcmr-claim")
}
stdout, stderr, err := bdProxiedRunBuffersWithEnv(t, bd, p.dir,
[]string{"BEADS_MAX_ROWS=1"},
"ready", "--claim", "--json", "--label", "rcmr-claim")
if err != nil {
t.Fatalf("bd ready --claim --json under BEADS_MAX_ROWS=1 with a larger ready pool should succeed: %v\nstdout:\n%s\nstderr:\n%s",
err, stdout, stderr)
}
var claimed []types.IssueWithCounts
s := strings.TrimSpace(stdout)
start := strings.Index(s, "[")
if start < 0 {
t.Fatalf("no JSON array in claim output:\n%s", stdout)
}
if err := json.Unmarshal([]byte(s[start:]), &claimed); err != nil {
t.Fatalf("parse claim JSON: %v\n%s", err, s[start:])
}
if len(claimed) != 1 {
t.Fatalf("expected exactly one claimed issue, got %d: %s", len(claimed), stdout)
}
if claimed[0].Status != types.StatusInProgress {
t.Errorf("Status = %s, want %s", claimed[0].Status, types.StatusInProgress)
}
})
// be-x42v.4 round-4 follow-up (codex P2): the claim-exempt branch above
// must still validate --max-rows via resolveMaxRows even though it
// ignores the resolved (positive) cap — otherwise a malformed value
// like -1 is silently accepted under proxied `ready --claim`, unlike
// every other command (direct or proxied).
t.Run("claim_rejects_invalid_max_rows_flag", func(t *testing.T) {
t.Parallel()
p := newSharedProxiedProject(t, bd, "rcim")
bdProxiedCreate(t, bd, p.dir, "Claim invalid max-rows seed")
out := bdProxiedReadyFail(t, bd, p, "--claim", "--max-rows", "-1")
if !strings.Contains(out, "must be non-negative") {
t.Errorf("expected --max-rows usage-error rejection, got: %s", out)
}
})
t.Run("reject_bulk_ready_under_max_rows_flag", func(t *testing.T) {
t.Parallel()
p := newSharedProxiedProject(t, bd, "rbmf")
bdProxiedCreate(t, bd, p.dir, "Bulk ready seed")
out := bdProxiedReadyFail(t, bd, p, "--max-rows", "1")
if !strings.Contains(out, "not supported in proxied-server mode") {
t.Errorf("expected --max-rows proxied-server rejection for bulk (non-claim) ready, got: %s", out)
}
})
t.Run("reject_bulk_ready_under_max_rows_env", func(t *testing.T) {
t.Parallel()
p := newSharedProxiedProject(t, bd, "rbme")
bdProxiedCreate(t, bd, p.dir, "Bulk ready env seed")
stdout, stderr, err := bdProxiedRunBuffersWithEnv(t, bd, p.dir,
[]string{"BEADS_MAX_ROWS=1"}, "ready")
if err == nil {
t.Fatalf("expected BEADS_MAX_ROWS under proxied bulk ready to fail, but it succeeded:\nstdout:\n%s\nstderr:\n%s", stdout, stderr)
}
out := stdout + stderr
if !strings.Contains(out, "not supported in proxied-server mode") {
t.Errorf("expected BEADS_MAX_ROWS proxied-server rejection for bulk (non-claim) ready, got: %s", out)
}
})
t.Run("exclude_type_csv_and_repeated", func(t *testing.T) {
t.Parallel()
p := newSharedProxiedProject(t, bd, "rxt")

View file

@ -0,0 +1,236 @@
// be-x42v.3: storage-layer behavioral coverage of SearchIssues + MaxRows
// against the dolt-server backend.
//
// Parity with the embedded backend is implicit: both SearchIssues entry
// points are thin wrappers around issueops.SearchIssuesInTx, so the cap
// behavior is shared by construction. The embedded counterpart of these
// tests lives in internal/storage/embeddeddolt/search_max_rows_test.go
// and exercises the same fixture and assertions; if either backend
// diverges from the cap contract, both tests will not stay in sync.
package dolt
import (
"context"
"errors"
"fmt"
"testing"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
)
// seedSearchMaxRowsIssues creates n open task issues for SearchIssues fixtures.
func seedSearchMaxRowsIssues(t *testing.T, ctx context.Context, store *DoltStore, n int) {
t.Helper()
for i := 0; i < n; i++ {
iss := &types.Issue{
ID: fmt.Sprintf("smr-%d", i),
Title: fmt.Sprintf("Search max-rows fixture %d", i),
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
}
if err := store.CreateIssue(ctx, iss, "test"); err != nil {
t.Fatalf("CreateIssue(%s): %v", iss.ID, err)
}
}
}
func TestSearchIssues_MaxRows_NotExceeded(t *testing.T) {
store, cleanup := setupTestStore(t)
defer cleanup()
ctx, cancel := testContext(t)
defer cancel()
seedSearchMaxRowsIssues(t, ctx, store, 3)
results, err := store.SearchIssues(ctx, "", types.IssueFilter{
MaxRows: 5,
MaxRowsSource: "--max-rows",
})
if err != nil {
t.Fatalf("SearchIssues: %v", err)
}
if len(results) != 3 {
t.Errorf("expected 3 rows under cap, got %d", len(results))
}
}
func TestSearchIssues_MaxRows_Exceeded_ReturnsErrTooManyRows(t *testing.T) {
t.Run("FlagSource", func(t *testing.T) {
store, cleanup := setupTestStore(t)
defer cleanup()
ctx, cancel := testContext(t)
defer cancel()
seedSearchMaxRowsIssues(t, ctx, store, 6)
_, err := store.SearchIssues(ctx, "", types.IssueFilter{
MaxRows: 3,
MaxRowsSource: "--max-rows",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
if typed.Found <= 3 {
t.Errorf("ErrTooManyRows.Found = %d, want > 3", typed.Found)
}
if typed.Cap != 3 {
t.Errorf("ErrTooManyRows.Cap = %d, want 3", typed.Cap)
}
if typed.Source != "--max-rows" {
t.Errorf("ErrTooManyRows.Source = %q, want %q", typed.Source, "--max-rows")
}
})
t.Run("EnvSource", func(t *testing.T) {
store, cleanup := setupTestStore(t)
defer cleanup()
ctx, cancel := testContext(t)
defer cancel()
seedSearchMaxRowsIssues(t, ctx, store, 6)
_, err := store.SearchIssues(ctx, "", types.IssueFilter{
MaxRows: 2,
MaxRowsSource: "BEADS_MAX_ROWS",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
if typed.Source != "BEADS_MAX_ROWS" {
t.Errorf("ErrTooManyRows.Source = %q, want %q", typed.Source, "BEADS_MAX_ROWS")
}
if typed.Cap != 2 {
t.Errorf("ErrTooManyRows.Cap = %d, want 2", typed.Cap)
}
})
}
func TestSearchIssues_MaxRows_Zero_NoCap(t *testing.T) {
store, cleanup := setupTestStore(t)
defer cleanup()
ctx, cancel := testContext(t)
defer cancel()
seedSearchMaxRowsIssues(t, ctx, store, 6)
results, err := store.SearchIssues(ctx, "", types.IssueFilter{
MaxRows: 0,
MaxRowsSource: "",
})
if err != nil {
t.Fatalf("SearchIssues with MaxRows=0: %v", err)
}
if len(results) != 6 {
t.Errorf("expected 6 rows with cap disabled, got %d", len(results))
}
}
// TestSearchIssues_MaxRows_WithLimit covers the four-quadrant (Limit,
// MaxRows) matrix end-to-end against a 6-row fixture. The helper-level
// shape selection is covered by issueops.TestEffectiveSearchLimit.
func TestSearchIssues_MaxRows_WithLimit(t *testing.T) {
t.Run("LimitUnderCap_NoError", func(t *testing.T) {
store, cleanup := setupTestStore(t)
defer cleanup()
ctx, cancel := testContext(t)
defer cancel()
seedSearchMaxRowsIssues(t, ctx, store, 6)
results, err := store.SearchIssues(ctx, "", types.IssueFilter{
Limit: 3,
MaxRows: 100,
MaxRowsSource: "--max-rows",
})
if err != nil {
t.Fatalf("SearchIssues: %v", err)
}
if len(results) != 3 {
t.Errorf("expected 3 rows with limit=3 under cap, got %d", len(results))
}
})
t.Run("LimitEqualsCap_NoError", func(t *testing.T) {
store, cleanup := setupTestStore(t)
defer cleanup()
ctx, cancel := testContext(t)
defer cancel()
seedSearchMaxRowsIssues(t, ctx, store, 6)
results, err := store.SearchIssues(ctx, "", types.IssueFilter{
Limit: 3,
MaxRows: 3,
MaxRowsSource: "--max-rows",
})
if err != nil {
t.Fatalf("SearchIssues: %v", err)
}
if len(results) != 3 {
t.Errorf("expected 3 rows with limit==cap, got %d", len(results))
}
})
t.Run("LimitOverCap_FiresCap", func(t *testing.T) {
store, cleanup := setupTestStore(t)
defer cleanup()
ctx, cancel := testContext(t)
defer cancel()
seedSearchMaxRowsIssues(t, ctx, store, 6)
_, err := store.SearchIssues(ctx, "", types.IssueFilter{
Limit: 10,
MaxRows: 3,
MaxRowsSource: "BEADS_MAX_ROWS",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
if typed.Cap != 3 {
t.Errorf("ErrTooManyRows.Cap = %d, want 3", typed.Cap)
}
if typed.Source != "BEADS_MAX_ROWS" {
t.Errorf("ErrTooManyRows.Source = %q, want %q", typed.Source, "BEADS_MAX_ROWS")
}
})
t.Run("OnlyCap_FiresOnOverage", func(t *testing.T) {
store, cleanup := setupTestStore(t)
defer cleanup()
ctx, cancel := testContext(t)
defer cancel()
seedSearchMaxRowsIssues(t, ctx, store, 6)
_, err := store.SearchIssues(ctx, "", types.IssueFilter{
MaxRows: 4,
MaxRowsSource: "--max-rows",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
if typed.Cap != 4 {
t.Errorf("ErrTooManyRows.Cap = %d, want 4", typed.Cap)
}
})
}

View file

@ -0,0 +1,239 @@
//go:build cgo
// be-x42v.3: storage-layer behavioral coverage of SearchIssues + MaxRows
// against the embedded Dolt backend. The cap enforcement itself lives in
// issueops.SearchIssuesInTx / EnforceMaxRowsCap (see search_test.go in
// issueops); these tests confirm the cap fires end-to-end through the
// embedded backend's real SQL path on a real fixture.
//
// Per-backend parity vs the dolt-server backend is implicit: both
// SearchIssues entry points are thin wrappers around the same
// issueops.SearchIssuesInTx, so cap behavior is shared by construction.
// The dolt-server-side counterpart of these tests lives in
// internal/storage/dolt/search_max_rows_test.go and uses the same
// fixture (6 open task issues) and the same assertions.
package embeddeddolt_test
import (
"errors"
"fmt"
"testing"
"github.com/steveyegge/beads/internal/storage/issueops"
"github.com/steveyegge/beads/internal/types"
)
// seedSearchIssues creates n open task issues for SearchIssues fixtures.
// Returns nothing (the caller queries via SearchIssues).
func seedSearchIssues(t *testing.T, te *testEnv, n int) {
t.Helper()
ctx := t.Context()
for i := 0; i < n; i++ {
iss := &types.Issue{
ID: fmt.Sprintf("%s-mr-%d", te.database, i),
Title: fmt.Sprintf("Search max-rows fixture %d", i),
Status: types.StatusOpen,
Priority: 2,
IssueType: types.TypeTask,
}
if err := te.store.CreateIssue(ctx, iss, "test"); err != nil {
t.Fatalf("CreateIssue(%s): %v", iss.ID, err)
}
}
}
func TestSearchIssues_MaxRows_NotExceeded(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "mrne")
seedSearchIssues(t, te, 3)
// 3 rows, cap=5 → success, no error, all 3 returned.
results, err := te.store.SearchIssues(t.Context(), "", types.IssueFilter{
MaxRows: 5,
MaxRowsSource: "--max-rows",
})
if err != nil {
t.Fatalf("SearchIssues: %v", err)
}
if len(results) != 3 {
t.Errorf("expected 3 rows under cap, got %d", len(results))
}
}
func TestSearchIssues_MaxRows_Exceeded_ReturnsErrTooManyRows(t *testing.T) {
skipUnlessEmbeddedDolt(t)
t.Run("FlagSource", func(t *testing.T) {
te := newTestEnv(t, "mref")
seedSearchIssues(t, te, 6)
_, err := te.store.SearchIssues(t.Context(), "", types.IssueFilter{
MaxRows: 3,
MaxRowsSource: "--max-rows",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
// Storage layer issues LIMIT cap+1 to sniff overage — Found is the
// observed row count when the cap fired, which equals cap+1 in
// practice (the +1 sniff probe).
if typed.Found <= 3 {
t.Errorf("ErrTooManyRows.Found = %d, want > 3", typed.Found)
}
if typed.Cap != 3 {
t.Errorf("ErrTooManyRows.Cap = %d, want 3", typed.Cap)
}
if typed.Source != "--max-rows" {
t.Errorf("ErrTooManyRows.Source = %q, want %q", typed.Source, "--max-rows")
}
})
t.Run("EnvSource", func(t *testing.T) {
te := newTestEnv(t, "mree")
seedSearchIssues(t, te, 6)
_, err := te.store.SearchIssues(t.Context(), "", types.IssueFilter{
MaxRows: 2,
MaxRowsSource: "BEADS_MAX_ROWS",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
if typed.Source != "BEADS_MAX_ROWS" {
t.Errorf("ErrTooManyRows.Source = %q, want %q", typed.Source, "BEADS_MAX_ROWS")
}
if typed.Cap != 2 {
t.Errorf("ErrTooManyRows.Cap = %d, want 2", typed.Cap)
}
})
}
func TestSearchIssues_MaxRows_Zero_NoCap(t *testing.T) {
skipUnlessEmbeddedDolt(t)
te := newTestEnv(t, "mrzc")
seedSearchIssues(t, te, 6)
// MaxRows=0 is the disabled form. With 6 rows and cap=0, no error.
results, err := te.store.SearchIssues(t.Context(), "", types.IssueFilter{
MaxRows: 0,
MaxRowsSource: "",
})
if err != nil {
t.Fatalf("SearchIssues with MaxRows=0: %v", err)
}
if len(results) != 6 {
t.Errorf("expected 6 rows with cap disabled, got %d", len(results))
}
}
// TestSearchIssues_MaxRows_WithLimit exercises the four-quadrant matrix
// (Limit, MaxRows) from designer §3.1:
//
// Limit MaxRows Effective Cap fires?
// ───── ─────── ───────── ──────────
// 0 0 unlimited no
// 0 N LIMIT N+1 (sniff) yes when >N
// L 0 LIMIT L no
// L<=N N LIMIT L (limit wins, no overage detection) no
// L>N N LIMIT N+1 (sniff) yes when >N
//
// The helper-level cases (Limit, MaxRows shape selection) are covered by
// TestEffectiveSearchLimit; these cases verify the end-to-end behavior
// against a real 6-row fixture.
func TestSearchIssues_MaxRows_WithLimit(t *testing.T) {
skipUnlessEmbeddedDolt(t)
t.Run("LimitUnderCap_NoError", func(t *testing.T) {
te := newTestEnv(t, "mrlu")
seedSearchIssues(t, te, 6)
results, err := te.store.SearchIssues(t.Context(), "", types.IssueFilter{
Limit: 3,
MaxRows: 100,
MaxRowsSource: "--max-rows",
})
if err != nil {
t.Fatalf("SearchIssues: %v", err)
}
if len(results) != 3 {
t.Errorf("expected 3 rows with limit=3 under cap, got %d", len(results))
}
})
t.Run("LimitEqualsCap_NoError", func(t *testing.T) {
te := newTestEnv(t, "mrle")
seedSearchIssues(t, te, 6)
// Limit == MaxRows: storage emits LIMIT N (no +1 sniff), so no
// overage detection. EffectiveSearchLimit's "limit equals cap →
// limit" branch.
results, err := te.store.SearchIssues(t.Context(), "", types.IssueFilter{
Limit: 3,
MaxRows: 3,
MaxRowsSource: "--max-rows",
})
if err != nil {
t.Fatalf("SearchIssues: %v", err)
}
if len(results) != 3 {
t.Errorf("expected 3 rows with limit==cap, got %d", len(results))
}
})
t.Run("LimitOverCap_FiresCap", func(t *testing.T) {
te := newTestEnv(t, "mrlo")
seedSearchIssues(t, te, 6)
// Limit=10, MaxRows=3 with 6 rows: EffectiveSearchLimit picks
// MaxRows+1=4, scan returns 4, cap fires.
_, err := te.store.SearchIssues(t.Context(), "", types.IssueFilter{
Limit: 10,
MaxRows: 3,
MaxRowsSource: "BEADS_MAX_ROWS",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
if typed.Cap != 3 {
t.Errorf("ErrTooManyRows.Cap = %d, want 3", typed.Cap)
}
if typed.Source != "BEADS_MAX_ROWS" {
t.Errorf("ErrTooManyRows.Source = %q, want %q", typed.Source, "BEADS_MAX_ROWS")
}
})
t.Run("OnlyCap_FiresOnOverage", func(t *testing.T) {
te := newTestEnv(t, "mroc")
seedSearchIssues(t, te, 6)
// No Limit set, MaxRows=4 with 6 rows: storage issues LIMIT 5
// (cap+1), gets 5 rows, cap fires.
_, err := te.store.SearchIssues(t.Context(), "", types.IssueFilter{
MaxRows: 4,
MaxRowsSource: "--max-rows",
})
if err == nil {
t.Fatal("expected ErrTooManyRows, got nil")
}
var typed *issueops.ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("expected *ErrTooManyRows, got %T: %v", err, err)
}
if typed.Cap != 4 {
t.Errorf("ErrTooManyRows.Cap = %d, want 4", typed.Cap)
}
})
}

View file

@ -203,7 +203,30 @@ func ClaimReadyIssueInTx(
claimFilter.Status = types.StatusOpen
claimFilter.Unassigned = true
claimFilter.Assignee = nil
// Claim only ever delivers the one issue it successfully claims below —
// the breaker's job is to bound delivered payloads, and a claim's
// payload is always exactly one row regardless of how large the ready
// pool it scanned was. So a rig-wide BEADS_MAX_ROWS/--max-rows cap
// (sized for bulk list/ready reads) must not fire here, and the scan
// itself must stay unbounded (Limit=0): the loop below walks
// readyIssues in order and continues past any that are transiently
// unclaimable (already claimed by a racing agent, etc), so bounding
// the scan to Limit=MaxRows (e.g. BEADS_MAX_ROWS=1 → scan only the
// single top-of-queue row) would make claim spuriously return "nothing
// to claim" whenever that narrow window is unclaimable, even with
// plenty of other ready work available. Clear the cap fields so
// GetReadyWorkInTx never returns ErrTooManyRows either.
//
// This is parity with pre-PR main (which never bounded the claim scan)
// and correctness-first: an unbounded scan preserves claim's existing
// fairness/ordering guarantee across the whole ready set. A paged scan
// that stays bounded while still walking past unclaimable rows is a
// reasonable follow-up, but it's a genuine behavior change (not a
// MaxRows-cap fix) and is deliberately deferred rather than folded in
// here.
claimFilter.Limit = 0
claimFilter.MaxRows = 0
claimFilter.MaxRowsSource = ""
readyIssues, err := GetReadyWorkInTx(ctx, tx, claimFilter)
if err != nil {

View file

@ -0,0 +1,28 @@
package issueops
import "fmt"
// ErrTooManyRows is returned by SearchIssuesInTx (and equivalent paths in
// other backends) when a search would yield more rows than the caller's
// MaxRows cap allows. Callers can match it with errors.As to surface a
// structured "result set too large" condition instead of an opaque error
// string.
//
// Found is the row count observed when the cap fired. The storage layer
// issues LIMIT MaxRows+1 to detect overage, so Found equals MaxRows+1 in
// practice; the true row count in the underlying data may be larger.
//
// Source attributes which knob set MaxRows. Expected values: "--max-rows",
// "BEADS_MAX_ROWS", or "" (library users with no source attribution).
type ErrTooManyRows struct {
Found int
Cap int
Source string
}
func (e *ErrTooManyRows) Error() string {
if e.Source != "" {
return fmt.Sprintf("search returned %d rows, exceeding %s cap of %d", e.Found, e.Source, e.Cap)
}
return fmt.Sprintf("search returned %d rows, exceeding cap of %d", e.Found, e.Cap)
}

View file

@ -75,8 +75,8 @@ func buildReadyWorkPredicates(ctx context.Context, tx DBTX, filter types.WorkFil
args = append(args, orderBy.Args...)
var limitSQL string
if filter.Limit > 0 {
limitSQL = fmt.Sprintf("LIMIT %d", filter.Limit)
if eff := EffectiveSearchLimit(filter.Limit, filter.MaxRows); eff > 0 {
limitSQL = fmt.Sprintf("LIMIT %d", eff)
}
return &readyWorkPredicates{
@ -136,6 +136,12 @@ func GetReadyWorkInTx(
ordered = mergeReadyWisps(ordered, wisps, filter)
}
// Apply the defensive cap on the row count returned to the caller.
// LIMIT cap+1 was issued above so a count of cap+1 indicates overage.
if err := EnforceMaxRowsCap(len(ordered), filter.MaxRows, filter.MaxRowsSource); err != nil {
return nil, err
}
return ordered, nil
}
@ -304,6 +310,15 @@ func readyWorkWispIssueFilter(filter types.WorkFilter) types.IssueFilter {
Pinned: &pinnedFalse,
MetadataFields: filter.MetadataFields,
HasMetadataKey: filter.HasMetadataKey,
// be-x42v.4 follow-up (review SHOULD-FIX 8): without this,
// getReadyWispsInTx's unbounded (Limit<=0) branch called
// searchTableInTxT with MaxRows=0, so EffectiveSearchLimit emitted
// no SQL LIMIT at all — the entire wisps table matching the
// predicate was scanned and hydrated before GetReadyWorkInTx's
// post-merge EnforceMaxRowsCap ever ran. Propagating the cap here
// lets EffectiveSearchLimit bound that query to cap+1 up front.
MaxRows: filter.MaxRows,
MaxRowsSource: filter.MaxRowsSource,
}
if filter.Status != "" {
s := filter.Status

View file

@ -31,10 +31,10 @@ func GetReadyWorkWithCountsInTx(ctx context.Context, tx *sql.Tx, filter types.Wo
return nil, fmt.Errorf("get ready work with counts: wisp probe: %w", probeErr)
}
if empty {
return out, nil
return finishReadyWorkWithCounts(out, filter)
}
if !wispDepsExist {
return out, nil
return finishReadyWorkWithCounts(out, filter)
}
wispPreds, err := buildReadyWorkPredicates(ctx, tx, filter, WispsFilterTables)
@ -44,12 +44,12 @@ func GetReadyWorkWithCountsInTx(ctx context.Context, tx *sql.Tx, filter types.Wo
wisps, err := runReadyCountsInTx(ctx, tx, WispsFilterTables, filter.Limit, wispPreds, true, false)
if err != nil {
if isTableNotExistError(err) {
return out, nil
return finishReadyWorkWithCounts(out, filter)
}
return nil, err
}
if len(wisps) == 0 {
return out, nil
return finishReadyWorkWithCounts(out, filter)
}
// Prefer the canonical wisp record when an ID exists in both tables (be-iabdi).
@ -71,10 +71,38 @@ func GetReadyWorkWithCountsInTx(ctx context.Context, tx *sql.Tx, filter types.Wo
}
kept = append(kept, wisps...)
sortIssuesWithCountsByPolicy(kept, filter.SortPolicy)
if filter.Limit > 0 && len(kept) > filter.Limit {
kept = kept[:filter.Limit]
return finishReadyWorkWithCounts(kept, filter)
}
// finishReadyWorkWithCounts is the terminal hook every
// GetReadyWorkWithCountsInTx exit path routes through: it applies the
// caller-facing Limit trim and then enforces the defensive MaxRows cap
// (be-x42v) on the delivered count — mirroring GetReadyWorkInTx's
// non-counts path, where mergeReadyWisps already trims the merged
// issues+wisps set to Limit before EnforceMaxRowsCap runs on it.
//
// Trim-before-cap matters specifically for the merged (issues+wisps) case:
// each table's query is independently bounded by
// EffectiveSearchLimit(filter.Limit, filter.MaxRows), so with
// --include-ephemeral the merged pre-trim slice can hold up to ~2x that
// per-table bound — e.g. Limit=2, MaxRows=3, two rows ready in each table
// merges to 4, which trips MaxRows even though the actually-delivered page
// (trimmed to Limit=2) is well within the cap. Checking the cap against the
// delivered/post-trim count instead avoids that false positive.
//
// This does not weaken cap enforcement for the single-table (no wisps, or
// wisps empty/unmerged) paths: EffectiveSearchLimit already bounds a lone
// query's LIMIT to at most max(Limit, MaxRows+1), so a single source's
// result never exceeds Limit when Limit>0 and the trim is a no-op there —
// only the two-source merge can produce more rows than Limit pre-trim.
func finishReadyWorkWithCounts(items []*types.IssueWithCounts, filter types.WorkFilter) ([]*types.IssueWithCounts, error) {
if filter.Limit > 0 && len(items) > filter.Limit {
items = items[:filter.Limit]
}
return kept, nil
if err := EnforceMaxRowsCap(len(items), filter.MaxRows, filter.MaxRowsSource); err != nil {
return nil, err
}
return items, nil
}
// runReadyCountsInTx renders the ready-work counts mega-query for one table

View file

@ -4,6 +4,7 @@ import (
"context"
"database/sql"
"fmt"
"sort"
"strings"
"github.com/steveyegge/beads/internal/storage/sqlbuild"
@ -50,6 +51,19 @@ type searchProjection[T any] struct {
// joinLeases adds the leases LEFT JOIN to the FROM clause; required by
// any projection whose columns include sqlbuild.LeaseSelectColumns.
joinLeases bool
// less, when non-nil, orders two elements the same way SQL's ORDER BY
// ordered each per-table query (sqlbuild.OrderBy), given the same
// sortBy/sortDesc values the caller's filter carried. searchInTx's
// merge branch (issues+wisps) needs this to re-sort the concatenation
// of two independently-ordered legs before trimming to filter.Limit —
// without it, the trim keeps whichever leg happens to come first in
// the concatenation regardless of sort rank (be-x42v.4 round-5
// follow-up). nil for projections with no sortable payload to compare
// (idProjection scans bare IDs, no column data); safe today because no
// caller combines Limit>0 with a merged (non-SkipWisps) ID-only search
// — see the merge-trim call site for the fallback behavior if that
// changes.
less func(a, b T, sortBy string, sortDesc bool) bool
}
var issueProjection = searchProjection[*types.Issue]{
@ -57,6 +71,7 @@ var issueProjection = searchProjection[*types.Issue]{
scan: func(rows *sql.Rows) (*types.Issue, error) { return ScanIssueFrom(rows) },
id: func(issue *types.Issue) string { return issue.ID },
hydrate: hydrateIssueLabelsAndDeps,
less: sqlbuild.Less,
idShrink: true,
joinLeases: true,
}
@ -120,6 +135,10 @@ func searchInTx[T any](ctx context.Context, tx DBTX, query string, filter types.
return nil, fmt.Errorf("search wisps (ephemeral filter): %w", err)
}
if len(results) > 0 {
results = trimToSearchLimit(results, filter.Limit)
if capErr := EnforceMaxRowsCap(len(results), filter.MaxRows, filter.MaxRowsSource); capErr != nil {
return nil, capErr
}
return results, nil
}
// Fall through: wisps table doesn't exist or returned no results
@ -131,7 +150,15 @@ func searchInTx[T any](ctx context.Context, tx DBTX, query string, filter types.
}
// Skip wisps merge entirely when caller opts out (Q2: perf escape hatch).
// This is also a terminal return of the row set actually handed back to
// the caller, so — like the empty-wisps-table early return above — it
// must enforce the cap itself; skipping it here would let SkipWisps
// callers (e.g. bd list's default filter) silently bypass MaxRows.
if filter.SkipWisps {
results = trimToSearchLimit(results, filter.Limit)
if err := EnforceMaxRowsCap(len(results), filter.MaxRows, filter.MaxRowsSource); err != nil {
return nil, err
}
return results, nil
}
@ -148,6 +175,14 @@ func searchInTx[T any](ctx context.Context, tx DBTX, query string, filter types.
return nil, fmt.Errorf("search wisps (merge): probe: %w", probeErr)
}
if empty {
// No wisps to merge, but the issues-only result set can still
// exceed the cap (the merge path below enforces it at line ~74;
// this early return must enforce it too, or the cap is silently
// skipped whenever the wisps table is empty).
results = trimToSearchLimit(results, filter.Limit)
if err := EnforceMaxRowsCap(len(results), filter.MaxRows, filter.MaxRowsSource); err != nil {
return nil, err
}
return results, nil
}
wispResults, wispErr := searchTableInTxT(ctx, tx, query, filter, WispsFilterTables, proj)
@ -169,12 +204,66 @@ func searchInTx[T any](ctx context.Context, tx DBTX, query string, filter types.
}
}
results = append(filtered, wispResults...)
// The concatenation above is two independently ORDER BY'd legs,
// not a globally ordered set: re-sort by the same key before
// the merge's trimToSearchLimit call below, or trimming just
// keeps "however many durable rows fit" and can silently drop
// a higher-ranked wisp in favor of a lower-ranked durable row
// (be-x42v.4 round-5 follow-up). Mirrors
// finishSearchIssuesWithCounts's sortSearchIssuesWithCounts,
// which already sorts before its own trim.
sortMergedResults(results, proj.less, filter.SortBy, filter.SortDesc)
}
}
// Apply the defensive cap on the merged, delivered result set. Each leg
// (issues, wisps) is independently bounded by EffectiveSearchLimit, so
// the merged pre-trim count can exceed the cap even when filter.Limit
// itself does not — e.g. Limit=2, MaxRows=5, 3 rows in each table merges
// to 6, which would trip MaxRows even though the page actually handed
// back to the caller (trimmed to Limit=2) is well within the cap.
// Trimming before the cap check (mirrors GetReadyWorkInTx's
// mergeReadyWisps, which trims before its caller's EnforceMaxRowsCap
// runs) avoids that false positive; a single-source result never
// exceeds Limit when Limit>0 in the first place, so this trim is a
// no-op there and a genuine overage still fires (Limit=0, or
// Limit>MaxRows overage that survives the trim).
results = trimToSearchLimit(results, filter.Limit)
if err := EnforceMaxRowsCap(len(results), filter.MaxRows, filter.MaxRowsSource); err != nil {
return nil, err
}
return results, nil
}
// sortMergedResults re-sorts results in place by the same key SQL's ORDER BY
// applied to each per-leg query, so a subsequent trimToSearchLimit call on a
// concatenation of two independently-ordered legs (issues+wisps) keeps the
// globally correct top-N page rather than an arbitrary prefix of the
// concatenation. No-ops when less is nil (no sortable payload for this
// projection — see searchProjection.less's doc comment) or when there's
// nothing to reorder.
func sortMergedResults[T any](results []T, less func(a, b T, sortBy string, sortDesc bool) bool, sortBy string, sortDesc bool) {
if less == nil || len(results) <= 1 {
return
}
sort.SliceStable(results, func(i, j int) bool {
return less(results[i], results[j], sortBy, sortDesc)
})
}
// trimToSearchLimit truncates results to filter.Limit (when set, Limit>0)
// before the caller-facing MaxRows cap check runs. Every searchInTx exit
// path routes results returned to the caller through this before
// EnforceMaxRowsCap — see the comment above the final merge check for why
// (be-x42v.4 round-4 follow-up, mirrors finishReadyWorkWithCounts).
func trimToSearchLimit[T any](results []T, limit int) []T {
if limit > 0 && len(results) > limit {
return results[:limit]
}
return results
}
// searchTableInTxT runs a filtered search against a specific table set
// (issues or wisps) under the given projection.
//
@ -207,8 +296,8 @@ func searchTableInTxT[T any](ctx context.Context, tx DBTX, query string, filter
}
limitSQL := ""
if filter.Limit > 0 {
limitSQL = fmt.Sprintf(" LIMIT %d", filter.Limit)
if eff := EffectiveSearchLimit(filter.Limit, filter.MaxRows); eff > 0 {
limitSQL = fmt.Sprintf(" LIMIT %d", eff)
}
selectKeyword := "SELECT "
@ -324,3 +413,35 @@ func searchTablePatternBT[T any](ctx context.Context, tx DBTX, query string, fil
return results, nil
}
// EffectiveSearchLimit returns the SQL LIMIT to apply given a caller-supplied
// Limit and a defensive MaxRows cap. Semantics (architecture be-jp5s D1/R-03):
//
// - limit=0, maxRows=0: returns 0 (no LIMIT clause; unlimited)
// - limit=N, maxRows=0: returns N (today's --limit behavior)
// - limit=0, maxRows=M: returns M+1 (detect overage at cap+1)
// - limit=N, maxRows=M: returns N if N<=M, else M+1
//
// Callers issue LIMIT cap+1 specifically so that EnforceMaxRowsCap can detect
// overage by comparing len(scanned rows) to MaxRows. The returned int is the
// LIMIT value; treat 0 as "do not emit a LIMIT clause".
func EffectiveSearchLimit(limit, maxRows int) int {
if maxRows > 0 {
if limit == 0 || limit > maxRows {
return maxRows + 1
}
}
return limit
}
// EnforceMaxRowsCap returns *ErrTooManyRows when found exceeds maxRows.
// maxRows<=0 disables the cap; the function returns nil. source is the
// attribution string surfaced in the error message (see ErrTooManyRows).
// Call this after scanning rows from a query that used EffectiveSearchLimit
// to size LIMIT.
func EnforceMaxRowsCap(found, maxRows int, source string) error {
if maxRows > 0 && found > maxRows {
return &ErrTooManyRows{Found: found, Cap: maxRows, Source: source}
}
return nil
}

View file

@ -27,7 +27,7 @@ func SearchIssuesWithCountsInTx(ctx context.Context, tx *sql.Tx, query string, f
return nil, err
}
if len(wisps) > 0 {
return finishSearchIssuesWithCounts(wisps, filter), nil
return finishSearchIssuesWithCounts(wisps, filter)
}
}
// Fall through: the wisps tier is missing/empty or matched no rows.
@ -40,7 +40,7 @@ func SearchIssuesWithCountsInTx(ctx context.Context, tx *sql.Tx, query string, f
if err != nil {
return nil, err
}
return finishSearchIssuesWithCounts(out, filter), nil
return finishSearchIssuesWithCounts(out, filter)
}
out, err := runFilterSearchQueryInTx(ctx, tx, query, filter, IssuesFilterTables, wispDepsExist)
@ -50,7 +50,7 @@ func SearchIssuesWithCountsInTx(ctx context.Context, tx *sql.Tx, query string, f
// Skip wisps merge entirely when caller opts out (Q2: perf escape hatch).
if filter.SkipWisps {
return finishSearchIssuesWithCounts(out, filter), nil
return finishSearchIssuesWithCounts(out, filter)
}
empty, probeErr := wispsTableEmptyOrMissingInTx(ctx, tx)
@ -58,21 +58,21 @@ func SearchIssuesWithCountsInTx(ctx context.Context, tx *sql.Tx, query string, f
return nil, fmt.Errorf("search issues with counts: wisp probe: %w", probeErr)
}
if empty {
return finishSearchIssuesWithCounts(out, filter), nil
return finishSearchIssuesWithCounts(out, filter)
}
if !wispDepsExist {
return finishSearchIssuesWithCounts(out, filter), nil
return finishSearchIssuesWithCounts(out, filter)
}
wisps, err := runFilterSearchQueryInTx(ctx, tx, query, filter, WispsFilterTables, true)
if err != nil {
if isTableNotExistError(err) {
return finishSearchIssuesWithCounts(out, filter), nil
return finishSearchIssuesWithCounts(out, filter)
}
return nil, err
}
if len(wisps) == 0 {
return finishSearchIssuesWithCounts(out, filter), nil
return finishSearchIssuesWithCounts(out, filter)
}
// Prefer the canonical wisp record when an ID exists in both tables (be-iabdi).
@ -93,7 +93,7 @@ func SearchIssuesWithCountsInTx(ctx context.Context, tx *sql.Tx, query string, f
}
}
kept = append(kept, wisps...)
return finishSearchIssuesWithCounts(kept, filter), nil
return finishSearchIssuesWithCounts(kept, filter)
}
func runFilterSearchQueryInTx(ctx context.Context, tx *sql.Tx, query string, filter types.IssueFilter, tables FilterTables, includeWispReverseDeps bool) ([]*types.IssueWithCounts, error) {
@ -106,8 +106,8 @@ func runFilterSearchQueryInTx(ctx context.Context, tx *sql.Tx, query string, fil
whereSQL = "WHERE " + joinAnd(whereClauses)
}
limitSQL := ""
if filter.Limit > 0 {
limitSQL = fmt.Sprintf("LIMIT %d", filter.Limit)
if eff := EffectiveSearchLimit(filter.Limit, filter.MaxRows); eff > 0 {
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)
@ -154,12 +154,37 @@ func scanCountsRowsInTx(ctx context.Context, tx *sql.Tx, mainTable, query string
return out, nil
}
func finishSearchIssuesWithCounts(items []*types.IssueWithCounts, filter types.IssueFilter) []*types.IssueWithCounts {
// finishSearchIssuesWithCounts is the single terminal hook every
// SearchIssuesWithCountsInTx exit path routes through: it sorts the merged
// result, applies the caller-facing Limit trim, and only then enforces the
// defensive MaxRows cap (be-x42v) on the delivered count — mirroring
// searchInTx's trimToSearchLimit-before-EnforceMaxRowsCap ordering and
// finishReadyWorkWithCounts in ready_work_counts.go.
//
// Trim-before-cap matters for the merged (issues+wisps) case:
// runFilterSearchQueryInTx sizes each leg's SQL LIMIT independently via
// EffectiveSearchLimit(filter.Limit, filter.MaxRows), so the merged
// pre-trim slice can hold up to ~2x that per-leg bound — e.g. Limit=2,
// MaxRows=5, 3 rows in each table merges to 6, which would trip MaxRows
// even though the page actually handed back to the caller (trimmed to
// Limit=2) is well within the cap. Checking the cap against the delivered
// count instead avoids that false positive.
//
// This does not weaken cap enforcement for a single-source result: a lone
// query's LIMIT is already bounded to at most max(Limit, MaxRows+1), so its
// result never exceeds Limit when Limit>0 and the trim is a no-op there —
// only the two-source merge can produce more rows than Limit pre-trim, and
// a genuine overage (Limit=0, or Limit>MaxRows overage that survives the
// trim) still fires.
func finishSearchIssuesWithCounts(items []*types.IssueWithCounts, filter types.IssueFilter) ([]*types.IssueWithCounts, error) {
sortSearchIssuesWithCounts(items, filter.SortBy, filter.SortDesc)
if filter.Limit > 0 && len(items) > filter.Limit {
return items[:filter.Limit]
items = items[:filter.Limit]
}
return items
if err := EnforceMaxRowsCap(len(items), filter.MaxRows, filter.MaxRowsSource); err != nil {
return nil, err
}
return items, nil
}
// sortSearchIssuesWithCounts must order the merged issues+wisps rows the same

View file

@ -104,7 +104,10 @@ func TestFinishSearchIssuesWithCountsTruncatesByRequestedSort(t *testing.T) {
iwc("bd-newest-p4", 4, at(10)),
}
got := finishSearchIssuesWithCounts(items, types.IssueFilter{SortBy: "created", Limit: 2})
got, err := finishSearchIssuesWithCounts(items, types.IssueFilter{SortBy: "created", Limit: 2})
if err != nil {
t.Fatalf("sort=created limit=2: unexpected error: %v", err)
}
if len(got) != 2 || got[0].Issue.ID != "bd-newest-p4" || got[1].Issue.ID != "bd-new-p3" {
ids := make([]string, len(got))
for i, g := range got {
@ -114,7 +117,10 @@ func TestFinishSearchIssuesWithCountsTruncatesByRequestedSort(t *testing.T) {
}
// SortDesc flips the per-key default direction: created becomes ASC.
got = finishSearchIssuesWithCounts(items, types.IssueFilter{SortBy: "created", SortDesc: true, Limit: 2})
got, err = finishSearchIssuesWithCounts(items, types.IssueFilter{SortBy: "created", SortDesc: true, Limit: 2})
if err != nil {
t.Fatalf("sort=created desc limit=2: unexpected error: %v", err)
}
if len(got) != 2 || got[0].Issue.ID != "bd-old-p0" || got[1].Issue.ID != "bd-mid-p2" {
ids := make([]string, len(got))
for i, g := range got {
@ -124,7 +130,10 @@ func TestFinishSearchIssuesWithCountsTruncatesByRequestedSort(t *testing.T) {
}
// Default (no SortBy) keeps the historical priority/created/id order.
got = finishSearchIssuesWithCounts(items, types.IssueFilter{Limit: 2})
got, err = finishSearchIssuesWithCounts(items, types.IssueFilter{Limit: 2})
if err != nil {
t.Fatalf("default sort limit=2: unexpected error: %v", err)
}
if len(got) != 2 || got[0].Issue.ID != "bd-old-p0" || got[1].Issue.ID != "bd-mid-p2" {
ids := make([]string, len(got))
for i, g := range got {

View file

@ -0,0 +1,128 @@
package issueops
import (
"errors"
"strings"
"testing"
)
func TestEffectiveSearchLimit(t *testing.T) {
t.Parallel()
tests := []struct {
name string
limit int
maxRows int
want int
}{
{name: "no limit, no cap → unlimited", limit: 0, maxRows: 0, want: 0},
{name: "limit only → limit", limit: 10, maxRows: 0, want: 10},
{name: "cap only → cap+1", limit: 0, maxRows: 5, want: 6},
{name: "limit under cap → limit", limit: 3, maxRows: 5, want: 3},
{name: "limit equals cap → limit (no overage detection needed)", limit: 5, maxRows: 5, want: 5},
{name: "limit over cap → cap+1", limit: 100, maxRows: 5, want: 6},
{name: "cap=1 limit=0 → 2", limit: 0, maxRows: 1, want: 2},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
got := EffectiveSearchLimit(tc.limit, tc.maxRows)
if got != tc.want {
t.Errorf("EffectiveSearchLimit(%d, %d) = %d, want %d", tc.limit, tc.maxRows, got, tc.want)
}
})
}
}
func TestEnforceMaxRowsCap_Disabled_NoError(t *testing.T) {
t.Parallel()
if err := EnforceMaxRowsCap(1_000_000, 0, ""); err != nil {
t.Errorf("EnforceMaxRowsCap with MaxRows=0 returned error: %v (want nil)", err)
}
}
func TestEnforceMaxRowsCap_UnderCap_NoError(t *testing.T) {
t.Parallel()
if err := EnforceMaxRowsCap(3, 5, "--max-rows"); err != nil {
t.Errorf("EnforceMaxRowsCap(3, 5, ...) returned error: %v (want nil)", err)
}
}
func TestEnforceMaxRowsCap_AtCap_NoError(t *testing.T) {
t.Parallel()
if err := EnforceMaxRowsCap(5, 5, "--max-rows"); err != nil {
t.Errorf("EnforceMaxRowsCap(5, 5, ...) returned error: %v (want nil at exact cap)", err)
}
}
// TestSearchIssues_MaxRows_Exceeded_ReturnsErrTooManyRows exercises the cap
// helper that searchTableInTx invokes after scan. When the row count exceeds
// the cap, the helper returns a *ErrTooManyRows carrying Found/Cap/Source.
// The full SearchIssues integration path (issuing LIMIT cap+1 against a real
// table, then handing the count to this helper) is tested by the per-backend
// validator beads against live Dolt and embedded fixtures.
func TestSearchIssues_MaxRows_Exceeded_ReturnsErrTooManyRows(t *testing.T) {
t.Parallel()
tests := []struct {
name string
found int
cap int
source string
}{
{name: "cap-of-5-found-6 from --max-rows", found: 6, cap: 5, source: "--max-rows"},
{name: "cap-of-1-found-2 from BEADS_MAX_ROWS", found: 2, cap: 1, source: "BEADS_MAX_ROWS"},
{name: "cap-of-10-found-100 from library caller", found: 100, cap: 10, source: ""},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
err := EnforceMaxRowsCap(tc.found, tc.cap, tc.source)
if err == nil {
t.Fatalf("EnforceMaxRowsCap(%d, %d, %q) returned nil, want *ErrTooManyRows", tc.found, tc.cap, tc.source)
}
var typed *ErrTooManyRows
if !errors.As(err, &typed) {
t.Fatalf("EnforceMaxRowsCap: errors.As to *ErrTooManyRows failed; got %T %v", err, err)
}
if typed.Found != tc.found {
t.Errorf("ErrTooManyRows.Found = %d, want %d", typed.Found, tc.found)
}
if typed.Cap != tc.cap {
t.Errorf("ErrTooManyRows.Cap = %d, want %d", typed.Cap, tc.cap)
}
if typed.Source != tc.source {
t.Errorf("ErrTooManyRows.Source = %q, want %q", typed.Source, tc.source)
}
})
}
}
func TestErrTooManyRows_Error_WithSource(t *testing.T) {
t.Parallel()
err := &ErrTooManyRows{Found: 6, Cap: 5, Source: "--max-rows"}
got := err.Error()
for _, want := range []string{"6", "5", "--max-rows"} {
if !strings.Contains(got, want) {
t.Errorf("Error() = %q, missing %q", got, want)
}
}
}
func TestErrTooManyRows_Error_WithoutSource(t *testing.T) {
t.Parallel()
err := &ErrTooManyRows{Found: 6, Cap: 5}
got := err.Error()
for _, want := range []string{"6", "5"} {
if !strings.Contains(got, want) {
t.Errorf("Error() = %q, missing %q", got, want)
}
}
if strings.Contains(got, "--") {
t.Errorf("Error() = %q, should not contain dash prefix when Source empty", got)
}
}

View file

@ -1393,6 +1393,21 @@ type IssueFilter struct {
Offset int
SortBy string
SortDesc bool
// MaxRows is a defensive cap on the number of rows a search may return.
// 0 (the default) disables the cap. When >0, the storage layer issues
// LIMIT MaxRows+1 (to detect overage) and returns *issueops.ErrTooManyRows
// if the scan yielded more than MaxRows rows. MaxRows is independent of
// Limit: Limit=0 still means "unlimited" at the contract level; MaxRows is
// a safety knob layered on top. When both are set, the effective SQL LIMIT
// is min(Limit, MaxRows+1). Library users may set MaxRows directly; the
// CLI layer resolves it from --max-rows / BEADS_MAX_ROWS.
MaxRows int
// MaxRowsSource attributes which knob set MaxRows, used in error messages.
// Expected values: "--max-rows", "BEADS_MAX_ROWS", or "" (library users
// who set MaxRows directly without source attribution).
MaxRowsSource string
}
// SortPolicy determines how ready work is ordered
@ -1478,6 +1493,15 @@ type WorkFilter struct {
HasMetadataKey string // Existence check: issue has this top-level key set (non-null)
Offset int
// MaxRows enforces a hard upper bound on the row count returned. Mirrors
// IssueFilter.MaxRows so bd ready honors --max-rows / BEADS_MAX_ROWS
// symmetrically with bd list. 0 (the default) disables the cap.
MaxRows int
// MaxRowsSource attributes which knob set MaxRows. Expected values:
// "--max-rows", "BEADS_MAX_ROWS", or "" (library users with no source).
MaxRowsSource string
}
// StaleFilter is used to filter stale issue queries

View file

@ -0,0 +1,138 @@
# Release gate — `BEADS_MAX_ROWS` defensive row cap (be-x42v.1 + be-x42v.2)
- **Builder beads (CLOSED):**
- be-x42v.1 — Storage foundation (`IssueFilter.MaxRows` + `ErrTooManyRows` + `searchTableInTx` integration)
- be-x42v.2 — CLI wiring (`--max-rows` flag, `BEADS_MAX_ROWS` env, error formatting, exit codes, CHANGELOG)
- **Review beads:**
- be-xf0o — Verdict **PASS** (Opus 4.7 reviewer) on commit `3900c1bdc`
- be-2p12 — Verdict **PASS** (Opus 4.7 reviewer) on commit `dea537c56`
- **Commits shipped:** `3900c1bdc` (storage foundation) then `dea537c56` (CLI wiring), 23 files, +519/-30 over `origin/main` da73b7511
- **Branch:** `feat/be-x42v.1-max-rows-foundation` on `fork` (`quad341/beads`)
- **Evaluated:** 2026-05-12 by beads/deployer
## Scope
Adds an opt-in process-level row-count safety net to `bd`'s storage and CLI:
- Flag `--max-rows N` on `bd list`, `bd ready`, `bd dep tree`,
`bd find-duplicates`, `bd graph`.
- Env var `BEADS_MAX_ROWS=N` honored on the five above plus `bd lint`,
`bd doctor-conventions`, `bd doctor-pollution` (env-only per designer §4).
- Explicit opt-out (`MaxRows=0`, `MaxRowsSource=""`) wired at every
`IssueFilter` constructor in `bd cleanup`, `bd gc`, `bd export`,
`bd export --auto`, `bd migrate-issues`, `bd jira`.
- Storage: `internal/types.IssueFilter.MaxRows`/`MaxRowsSource`,
`*issueops.ErrTooManyRows{Found, Cap, Source}`, exported helpers
`EffectiveSearchLimit` and `EnforceMaxRowsCap`. Cap evaluated after the
`issues + wisps` merge in `SearchIssuesInTx`; `searchTableInTx` issues
`LIMIT cap+1` for bounded over-fetch. `WorkFilter.MaxRows` mirror with
`GetReadyWorkInTx` enforcement.
- `bd dep tree` applies the cap at the CLI layer (post-walk `TreeNode`
count) because tree walks don't flow through `IssueFilter`.
- `bd config show` lists `BEADS_MAX_ROWS` via a new standalone-env
collector.
- `CHANGELOG.md` Unreleased / Added entry; `CONTRIBUTING.md` storage
filter convention note on the explicit opt-out rule.
Default behavior unchanged: `MaxRows=0` is byte-identical to today on
every code path.
**Explicit deferrals (documented in the bead, not gate failures):**
- PG-backend cap parity (PG package is on the long-running
`postgres-backend` feature branch; helpers exported for reuse).
- Validator coverage for non-list command paths (filed as be-u8z9, routed
to validator).
- Validator coverage for the 10 designer §5 CLI scenarios (be-x42v.3,
still open).
- Opt-out command test gates (be-x42v.4 validator).
## Gate criteria
| # | Criterion | Verdict | Evidence |
|---|-----------|---------|----------|
| 1 | Review PASS present | **PASS** | be-xf0o (foundation) recorded `Review verdict: PASS` on 2026-05-12 11:27; be-2p12 (CLI) recorded `Review verdict: PASS` on 2026-05-12 12:28. Both single-pass (Opus 4.7); gemini second-pass currently disabled. |
| 2 | Acceptance criteria met | **PASS** | All acceptance items in both bead descriptions checked against code (see "Acceptance" below). PG-backend cap is explicitly deferred per the foundation bead. |
| 3 | Tests pass | **PASS** | See "Tests run on release branch" below. |
| 4 | No high-severity review findings open | **PASS** | Zero HIGH findings across both reviews. Three info-level findings from be-xf0o, all non-blocking and either justified-improvements or heads-up notes for follow-up validator/CLI work. |
| 5 | Final branch is clean | **PASS** | `git status` on the detached checkout shows only worktree-scaffolding untracked paths (`.gc/`, `.gitkeep`) which are never staged. |
| 6 | Branch diverges cleanly from main | **PASS** | `git merge-base --is-ancestor origin/main HEAD` confirms HEAD descends from `origin/main` (two commits on top of da73b7511; no rebase needed). |
## Acceptance (per be-x42v.1)
| Criterion | Status | Evidence |
|---|---|---|
| `IssueFilter.MaxRows int` + `MaxRowsSource string` with godoc | ✓ | `internal/types/types.go`; defaults zero/empty preserve today's behavior at every call site. |
| `*issueops.ErrTooManyRows{Found, Cap, Source}` typed error with `Error()` formatting | ✓ | `internal/storage/issueops/errors.go`; both Source-set and Source-empty branches covered by `TestErrTooManyRows_Error_With{Source,outSource}`. |
| `searchTableInTx` integration: LIMIT cap+1 when `MaxRows>0`; cap check returns `ErrTooManyRows` on overage | ✓ | `internal/storage/issueops/search.go`; routes through `EffectiveSearchLimit` helper. |
| Cap check applied after issues+wisps merge in `SearchIssuesInTx` | ✓ | Two call sites: early-return ephemeral path and post-merge path. Strictly better than the spec's pseudocode (handles union overflow when neither leg individually exceeds cap). |
| Storage happy-path test (`TestSearchIssues_MaxRows_Exceeded_ReturnsErrTooManyRows`) passes with `errors.As` Found/Cap/Source assertion | ✓ | Three sub-cases PASS. |
| Default `MaxRows=0` byte-identical to today | ✓ | `EffectiveSearchLimit(*,0)` returns the original limit; `EnforceMaxRowsCap(*,0,*)` returns nil. |
| PG-backend equivalent | **Deferred** (documented) | PG package not on `origin/main`; helpers exported for reuse when PG support lands. |
## Acceptance (per be-x42v.2)
| Criterion | Status | Evidence |
|---|---|---|
| `--max-rows int` flag on `bd list`, `bd ready`, `bd dep tree`, `bd find-duplicates`, `bd graph` | ✓ | `grep addMaxRowsFlag cmd/bd/` shows the five expected call sites. |
| Help text matches designer §2.2 verbatim | ✓ | `bd list --help` shows the prescribed text including "Hard upper bound … exit code 2 … 0 disables (the default). Overrides BEADS_MAX_ROWS for this invocation." |
| `BEADS_MAX_ROWS` env on the 5 above plus `bd lint`, `bd doctor-conventions`, `bd doctor-pollution` | ✓ | `resolveMaxRowsEnvOnly` wired in `cmd/bd/lint.go`, `doctor_conventions.go`, `doctor_pollution.go`. |
| Opt-out sites set explicit `MaxRows=0`, `MaxRowsSource=""` | ✓ | `grep -l 'MaxRows: *0' cmd/bd/{cleanup,gc,export,export_auto,migrate_issues,jira}.go` → all six present. |
| Error format: exit 2; two-line stderr; stdout empty; no ANSI | ✓ | Reviewer behavioral verification (designer §5 scenarios) on a fresh 10-issue DB matches the spec exactly; `handleMaxRowsError` formats from the typed `Found`/`Cap`/`Source` fields, not `err.Error()` passthrough. |
| `--max-rows -1` → exit 1, "must be non-negative" | ✓ | Reviewer-verified. |
| `WorkFilter.MaxRows` + `MaxRowsSource` added; `GetReadyWorkInTx` uses `EffectiveSearchLimit`/`EnforceMaxRowsCap` | ✓ | `internal/types/types.go` + `internal/storage/issueops/ready_work.go`. |
| `bd dep tree` cap at CLI layer (TreeNode count) | ✓ | `cmd/bd/dep.go` applies cap post-walk; appropriate since tree walks don't use `IssueFilter`. |
| `bd config show` lists `BEADS_MAX_ROWS` | ✓ | New `collectStandaloneEnvEntries` collector in `cmd/bd/config_show.go`. |
| `CHANGELOG.md` Unreleased / Added entry | ✓ | Present. |
| `CONTRIBUTING.md` storage-filter-conventions section | ✓ | Present; documents the explicit `MaxRows=0` opt-out rule for new commands. |
## Tests run on release branch
| Test | Result | Notes |
|------|--------|-------|
| `go build -tags gms_pure_go ./cmd/bd/` | success | clean build. |
| `go test -tags gms_pure_go ./internal/storage/issueops/ ./internal/types/` | PASS | targeted change packages. |
| `go test -tags gms_pure_go ./internal/storage/embeddeddolt/ ./internal/storage/schema/` | PASS | downstream consumers of `SearchIssuesInTx`. |
| `go test -tags gms_pure_go -v -run 'TestEffectiveSearchLimit\|TestEnforceMaxRowsCap\|TestSearchIssues_MaxRows\|TestErrTooManyRows' ./internal/storage/issueops/` | PASS (all sub-tests) | 7-case `TestEffectiveSearchLimit`, three `TestEnforceMaxRowsCap_*`, three `TestSearchIssues_MaxRows_Exceeded_ReturnsErrTooManyRows` sub-cases, two `TestErrTooManyRows_Error_*`. |
| `go vet -tags gms_pure_go ./internal/storage/issueops/ ./internal/types/ ./cmd/bd/` | clean | no output. |
| `golangci-lint run --build-tags gms_pure_go ./cmd/bd/... ./internal/storage/issueops/... ./internal/types/...` | 0 issues | matches reviewer's lint result. |
| `bd list --help` smoke (--max-rows flag presence + spec text) | matches §2.2 | verified locally on this branch. |
The reviewer's pre-existing rig-isolation failure
(`internal/storage/dolt/TestApplyConfigDefaults_*` env-leak from
`GC_DOLT_PORT=28231`) is documented as unrelated and reproducible on
`origin/main`. Not a blocker — those tests do not exercise the changed
code paths.
## Findings from reviews (no action required)
From be-xf0o (foundation review):
- **F1 (info):** Cap-placement moved from `searchTableInTx` (per spec
pseudocode) up to `SearchIssuesInTx` post-merge. Strictly better — the
union of issues+wisps legs can exceed the cap when neither leg does.
Accepted as a justified improvement over the spec.
- **F2 (info):** `ErrTooManyRows.Error()` wording diverges from designer
§3.2 (`"too many rows: %d found, %s=%d exceeded"`) and emits
`"search returned %d rows, exceeding %s cap of %d"` instead. Not
blocking because the CLI bead be-x42v.2 owns the user-visible message
and formats it from the typed `Found`/`Cap`/`Source` fields (verified
in `handleMaxRowsError`), not from `Error()` passthrough.
- **F3 (info):** `doltTransaction.SearchIssues` (the Transaction-interface
variant in `transaction.go:222`) has its own implementation that
ignores `filter.MaxRows`. No production caller in `cmd/bd` uses
`tx.SearchIssues` today (grep confirmed). Validator bead be-x42v.3 to
exercise this path or file a follow-up to wire the cap.
From be-2p12 (CLI review): no findings open.
## Push target
`origin` (`gastownhall/beads`) denies push to `quad341` (deployer's
GitHub identity); `fork` (`quad341/beads`) accepts. PR opens cross-repo
against `gastownhall/beads:main` with head
`quad341:feat/be-x42v.1-max-rows-foundation`.
## Verdict
**PASS** — push the gate-file commit to `fork`, open PR with both
commits.