beads/issueops/reader.go
Julian Knutsen d0063ac894
release/1.3.0: eleven cherry-picks for 1.3.1-rc.2 (#6653)
* fix(storage): include custom active-category statuses in bd ready (#5831) (#5918)

bd ready pins WorkFilter.Status to StatusOpen. BuildReadyWorkWhere treated
that pin as an exact match, so issues in a custom status with category
active never appeared — even though bd statuses --help, the ready_issues
view (migration 0025), and ClaimableSourceStatusesInTx all treat that
category as ready-eligible.

Widen the singular StatusOpen clause to the same predicate the view uses:

  status = ? OR status IN (SELECT name FROM custom_statuses WHERE category = 'active')

Non-open singular statuses stay exact. Built-in open still matches. Custom
wip/done/frozen/unspecified statuses stay out, matching claim's GH-3570
anti-steal set.

Reported by Justin Clemens (@justin-candor).

Addresses #5831

(cherry picked from commit 66aa73bb99)

* fix(cli): `bd list --wisp-type` cannot match a row — register the plane knob it needs (#6098)

`bd list --wisp-type heartbeat` returns an empty listing for EVERY input, and
`bd list` exposes no flag that changes that.

ListRequest.WispType is a predicate, not a plane selector — its own doc says
so, and RunReaderListWispTypeNarrowsTheAdmittedPlaneRatherThanAdmittingIt pins
it. That contract is right and this does not touch it. The doc also names the
way out:

    The combination that answers with rows is IncludeEphemeral (or
    IncludeInfra) plus this, and it is lawful rather than refused.

`bd list` registers neither `--include-ephemeral` nor `--all-types`. So of the
two combinations the doc names, the CLI can express only IncludeInfra — which
admits the plane AND lifts the infra-type exclusions AND changes the template
treatment, three decisions a caller who wanted one classification did not ask
for. The narrow knob the doc names FIRST has no flag at all.

That is the whole defect: the API composes correctly, and the CLI is missing
the other half of the pair.

## What this does

1. Registers `--include-ephemeral` on `bd list`, wired to
   `ListRequest.IncludeEphemeral` — the plane knob alone, off by default, so
   the default listing is byte-identical.

2. Refuses `--wisp-type` when no plane is admitted, with the fix in the hint,
   instead of printing an empty listing.

The refusal is at the CLI layer ONLY. At the API layer the combination stays
lawful and still composes to an empty page: that is the pinned contract, and a
programmatic caller composing filters may legitimately land on it. A human
typing `--wisp-type heartbeat` cannot have meant "prove to me that durable rows
carry no classification", so the CLI is where the guess is safe to make.

An explicit `--type` is deliberately left alone: an infra type routes to the
plane by itself, so the request may well be satisfiable, and this layer cannot
tell which types those are without loading the workspace's infra vocabulary.
Refusing there would reject lawful, answerable requests.

## Verification

    --- PASS: TestListRegistersIncludeEphemeral
    --- PASS: TestGatherListInput_WispTypeWithoutAPlaneIsRefused
    --- PASS: TestGatherListInput_WispTypeWithAPlaneIsAccepted (3 subtests)
    --- PASS: TestGatherListInput_IncludeEphemeralReachesTheRequest

The pair discriminates rather than being trivially green: a guard that refused
every `--wisp-type` would pass the refusal test and fail all three acceptance
subtests, one per route that admits the plane.

`ok github.com/steveyegge/beads/cmd/bd`, `ok
github.com/steveyegge/beads/internal/workapi`, `go build ./...` and `go vet`
clean. `internal/workapi/list.go` and the golden corpus are untouched.

docs/CLI_REFERENCE.md is not regenerated here: the docs pipeline builds from
the release tag in docs/cli-docs.pin (v1.2.2), not from this checkout, so the
new flag appears at the next release bump.

Claude-Session: https://claude.ai/code/session_01X1jMLQTSrCwtzFRS1xeUC6
(cherry picked from commit cbf84cb1c0)

* fix(list): honor --status when combined with --ready (#5924)

* fix(list): honor --status when combined with --ready (#5832)

`bd list --status X --ready` silently dropped --status and returned the
unfiltered ready set (typically open issues). BuildListFilter pinned
StatusOpen whenever ReadyFlag was set, and ReadyFilterFromIssueFilter
hard-coded the same pin, so a custom status or in_progress selector
never reached GetReadyWork.

--ready without --status still defaults to open. An explicit --status
is now the ready-work status selector, matching how other list filters
already compose with --ready. `--status all` remains the no-filter
spelling and keeps the open default.

* fix(list): status-aware --ready footer and honor-path contract docs (#5832)

The query intersection from the prior commit is unchanged. Round-1
review asked the ReadyFlag/Statuses contract comments and the text
footer to describe the honor path: default --ready is still open,
an explicit --status is named instead of "excludes in_progress".

(cherry picked from commit f5a20fb66b)

* fix(doctor): ignore the generated dolt-server-config.yaml (#5978)

doltserver.Start() writes .beads/dolt-server-config.yaml when the resolved
dolt binary supports auto_gc_behavior.archive_level. Its own doc comment
says the file "lives alongside the other gitignored server state files in
beadsDir", but the hyphenated name falls outside the "dolt-server." prefix
shared by the other five entries, so both GitignoreTemplate and
requiredPatterns missed it.

The file holds an absolute cfg_dir and a per-machine port, so committing it
breaks every other clone -- the same reason the template already gives for
'redirect'. It shows up as untracked in every consumer repo whose dolt
supports archive_level. This repo does not see it because its own root
.gitignore has a blanket .beads/* rule.

Add the pattern to requiredPatterns as well as the template: the template
only helps repos initialised after this change, while requiredPatterns is
what missingGitignorePatterns() iterates, so it is what lets bd doctor --fix
append the rule to an existing .beads/.gitignore.

Co-authored-by: Adam Spiers <ai@adamspiers.org>
(cherry picked from commit 671db6560d)

* fix(storage): stop recommending an inert config.yaml key for a missing prefix (#5936)

ReadConfigPrefix gates on the database's config table row `issue_prefix`.
When that row is absent its error told the operator that, "if using
config.yaml, use key 'issue-prefix', not 'issue_prefix'" — but this gate
never consults config.yaml. The YAML value is read one line above the
error solely to populate a debug.Logf diagnostic; it is discarded, so
setting `issue-prefix` in config.yaml leaves the gate failing exactly as
before. Following the advice produces a tracked config field that changes
nothing and misleads the next reader.

Point the message at what actually writes the row — `bd init --prefix` or
`bd bootstrap`, both of which it already named — and say plainly that the
check reads the database's config table so the config.yaml key does not
satisfy it. No resolution behavior changes; this is the error text only.

Reported-by: @ncljesus
Closes #5916

(cherry picked from commit 61ec85181f)

* fix(create): say --file is one issue per ## heading (#5921)

bd create --file/-f is a batch-import route: it creates one issue per
H2 ("##") heading, and ### subsections attach fields to that issue.
The old Usage was "Create multiple issues from markdown file", which
never named those semantics or --body-file. Callers who wanted "one
issue, description loaded from a file" reached for the shortest flag
and got a silent bulk import instead -- reported by @seanmartinsmith
with a 3-section briefing file (## Problem / ## Context / ##
Acceptance Criteria) that became 3 issues instead of one.

gatherCreateInput already rejects a positional title combined with
--file. That is the reporter's literal repro, so this keeps the
rejection and adds a --body-file hint on the error they actually
see. The remaining trap -- --file used alone on a section-headed
file -- is unchanged, because bd cannot tell that apart from a
genuine batch file by content.

Tests: parseMarkdownFile reproduces the trap file; gatherCreateInput
locks in the title+--file rejection and --body-file hint; flag Usage
names the per-heading behavior. The existing TestCreateFromMarkdownFile
binary path already covers well-formed --file creates.

(cherry picked from commit 67b066b58e)

* fix(list): stop truncation hint padding a blank TTY line (#5927)

printTruncationHint fed surrounding newlines through ui.RenderWarn.
lipgloss treats that as a block, pads the blank lines to the widest-line
width (alignTextHorizontal shortAmount = widestLine - lineWidth), and
drops the trailing newline (GH#5685). The next shell prompt then prints
on the same line as a run of spaces.

Keep the newlines outside RenderWarn so the hint is one colored line
with a real trailing newline. Tests construct an explicitly styled
lipgloss Style so the padded blank-line shape fails if the helper is
reverted.

Fixes #5685.

(cherry picked from commit 766c0bd15a)

* fix(setup/claude): keep settings.json's trailing newline and skip no-op rewrites (#5944)

* fix(setup/claude): keep settings.json's trailing newline and skip no-op rewrites (#5693)

bd setup claude (and bd init, which calls it) marshalled the Claude settings
map with json.MarshalIndent and wrote it unconditionally. MarshalIndent emits
no trailing newline, so every run stripped the one Claude Code's own writes
leave behind, and re-wrote the file even when no hook changed. Because bd init
git-adds .claude/settings.json, that surfaced as a staged diff with no
semantic content.

The same marshal-then-write pattern appears at four call sites in claude.go:
installClaude's settings write and its settings.local.json migration, and
removeClaude's settings write and its settings.local.json cleanup. Fixing one
would have left the bug live in the other three, so both halves are now shared
helpers -- marshalSettings appends the newline, writeSettingsIfChanged compares
against the bytes already on disk and returns early when they match -- and all
four sites go through them.

Reported by @maphew.

* chore(setup/claude): use the repo spelling "marshaled" in the new comments

The misspell linter flags British "marshalled"; CI pins golangci-lint
v2.10.1 and runs it with --new-from-merge-base, so both new comment lines
are in scope. Comment text only, no behaviour change.

(cherry picked from commit cad7e17d70)

* fix(gate): evaluate cross-rig bead gates via prefix routes (#5859)

* fix(gate): route cross-rig bead checks (#5857)

Evaluate historical rig:bead gate targets through the current read-only prefix routing seam in direct and proxied-server modes. Preserve local bead gates, reject malformed cross-rig values, and cover the real two-store route with a Dolt integration test.

Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Klas Hesselman

* fix(gate): address cross-rig review feedback (#5857)

Preserve the original local not-found error when prefix routing is unavailable, document the user-visible behavior, and lock the proxied error contract with a regression test.

Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of Klas Hesselman
(cherry picked from commit cbfc505e39)

* fix(storage/uow): retry transient ping failures during openDB bootstrap (#6003)

* test(uow): red — pingWithRetry does not exist yet for openDB's boot-time ping

Adds TestPingWithRetryRecoversFromATransientBadConn (be-x49l6): a fake
pinger exercising three cases — transient error retries then recovers,
non-transient error fails without retrying, and an already-cancelled
context fails promptly. Fails to compile until pingWithRetry/pinger
are added to dolt_sql_provider.go.

* feat: green — Fix: unretried ping in uow openDB turns a transient Dolt connection drop into a hard CI failure (refs be-x49l6)

* refactor: drop what-comment on pingWithRetry (self-review, refs be-x49l6)

Self-review flagged it as restating the function's own signature/behavior
rather than explaining a non-obvious why; the pinger and
isTransientPingError comments stay since they carry rationale the code
doesn't otherwise convey.

* test(uow): red — a hung boot ping is not bounded per attempt

Adds the two behaviours review #6003 asked for, both failing:

  - a_hung_ping_is_capped_per_attempt_and_retried: blockingPinger stalls
    until its context is cancelled. backoff.Retry bounds only the gap
    between attempts, so with the caller's context handed straight to
    PingContext the call never returns at all. The subtest runs the call
    off-goroutine so this reports as "never returned" instead of a
    package timeout.
  - connection-level_net_error_retries_then_recovers: a *net.OpError
    (connection refused / reset / broken pipe) is currently classified
    non-transient and fails the boot ping outright.

the_caller's_own_deadline_fails_without_retrying passes already and is
kept as the regression guard for the trap #6000 fell into: making
context.DeadlineExceeded retryable must not make the caller's own expiry
retryable too.

pingWithRetry takes attemptTimeout here but does not honour it yet, so
the red is behavioural rather than a compile error.

Refs be-g1i7n.

* fix(uow): bound each boot ping attempt and widen the transient classifier

Review #6003, point 1. backoff.Retry bounds the gap between attempts but
cannot interrupt one in flight, and the DSN sets a dial Timeout (5s) with
no ReadTimeout — so a server that accepts TCP and then stalls
mid-handshake blocked for the caller's entire context, which is the exact
scenario the PR summary claims to fix.

Each attempt now runs under its own context.WithTimeout
(pingAttemptTimeout, 10s — above the 5s dial timeout so a real dial
timeout still surfaces as itself), and context.DeadlineExceeded is
classified transient so the retry loop actually continues.

pingWithRetry checks the caller's context *before* classifying. That is
what keeps the retryable DeadlineExceeded from swallowing the caller's
own expiry — the inverse of the regression #6000 introduced by capping
each attempt and then treating the resulting DeadlineExceeded as
permanent. Covered from both sides:
a_hung_ping_is_capped_per_attempt_and_retried and
the_caller's_own_deadline_fails_without_retrying.

Review #6003, point 2. isTransientPingError stays separate from
internal/storage/dolt's isRetryableError, and now says why in full: that
one is a query-time classifier matching on error text, admitting
migration-lock, read-only and MySQL-1105 shapes a boot ping cannot be in
because nothing has executed on the connection yet. The coverage gap the
review named is closed on this side instead — *net.OpError is transient,
which is refused/reset/broken-pipe portably and by type rather than by
substring, with permanent DNS failures excluded so an unresolvable host
still fails fast instead of spending the whole budget.

Refs be-g1i7n.

(cherry picked from commit c0d8da42de)

* fix(deps): bump dolt/go past upstream manifest-missing-chunk defense (#4070) (#5931)

* fix(deps): bump dolt/go past upstream manifest-missing-chunk defense (#4070)

Pin github.com/dolthub/dolt/go to 796d074977417da931df65202a79e0a7f532a3db.
That hop includes:

- 23ccbf9442275166f168939277a5b4a348a63c9d — reject a file manifest
  update that references a missing table file (the defense itself)
- 796d074977417da931df65202a79e0a7f532a3db — doc/test follow-up to the
  defense commit (no production-semantics change)

A non-atomic backup sync can leave the backup manifest ahead of chunk
files; subsequent syncs then fail with "table file not found" and stay
broken. The upstream defense turns that silent corruption into a loud
failed sync. Beads' previous pin (a6690826d767, 2026-07-15) predates
both commits.

Minimal-churn pin: do not bump to today's dolt tip. go mod tidy did not
force a later version.

This is a mitigation, not a root-cause fix: backup file+manifest publish
remains non-atomic, and backups already in the manifest-ahead state are
not repaired by this change.

Mitigates #4070

* fix(nix): update vendorHash for the dolt/go bump

The go.mod/go.sum bump in this PR invalidates the pinned vendorHash, so
`nix build .#default` fails with a fixed-output hash mismatch. Update it to
the value CI computed:

  specified: sha256-D+KDoLFJHpt9D9rCrtE3NMfL4fgK7UxpdKlCxp5yz5Y=
  got:       sha256-wDU1tw/4t2CetwQl4+zUhlDI70dSasLLI2Gy66ZyhQQ=

The repo documents this coupling in .github/dependabot.yml; the existing
"Update vendorHash for dependabot Go bumps" workflow only fires for
dependabot PRs, so a manual bump is needed here.

(cherry picked from commit 851aa2f20a)

* docs(changelog): record the 1.3.1 cherry-pick behaviour deltas

Documents all eleven picks under the existing `## [1.3.1]` heading. The
six behaviour deltas go under Changed, including the two that are not
pure wins and that a user is most likely to hit without knowing why:

  - bd doctor now warns on every pre-existing workspace until --fix
    appends the new .beads/dolt-server-config.yaml gitignore rule.
  - opening a store against a dead server takes up to ~30s to fail
    instead of failing instantly, because the boot ping is retried.

Also called out as non-obvious: the ready set grows where custom
active-category statuses exist, bare --wisp-type becomes a refusal
rather than an empty success, and the Dolt bump converts a quietly
corrupting backup sync into a loud failing one without repairing
backups already in that state.

The dated `## [1.3.0]` section is shipped and is left byte-identical:
the diff is 165 insertions and 0 deletions, and the [1.3.0]-to-EOF
region still hashes to 798a2ee0b0f0b7a3f0fc017ae01c919807740348a34f5ea8719b82a008533d00.
The `## [1.3.1]` date is left for a later release prep to restamp.

* fix(nix): recompute vendorHash for the release-branch dependency set

The #5931 cherry-pick (510675948) bumps four dolt module pins, which
invalidates the pinned vendorHash. Neither side's value was usable: the
release branch already carried its own dependency bump (d594092eb), so
this pick lands on a vendor set that has existed on neither release/1.3.0
nor main, and #5931's own hash was computed against main's graph.

Taken from the `got:` value the nix-build lane reported for this branch:

  specified: sha256-wDU1tw/4t2CetwQl4+zUhlDI70dSasLLI2Gy66ZyhQQ=
  got:       sha256-DQdauEx5g48Xbxrz4wGLx4vkrQoYQX3FUx+7N/Y6YV4=

go mod tidy after the pick was a no-op, and the dependency delta against
the release tip is exactly the four intended pins, so this hash covers
that change and nothing else.

* docs(changelog): scope the #6003 open-latency entry and correct its bound

The 1.3.1 entry for the openDB bootstrap-ping retry said "up to ~30s" and
named no topology. Both were misleading:

- 30s is the retry BUDGET, not the wall-clock bound. backoff stops
  scheduling new attempts at 30s (MaxElapsedTime, dolt_sql_provider.go)
  but cannot cancel one in flight, and pingAttemptTimeout caps an attempt
  at 10s — so a single open can take ~40s. openAndInitSchema pings twice,
  each with a fresh budget, so the narrow case where the backend satisfies
  the first ping and the schema init and is then unreachable for the
  second reaches ~80s.

- Only unit-of-work provider construction takes that ping, which is a
  minority of topologies: proxied-server (local and external) on every
  command, plus `bd serve` in server/external-server/shared-server
  workspaces, which funnels through newSQLServerUOWProvider. Embedded
  never reaches it (bd serve refuses embedded outright), and an ordinary
  CLI command in a server or shared-server workspace opens a DoltStore
  that takes no such ping. An embedded reader of the old entry would have
  triaged a slowdown that cannot affect them.

CHANGELOG only; the dated [1.3.0] section is unchanged (verified
byte-identical, sha256 798a2ee0…, 9169 lines).

---------

Co-authored-by: Vishnu J <vishnuj81093@gmail.com>
Co-authored-by: Karel Bourgois <karel@voxist.com>
Co-authored-by: Adam Spiers <github@adamspiers.org>
Co-authored-by: Adam Spiers <ai@adamspiers.org>
Co-authored-by: swedeinasia-flow <klas@flownetworks.io>
Co-authored-by: Jim Wordelman <jim@wordelman.name>
2026-09-21 00:23:37 -07:00

641 lines
32 KiB
Go

package issueops
import (
"context"
"time"
"github.com/steveyegge/beads/internal/types"
)
// IssueWithCounts is one row of a work page: the issue plus its relationship
// cardinalities.
type IssueWithCounts = types.IssueWithCounts
// IssueDetails is one issue with its labels, edges and cardinalities.
type IssueDetails = types.IssueDetails
// MolType classifies a molecule.
type MolType = types.MolType
// WispType classifies an ephemeral record.
type WispType = types.WispType
// ReadyRequest describes one ready-work query.
//
// It is a HIGH-LEVEL request, not a filter: normalization, alias expansion,
// validation and defaulting all happen inside the implementation. A caller
// that wants ready work says what it wants, never how the query is shaped —
// which is the whole reason two front doors cannot answer this question
// differently.
type ReadyRequest struct {
// IssueType restricts the type. Only shorthand alias expansion is applied
// (mr, feat, mol, enhancement, dec, adr); an unrecognized type matches
// nothing rather than failing. Setting it drops the default type
// exclusions, ExcludeTypes included.
IssueType string
// Assignee restricts to one actor. Unassigned wins over a stale Assignee.
Assignee string
// Unassigned restricts to rows with no assignee.
Unassigned bool
// Labels must ALL be present; LabelsAny requires at least one;
// ExcludeLabels must be absent. All three are raw: normalization happens
// inside.
Labels []string
LabelsAny []string
ExcludeLabels []string
// LabelPattern is a glob and LabelRegex a regular expression, both matched
// against labels.
LabelPattern string
LabelRegex string
// Priority is an exact priority. It is a pointer because 0 is a real
// priority: a value-plus-flag pair would let one half be filled in without
// the other, and P0 has already been lost that way once.
Priority *int
// ParentID restricts to recursive descendants of one issue.
ParentID string
// MolType restricts to one molecule type.
MolType *MolType
// IncludeDeferred admits rows whose defer_until is still in the future;
// IncludeEphemeral admits wisp-plane rows.
IncludeDeferred bool
IncludeEphemeral bool
// ExcludeTypes names types to exclude. Entries may be comma-separated;
// splitting and alias expansion happen inside. Ignored when IssueType is
// set.
ExcludeTypes []string
// MetadataFields is a top-level metadata equality filter and
// HasMetadataKey a top-level key-presence filter. Keys are validated
// inside.
MetadataFields map[string]string
HasMetadataKey string
// Sort is the ready ordering: hybrid, priority or oldest. Empty resolves to
// hybrid at the storage layer, which no front door should rely on — both
// surfaces send a concrete policy, because hybrid demotes older
// high-priority work and therefore changes the item SET once Limit
// truncates.
Sort string
// Limit bounds the page. Nil means the shared ready default; 0 means
// unlimited. It is a pointer so that "unset" and "explicitly unlimited"
// stay distinguishable, which is what lets one constant serve both
// surfaces.
Limit *int
// Offset skips the first N matching rows, on EVERY implementation. The
// page a caller receives is the rows at positions [Offset, Offset+Limit)
// of the answer the same request returns unpaged, in the same order.
//
// WHERE the skip happens is not a backend's choice either. One seam
// renders OFFSET and one renders LIMIT without it, so both bodies reach
// past the skipped rows and drop them in the shared page epilogue
// (internal/workapi.FinishPageAt) — which is also the only sequence that
// is right for a sort SQL cannot express, since that order first exists
// after the fetch.
//
// An Offset past the end of the result set is an empty page and a nil
// error, not a failure: a pager that walks off the end has its answer.
//
// A ready request carries no keyset position, so there is no portable way
// to page ready work. A caller that must page across backends pages a
// ListRequest instead — see ListRequest.Offset.
Offset int
// Brief drops the free-form text from every row: Description, Design,
// AcceptanceCriteria, Notes, Payload and Waiters come back zero-valued and
// the row carries types.Issue.IsLitePartial. See ListRequest.Brief, which
// is the same knob on the other operation and carries the full contract.
Brief bool
}
// ListRequest describes one issue-list query.
//
// Like ReadyRequest it is high-level: the default
// status/pinned/template/gate/infra exclusions, type validation, status
// parsing and limit defaulting are all applied inside.
//
// PINNED is TWO exclusions rather than one, because a row can be pinned two
// unrelated ways and each is hidden by its own predicate. The `pinned` STATUS
// is one of the statuses the default status exclusion covers, alongside
// `closed`; the separate Pinned FLAG — a marker on a row of any status — is
// hidden by a predicate of its own. A row carrying either is absent from a
// default listing, and the knob that takes each back off is a different one:
// see Status for the first and PinnedFlag for the second.
type ListRequest struct {
// Status selects statuses; one name, or a comma-separated OR set. Setting
// it REPLACES the default exclusions rather than fighting them.
//
// It replaces the STATUS ones only. The pinned-flag predicate survives it,
// so `pinned` and `hooked` are the two spellings that also drop that
// predicate — every other status narrows to unflagged rows.
Status string
// IssueType is validated against the workspace vocabulary — unlike
// ReadyRequest.IssueType, which matches nothing rather than failing.
IssueType string
Assignee string
TitleSearch string
SpecPrefix string
// IDFilter is a comma-separated id set.
IDFilter string
Labels []string
LabelsAny []string
ExcludeLabels []string
LabelPattern string
LabelRegex string
TitleContains string
DescContains string
NotesContains string
ExternalContains string
ExternalRef string
CreatedBefore *time.Time
CreatedAfter *time.Time
UpdatedAfter *time.Time
UpdatedBefore *time.Time
ClosedAfter *time.Time
ClosedBefore *time.Time
DeferAfter *time.Time
DeferBefore *time.Time
DueAfter *time.Time
DueBefore *time.Time
EmptyDesc bool
NoAssignee bool
NoLabels bool
SkipLabels bool
// SkipCounts suppresses the CARDINALITY hydration exactly as SkipLabels
// suppresses the label one: DependencyCount, DependentCount and
// CommentCount come back ZERO, and a caller must read a zero as UNKNOWN
// rather than as none. Nothing else about the page moves — the rows, their
// order, Parent and the has-more verdict are what they would have been —
// because this chooses what is HYDRATED, never which rows match.
//
// It is here for the renderings that print a page without those three
// numbers. Each is its own aggregate join, and the reverse-blocker one is
// the expensive member: it joins on an expression the embedded engine's
// planner cannot index, which is the per-call cost that makes a counted
// page the wrong shape for a listing that shows no counts.
//
// Like SkipLabels it is NOT carried onto the ReadyFlag arm; the counts are
// hydrated there either way, which costs time and not correctness.
SkipCounts bool
// Brief suppresses the FREE-FORM TEXT the way SkipLabels suppresses labels
// and SkipCounts the cardinalities: Description, Design,
// AcceptanceCriteria, Notes, Payload and Waiters are not selected and come
// back zero-valued. Nothing else about the page moves — the rows, their
// order, Parent and the has-more verdict are what they would have been —
// because this chooses what is HYDRATED, never which rows match. A
// predicate over a heavy column (DescContains, NotesContains, EmptyDesc)
// keeps selecting exactly the rows it selects today: WHERE is independent
// of the SELECT shape.
//
// A BLANK FIELD IS AMBIGUOUS ON THE WIRE and the row says so in process:
// all six are omitempty, so a projected row marshals identically to a
// genuinely textless one, and the row carries types.Issue.IsLitePartial to
// tell them apart for an in-process caller. That flag is json:"-", so a
// wire consumer distinguishes them by having asked — the same shape the
// repo has already argued about twice (ga-clgh/CommentsOmitted, #5550).
//
// UNLIKE SkipLabels and SkipCounts it IS carried onto the ReadyFlag arm,
// and onto ReadyRequest.Brief beside it. Those two drop a NUMBER the ready
// renderings print; this drops a body no listing prints, so carrying it is
// what makes `--ready` and `bd ready` answer the same request the same way.
//
// It is the storage layer's types.IssueFilter.Lite / types.WorkFilter.Lite
// under the name the CLI and the MCP integration already use for a
// projection (bd show --brief-deps, the MCP's brief).
Brief bool
// Priority is exact; PriorityMin and PriorityMax bound a range. All three
// are pointers for the same reason ReadyRequest.Priority is.
Priority *int
PriorityMin *int
PriorityMax *int
// PinnedFlag and NoPinnedFlag select on the Pinned FLAG, which is not the
// `pinned` status — see this type's own doc for why there are two of them.
//
// PinnedFlag answers with the FLAGGED rows and only them, at any status: it
// drops the default status exclusions on the way, so a closed pinned row —
// which a default listing hides twice over — is in that answer.
//
// NoPinnedFlag asks for the UNFLAGGED rows, which a default listing already
// answers with. Its work is holding that predicate in place where AllFlag
// or a pinned/hooked Status would otherwise have dropped it, so on a
// default listing it changes nothing and on those it narrows.
//
// On the ReadyFlag arm neither applies: that set decides pinned for itself,
// which is why PinnedFlag is refused there and NoPinnedFlag merely accepted
// (see AllFlag).
PinnedFlag bool
NoPinnedFlag bool
IncludeTemplates bool
IncludeGates bool
IncludeInfra bool
// IncludeEphemeral admits the EPHEMERAL PLANE — the wisps TABLE, which a
// default listing does not read at all — and admits nothing else.
//
// WHAT IS IN THAT PLANE is not only true ephemerals. The wisps table holds
// every row the durable plane does not: wisps proper (ephemeral = 1) AND
// no-history rows, which live there with ephemeral = 0. Both arrive
// together, because this selects a TABLE rather than testing a column.
//
// False, the zero value, is the listing every caller has today: the durable
// issues table alone. True merges the wisps table IN ADDITION, so under the
// same filters the answer is a SUPERSET of the false answer. It never
// narrows, and it never becomes ephemeral-only.
//
// IT IS NOT THE SAME MECHANISM AS ReadyRequest.IncludeEphemeral, despite
// the shared name and the shared "admit in addition" reading, and the
// difference is observable. The ready query reads BOTH planes either way
// and its flag adds a per-ROW predicate (ephemeral = 0) when unset; this
// one selects which TABLES are read at all. So a no-history row — in the
// wisps table with ephemeral = 0 — is already in a DEFAULT ready answer and
// is absent from a default listing until this flag is set. Match the two
// fields for intent, never for row-level equivalence.
//
// IT IS A PLANE KNOB, NOT A TYPE KNOB — the difference from the three
// fields above it. Each of those takes a TYPE exclusion back off; this
// takes none off, so an ephemeral row whose type a default listing already
// excludes stays excluded. THAT INCLUDES THE INFRA TYPES, which is the
// combination most likely to surprise: the configured infra vocabulary
// (agent, role and message by default) is excluded by TYPE, so ephemeral
// agent/role/message rows need IncludeInfra as well as — or instead of —
// this. IncludeInfra does BOTH, which makes it strictly wider; what this
// field alone reaches is the ephemeral rows of the types a listing already
// shows.
//
// THE MERGED ANSWER IS ONE ORDER. Both planes are ordered together by
// SortBy as if they were a single table — not the durable rows followed by
// the ephemeral ones — so a Limit truncates the merged order rather than
// one plane's. Both implementations produce it (one merge-sorts two ordered
// legs, the other ORDERs a SQL union), and the keyset position
// (AfterCreatedAt/AfterID) is applied to BOTH legs, so a paged walk over
// the merged order drops no row and repeats none.
//
// The caveat that walk inherits is the one every multi-page walk already
// has, and this does not deepen it: a page is not a snapshot. A row written
// — or, for a wisp, compacted away — between two pages is seen or missed
// according to where it falls relative to the position, and the ephemeral
// plane merely turns over faster than the durable one.
//
// On the ReadyFlag arm it is CARRIED rather than dropped; see that field.
IncludeEphemeral bool
// IncludeAllTypes lifts every default suppression that hides a bead from a
// listing on account of WHAT IT IS: the three type knobs above (templates,
// gates, infra types) AND the ephemeral plane, so the wisps table is read
// too. Frontends whose contract is "never hide a bead" — `bd human list`,
// where a human label is an explicit request for a person's attention —
// set this one field instead of enumerating the knobs and then drifting
// from them when a fourth suppression lands.
//
// IT IS THE UNION OF THOSE FLAGS, NOT A NEW MECHANISM. Setting it is
// equivalent to IncludeTemplates + IncludeGates + IncludeInfra +
// IncludeEphemeral; it narrows nothing and admits nothing they cannot.
// Both the type suppressions and the plane decision live in workapi's
// applyTypeSuppressions, which this flag skips entirely — so a suppression
// added there is lifted here automatically, which is the whole point.
//
// IT SAYS NOTHING ABOUT STATUS. The done/frozen exclusions and the pinned
// default are a separate axis and still apply; --status (including "all")
// is how a caller lifts those.
IncludeAllTypes bool
// ExcludeTypes entries may be comma-separated; splitting happens inside.
ExcludeTypes []string
ParentID string
NoParent bool
MolType *MolType
// WispType matches the wisp_type COLUMN, which both tables carry. It is
// therefore a predicate and not a plane selector: it does not admit the
// ephemeral plane, and on a default listing — where that plane is
// suppressed — it narrows the durable rows to those whose wisp_type
// matches, which no ordinary durable row has. The combination that answers
// with rows is IncludeEphemeral (or IncludeInfra) plus this, and it is
// lawful rather than refused: the two compose as an ordinary AND, admitting
// the plane and then narrowing it to one classification.
WispType *WispType
DeferredFlag bool
OverdueFlag bool
// MetadataFields is a top-level metadata equality filter and
// HasMetadataKey a top-level key-presence filter. Keys are validated
// inside, as they are for ReadyRequest.
MetadataFields map[string]string
HasMetadataKey string
// AllFlag drops the default status exclusions.
//
// ReadyFlag switches the query to the blocker-aware ready set. It does NOT
// simply add a blocker predicate to this listing: that query reads a
// narrower filter vocabulary than this request can describe, and only part
// of the request reaches it.
//
// WHAT IT CARRIES: Status/Statuses (an explicit --status is the
// intersection; AllFlag and `--status all` still take the open default),
// IssueType, all five label forms, Assignee, NoAssignee,
// the exact Priority, ParentID, MolType, WispType, MetadataFields,
// HasMetadataKey, the type exclusions (ExcludeTypes, and with them
// IncludeGates and IncludeInfra), IncludeEphemeral — the ready query has an
// ephemeral gate of its own, so the plane bit crosses intact and
// IncludeInfra's plane half crosses with it — Limit, Offset and the MaxRows
// cap with its attribution. SortBy and Reverse
// still apply, because the display order is applied to the page after the
// query rather than inside it.
//
// WHAT IT REFUSES: every other filter here is one the ready query cannot
// carry, so combining it with ReadyFlag returns ErrValidation naming the
// fields rather than answering a wider question than was asked. That is
// IDFilter, TitleSearch, SpecPrefix, the four *Contains fields,
// ExternalRef, every Created/Updated/Closed/Defer/Due bound, DeferredFlag,
// OverdueFlag, EmptyDesc, NoLabels, NoParent, PinnedFlag, PriorityMin,
// PriorityMax, and the keyset position. There is no fallback: no
// combination of the two silently widens the answer.
//
// TWO THINGS THE READY SET DECIDES FOR ITSELF, which no field here
// overrides. It never returns pinned issues, which is why NoPinnedFlag is
// accepted and PinnedFlag refused. And it applies no template predicate at
// all, so this request's default template exclusion does not reach it and
// IncludeTemplates changes nothing here: a template is left out of a
// ReadyFlag listing only when its issue type is one the ready query
// already excludes. SkipLabels and SkipCounts are likewise not carried —
// labels and cardinalities are hydrated either way, which costs time and
// not correctness.
AllFlag bool
ReadyFlag bool
// SortBy names the display order and Reverse inverts it. A sort the
// database cannot express (natural-numeric id order) is resolved inside by
// fetching the full result set and trimming, so no caller has to know
// which sorts those are.
SortBy string
Reverse bool
// Limit bounds the page the caller RECEIVES. Nil means the shared list
// default; 0 means unlimited. The row limit actually pushed into the query
// is derived from it inside the implementation, together with the
// over-fetch that detects truncation.
Limit *int
// Offset skips the first N matching rows, on EVERY implementation, and the
// page is the rows at positions [Offset, Offset+Limit) of the answer the
// same request returns unpaged. See ReadyRequest.Offset for where the skip
// is applied and why that is not a backend's choice either.
//
// THE PORTABLE WAY TO PAGE IS THE KEYSET POSITION below,
// AfterCreatedAt/AfterID: every implementation honors it, and it does not
// skip or repeat rows when the result set changes underneath a walk.
// Offset is here for the surfaces that already published it.
Offset int
// AfterCreatedAt and AfterID carry a decoded keyset position in the
// (created_at DESC, id ASC) order. The opaque token that encodes them is a
// transport concern and never reaches this contract.
//
// AfterPriority EXTENDS that position to the (priority ASC, created_at
// DESC, id ASC) order — the order SortBy="priority" and the empty default
// render — and is honored by every implementation, on BOTH tier legs, the
// same way the pair above is. It is the same position and not a second
// one: AfterCreatedAt alone decides whether one was supplied, so a
// priority with no instant is ignored exactly as an AfterID with no instant
// is.
//
// SET IT ONLY UNDER THE ORDER IT NAMES. A priority position under
// SortBy="created" positions in an order the ORDER BY does not render, and
// the page that comes back is a walk through rows neither side agrees on.
// The order the request asks for and the order the position was minted in
// are one decision; the transport above this contract is what keeps them
// from drifting.
AfterCreatedAt *time.Time
AfterID string
AfterPriority *int
// MaxRows is a DEFENSIVE CAP rather than a page. It bounds how many rows
// the query may match before the whole answer is refused; 0 disables it.
// A request whose result set exceeds it comes back as
// *internal/storage/issueops.ErrTooManyRows — carrying the count observed,
// the cap, and MaxRowsSource's attribution — and NO PAGE. That is the
// difference from Limit, whose overflow is an ordinary truncated page with
// HasMore set. It is a circuit breaker for a caller that would rather fail
// than wait. The type is named here rather than left as "an error" so a
// caller can tell the cap firing from any other failure with errors.As;
// this leaf does not import it, and no answer depends on that.
//
// EVERY IMPLEMENTATION HONORS IT, and they agree on when it fires: when
// the query matched more rows than the cap allows AND the window the
// request asked the query to TOUCH could have exceeded it. THAT WINDOW IS
// Limit+Offset, NOT Limit. A row Offset skips is a row the query matched,
// so an offset walks a caller toward the breaker and never past it: a cap
// of Limit+Offset or looser never fires, because a query bounded to that
// many rows cannot break it, and one more row of offset is what flips the
// same request to a refusal. The two seams size that window through one
// function (internal/storage/issueops.SearchProbeLimit) so they cannot
// disagree about the boundary.
//
// Unlike SkipCounts and SkipLabels it IS carried onto the ReadyFlag arm.
MaxRows int
// MaxRowsSource attributes the cap to whatever knob set it — "--max-rows",
// "BEADS_MAX_ROWS", or empty for a library caller — and that attribution is
// what the refusal text reads back. It decides no answer: a request is
// refused on MaxRows alone, and this only decides how the refusal reads.
MaxRowsSource string
}
// GetRequest describes one issue-detail lookup.
type GetRequest struct {
// ID is the exact canonical id. There is no fuzzy, prefix or substring
// resolution here: an interactive affordance that can resolve to a
// different issue than the caller named has no place on a contract two
// front doors share. The issue-to-wisp fallback DOES happen inside.
//
// THAT FALLBACK NEEDS NO PLANE ORDER, and this contract deliberately
// states none: no LOCAL WRITE PATH can make an id resident in both planes,
// so the state an order would arbitrate is not reachable by writing
// through this library. Every local write path closes it. A guarded create
// probes BOTH tables before inserting
// and answers ErrAlreadyExists for an id either one already holds. Every
// batch create — import, a graph apply, a cooked formula, a markdown
// import — refuses on top of that an id already resident in the SIBLING
// table, skipping the row rather than hard-failing only on the
// auto-import recovery path, which leaves the resident row alone.
// Promotion and demotion insert into the target plane and delete from the
// source inside ONE transaction, so their dual-presence window never
// commits. This is why the implementations are free to probe the planes in
// either order, and why they in fact differ — a documented non-issue
// rather than a latent divergence (bd-yby99.22).
//
// TWO CAVEATS ARE WORTH CARRYING, and the second is the load-bearing one.
//
// First: the graph-apply path served by a unit-of-work provider gets its
// refusal from a preflight ABOVE storage rather than from the create
// guard, so a future caller that reached the graph-apply use case directly
// would be the thing that made this reachable.
//
// Second, and NOT closed by anything here: REPLICATION. The durable plane
// merges from a remote on pull, the ephemeral tables are dolt-ignored and
// local-only, and no post-merge check reconciles the two — the collision
// guard is reachable only from the create path. So a clone holding a wisp
// whose id another clone promoted to durable receives that id into the
// issues plane while its own wisp row survives. That needs a deterministic
// id to collide at all, which explicit-id creates and the identically
// minted infra wisps supply. It is a REAL residual path, it is outside
// this library's reach, and the resulting state is worse than an
// unspecified plane order: the merge-based lookups behind ready and search
// hard-error for the whole store. A plane order here would not rescue it.
//
// So the honest statement is the scoped one — no local write path reaches
// dual residency, replication can, and a caller that hits it has a
// corrupt store rather than an ordering question (bd-yby99.22).
ID string
// IncludeDependents and IncludeComments populate the two expensive row
// lists. Both default off: the detail view carries counts, and a caller
// that wants the rows asks for them.
IncludeDependents bool
IncludeComments bool
// BriefDeps reduces each dependency to its identity-and-shape fields.
BriefDeps bool
}
// IssuePage is one page of work. Ready and List share it deliberately: both
// surfaces of both operations emit IssueWithCounts today, and a leaner page
// type for ready would drift at the field level the moment anything compared
// the two.
type IssuePage struct {
// Items is the page, in the operation's order. Never nil for a successful
// call.
Items []*IssueWithCounts
// HasMore reports that the limit truncated the result.
HasMore bool
}
// Reader describes guarded issue queries: the read counterpart of Lifecycle,
// and — like Lifecycle — a role with its own accessor. A new capability gets a
// new role interface and its own accessor; never append a method here.
//
// Each method takes the whole request and performs filter and default
// construction INTERNALLY. A caller of this interface can only say
// rd.List(ctx, req): the four-step ritual of building a config source, loading
// config, building a filter and executing it is not reachable through it.
// Implementations never mutate caller-owned request values.
//
// WHERE THAT IS ENFORCED, precisely, because the difference matters:
//
// - The HTTP surface is on the role for all three of its issue reads, and
// two lint rules make writing a filter there a lint failure rather than a
// review comment. THE CLAIM at the bottom of this comment names them, and
// names what they cover and what they do not.
//
// - `bd show --json`'s DETAIL VIEW is on the role on BOTH routes: the direct
// one reaches it through store.IssueReader(), the proxied one through the
// unit-of-work provider's accessor. Its ALTERNATE views are not, and are
// not the same question: --refs, --children, --thread and --as-of each
// answer with their own shape, which this contract does not describe and
// no HTTP operation serves. --short is not either; it prints one line from
// the issue, not a detail view.
//
// The shared implementation behind the store accessor
// lives in internal/workapi/storereader, which the
// cmd-bd-role-constructors depguard rule keeps out of cmd/bd: the
// accessor is where each storage decorator adds its layer, so a command
// that constructed a reader directly would get an unspanned one. `bd show`
// keeps its own id RESOLUTION — fuzzy ids, cross-repo routing, --current —
// and hands this contract the canonical id it resolved, because an
// affordance that can answer with a different issue than the caller named
// has no place on a contract an unattended HTTP client also calls.
//
// - `bd list` IS, on both routes, for its PAGE — every output mode but the
// two named next. --json and every text rendering call List below and
// nothing else; --ready is not a route of its own on either side, it is
// ReadyFlag, and picking the ready query from it is this role's job.
// The two exceptions consume the FILTER as a VALUE and no page can express
// either: --watch re-runs it on a ticker, and the hierarchical --parent
// tree re-parents a copy of it at every level. What is NOT an exception,
// though it looks like one, is the whole-graph dependency-record load
// behind --format and the pretty tree: that is a different question from
// both this role's and BlockingAnnotator's, so those renderings take their
// page from here and load the graph beside it.
//
// The other thing `bd list` used to do here was the per-page blocking
// decoration, which is issueops.BlockingAnnotator's on both routes now —
// its own role, because it is a DERIVED annotation over ids a page already
// chose rather than a page.
//
// - `bd ready` is NOT, on either route, and will not be until there are more
// roles to route it through. It consumes the FILTER itself for --claim,
// --gated, --explain and --mol. Two of its questions HAVE left the filter
// behind, each for the role that owns it: --claim is ReadyClaimer's, and
// the published total is ReadyCounter's, on both routes.
//
// WHAT `bd ready` DOES SHARE, stated exactly, because "not on the role" is not
// the same as "unprotected":
//
// - CONSTRUCTION. Every route, and both implementations of this interface,
// build from these same request types through the same two builders in
// internal/workapi, which the builders' golden files pin.
// - EXECUTION, on the PROXIED route only. The direct route keeps an epilogue
// of its own and cannot give it up: it answers the strictly larger question
// "how many rows did the limit hide" and publishes the total in its
// pagination meta, where this role answers only "were any hidden".
// Collapsing them would change one surface's published output. That second
// question is not off-role, though — it is ReadyCounter's, which both
// routes now ask through their own accessor, over this same ReadyRequest;
// what stays outside this role is the PAGE's epilogue, not the count beside
// it.
//
// THE CLAIM, stated once and in full so it can be checked sentence by
// sentence. SHARED: all three issue reads on the HTTP surface go through this
// role, so does `bd show --json`'s detail view on both its routes, and so does
// `bd list`'s page on both of its — in every mode but --watch and the
// hierarchical --parent tree, which take the filter instead. `bd ready` is not
// on it and shares instead the request types above, the two builders in
// internal/workapi that their golden files pin, and workapi.FinishPage on its
// proxied route only. ENFORCED,
// and by what: depguard (httpapi-transport-boundary) denies internal/workapi
// from every non-test file of internal/httpapi, so no builder is callable
// there, and a forbidigo rule denies naming types.IssueFilter or
// types.WorkFilter there at all, so no filter is writable there either — both
// are directory-scoped with no per-file exception, so a file added to that
// package tomorrow is covered the moment it exists. That same forbidigo rule
// covers cmd/bd deny-by-default with 59 named exceptions, so the files
// implementing `bd list` and `bd show` cannot write a filter, and neither can
// a file they are split or renamed into unless the new name lands on that
// list. NOT ENFORCED: the rule forbids NAMING those types, not holding a
// value, so the property is "no filter is written there", not "every filter
// there came from a builder"; test files are exempt from both rules, because
// the oracles hold filters in order to inspect them; `bd ready`'s files are
// among the 59, since its listing and --claim are handed the filter itself and
// the blocked-issue views in those files name one directly, so it is guarded by
// the builder and the golden files and not by the linter;
// cmd/bd/list_show_filter_modes.go is among them too and STAYS there — the
// count did not drop with this flip, because that file is where `bd list`'s
// two filter-consuming modes and `bd show --current` live and all three still
// need to name the type;
// GET /healthz and GET /v0/beads/context are not issue queries and are on no
// role; `bd ready`'s direct route and `bd list`'s hierarchical tree run
// epilogues of their own; and none of this is a merge gate — the rules run in
// `make ci-pr-lint` on every pull request and aggregate into the ci-gate job,
// but main carries no branch protection beyond deletion and non-fast-forward,
// so no check is GitHub-required and a red gate binds by convention.
//
// Closing the rest needs more roles (a claim role, an explain role), not more
// methods here.
type Reader interface {
// Ready returns unblocked open work in the requested policy's order.
Ready(ctx context.Context, req ReadyRequest) (IssuePage, error)
// List returns issues under the request's filters, in the requested
// display order.
List(ctx context.Context, req ListRequest) (IssuePage, error)
// Get returns one issue's detail view. A miss — for both the issue and the
// wisp table — is ErrNotFound; a backend failure passes through unchanged
// and never decays into not-found.
Get(ctx context.Context, req GetRequest) (*IssueDetails, error)
}