Commit graph

9 commits

Author SHA1 Message Date
Julian Knutsen
8aaefe2d4f
feat(httpapi): serve bd list's order with sort on listIssues (#5666)
* feat(httpapi): serve `bd list`'s order with `sort` on listIssues

The issue listing served one order, `(created_at DESC, id ASC)`, because the
cursor is a keyset position in it. The spec stated the constraint in its own
words: "the sort order is welded to the cursor contract, and a new order needs
new surface." That welding put the cost on every client wanting `bd list`'s
ordering — the only way to get it was to page the whole result set and sort
locally, which is the one cost on this surface that grows with the project.

Measured against a real `bd serve` over 1400 rows at the 200-row page an HTTP
client actually uses: walk-and-sort is 7 requests plus a client-side
comparator, `?sort=priority` is 1. Both are checked against `bd list --json`
row for row, because the claim that matters is not "fewer requests" but "the
same order".

`sort` takes `created` and `priority` and nothing else. Each value is a keyset
contract — a position shape, a strictly-after predicate, an index — not a
display preference, and both keys are provably total (priority and created_at
are non-null, id is unique) so a page boundary inside a run of equal keys
resolves on id. The seven other orders `bd list --sort` takes have no such key:
`id` is natural-numeric and no database expresses it, `updated` moves on every
write, `closed` is nullable, and status/title/type/assignee are mutable and
unindexed. `priority` here is (priority ASC, created_at DESC, id ASC), which is
both `bd list`'s flagless order and what `--sort priority` produces — a stable
priority sort over the created order is the same sequence — so one served order
retires the walk for both.

Absent `sort` still means `created`, permanently: it is the compatibility
contract for every client written before the parameter existed.

THE CURSOR NOW CARRIES ITS ORDER. This is the half that makes the parameter
safe rather than merely useful, and the obvious implementation gets it wrong.
The token was base64 of `{t,i}` with no binding, so a created-order cursor
replayed under `sort=priority` decoded perfectly and was read as a position in
a different total order — a page that skips and duplicates rows, served with a
200, undetectable by the client. Tokens are now `v2` with an explicit order
member, and decode takes the wanted order as a parameter so a mismatch is
unrepresentable at the seam rather than merely detectable past it. Outstanding
`v1` tokens stay readable as the created-order positions they are, so no
traversal in flight has to restart. This does not contradict "the token carries
no filters": filters select the set, the order decides what the position means.

Storage grows one field. IssueFilter.AfterPriority extends the existing
position; the predicate nests the created one rather than restating it, because
the created/id comparison is only reachable at the cursor's own priority.
Flattening it the way the created predicate's leading-bound trick invites looks
equivalent and is not — it re-delivers rows at the cursor's priority created
after it, which the new conformance walk catches against real Dolt.

NO INDEX MIGRATION, by measurement rather than by omission. A composite
(priority, created_at, id) index was tried on Dolt 2.2.0 against the production
predicate, in both the plain ascending and the mixed-direction spelling Dolt's
DDL accepts: the plan is byte-identical in all three cases, keeping the
single-column priority seek and the TopN. It would have bought write
amplification on every insert and every priority update for no measured change.
The sargability guard pins what is achieved — an IndexedTableAccess range on
idx_issues_priority — and records the measurement to redo if Dolt learns to
stream the composite.

Agent-Signature: claude-opus-5
Co-authored-by: CI Bot <ci@beads.test>

* fix(changelog): drop leftover diff3 conflict marker in sort entry

The rebased adopt-PR head left a stray '|||||||' merge-base marker on the first line of the new `sort` CHANGELOG entry (CHANGELOG.md:381), which `git diff --check` flagged as a leftover conflict marker. Remove only the marker line; the resolved entry content is unchanged. Maintainer fixup for PR #5666 adoption review.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-08-27 09:21:12 -07:00
Bee
8301974ecd
fix(sweep): purge/prune select candidates by tier — a typed wisp is ephemeral however it was minted (#5995)
* fix(sweep): select purge/prune candidates by tier, not the raw ephemeral flag

A typed wisp minted without the ephemeral flag was invisible to bd purge:
the candidate filter matched ephemeral=1 alone, and the Ephemeral=true
search route only looks at the wisps plane — so legacy typed wisps in the
issues table (858 rows / 7.3 MB in one production DB) survived every sweep
that existed to delete them, while still reporting 'No closed ephemeral
beads to purge'.

IssueFilter gains EphemeralTier: ephemeral-tier is ephemeral=1 OR a
non-empty wisp_type; the durable tier is the complement, so bd prune stops
silently owning rows purge should. The field deliberately does not take
the wisps-plane-only fast path — a tier query merges both planes, because
the rows that motivated it live in the issues table. NoHistory beads
(wisps plane, ephemeral=0, no wisp_type) stay durable-tier (GH#3649).

The list/ready golden filters gain the new field as null.

* fix(create): a wisp_type implies the ephemeral tier at mint

All three create paths (ExecuteCreate, the batch body, and the dolt
store's own createIssue routing) now infer ephemeral from a non-empty
wisp_type, the same way they already infer it from a configured infra
type — so no new mints produce the flag-less typed-wisp shape the sweep
fix has to catch. NoHistory keeps its own retention mode, as before.

* test(dolt): pin the tier boundary on the legacy typed-wisp shape

Three cases: a manufactured issues-plane row with wisp_type but no
ephemeral flag is taken by the ephemeral sweep and left by the durable
one; a NoHistory bead stays durable-tier; and a create carrying only a
wisp_type lands in the wisps plane marked ephemeral. The first and third
were verified red against their halves of the fix reverted.

* test(sweep): conformance tier-boundary cases + the remaining mint sites

Adds two cases to the sweeper conformance kit, wired in all three backends:

- RunSweeperTreatsALegacyTypedWispAsEphemeralTier — the row shape that
  motivated the fix: a closed issues-plane row carrying wisp_type but not
  the ephemeral flag (858 such rows / 7.3 MB survived every purge in one
  production DB). Manufactured with a raw UPDATE through a new optional
  Exec fixture hook, because every current create path now infers the flag.
- RunSweeperLeavesNoHistoryBeadsToTheDurableTier — the other edge: a
  NoHistory bead (wisps plane, ephemeral=0, no wisp_type) is durable-tier
  (GH#3649) and must survive the widened ephemeral sweep. Seeded through
  CreateWisp because plane routing of NoHistory is the create verb's
  concern and the uow kit's CreateIssue calls the domain-level create.

Also carries the wisp_type→ephemeral mint inference to the five remaining
create sites (uow issue_operations/batch_creator/batch_applier,
embeddeddolt create_issue) and slims the dolt-local typed-wisp test to the
mint case now that the sweep half lives in the conformance kit.

Verified: TestSweeperContract green on dolt (91s), uow (87s), and
embeddeddolt with BEADS_TEST_EMBEDDED_DOLT=1 (76s, 13/13 subtests, no
skips).

* test(sweep): dispatch the two new sweeper cases in roleContractCases

The conformance package's own coverage tripwire
(TestRoleContractCasesCoverEveryContractCase) failed in CI: a role contract
case that no roleContractCases row dispatches is invisible to an external
backend running RunRoleContracts. The legacy typed-wisp case still skips
cleanly on a bundle whose SweeperFixture carries no Exec hook.
2026-08-27 05:06:50 -07:00
Stephanie Jarmak
7e825441b4
feat(workapi,storage): opt-in Brief projection for the list and ready pages (#5554)
STORAGE LAYER ONLY, per CONTRIBUTING_PR_GUIDELINES.md. issueops.ListRequest
and issueops.ReadyRequest gain Brief; no CLI flag and no HTTP parameter sets
it yet, so no front door's payload changes. The wiring stacks on top.

WHAT IT DROPS is the free-form text: description, design, acceptance_criteria,
notes, payload and waiters are not selected, and the row comes back carrying
types.Issue.IsLitePartial. #5546 measured a 16,051-issue store where
`bd ready --json` returned 454,021 bytes and notes plus description were 76% of
it, on the call an agent makes to decide what to work on. Measured through
issueops.Reader on 100 rows sized from those per-row ratios: 362,301 bytes
full, 24,001 brief, a 93.4% reduction.

THE PRIMITIVE WAS HALF-BUILT AND UNREACHABLE. #3906 landed
types.IssueFilter.Lite, IssueSelectColumnsLite, HeavyDropList,
ScanIssueLiteFrom and Issue.IsLitePartial, then wired filter.Lite into exactly
one place: SearchIssuesInTx, the UNCOUNTED store-backed search. Every read that
answers with IssueWithCounts, which is every --json route of both commands,
both implementations of issueops.Reader, and both HTTP reads, runs the counts
mega-query instead and ignored the field. A request that set it would have come
back correct, fully hydrated, and with nothing on it to say the projection had
not happened. That silent no-op is what this closes.

THE APPLICATION POINT IS THE COUNTS MEGA-QUERY, and it is one point rather than
four because sqlbuild.SearchCountsSQL and issueops.ScanReadyWorkRowWithCounts
are already the pair every counted read passes through: the store seam's list
(search_counts.go) and ready (ready_work_counts.go), and the unit-of-work
seam's list (issue_search_counts.go) and ready (ready_work_union.go, via
fetchCountsByIDs). sqlbuild.CountsHydration is already the value that carries
hydration opt-outs across that pair on both seams, so Lite is a third field on
it rather than a new channel.

IT CHANGES THE PROJECTION'S SHAPE, which SkipLabels and SkipCounts do not, and
that is why ScanReadyWorkRowWithCounts now takes the whole hydration instead of
a bool: the value that chose the SELECT list is the value that drives the scan,
so the two cannot be given different answers. Substituting empty strings in the
heavy positions would have kept one scan path and was rejected, because the row
would carry blank text with IsLitePartial=false, which is indistinguishable
from a genuinely textless row, the ambiguity ga-clgh and CommentsOmitted
already record.

WHERE IS INDEPENDENT OF SELECT, so this bounds the size of a row and never
which rows match: DescContains, NotesContains and EmptyDesc keep selecting
exactly what they select today, and no sort key, keyset cursor or wisp-merge
dedup reads a dropped column (CompareIssuesBy orders on nine fields, none of
them heavy).

THE CLAIM REFUSES IT, which is not the same call the page makes and is the
sharper case of the rule Limit and Offset already state. A claim does not read
its row through the page's query at all: ExecuteClaimNext refetches the winning
row whole with GetIssueInTx and hydrates its counts itself, so the projection
has nothing to apply to. Accepting the field would answer a MUTATING request
with a fully hydrated row carrying IsLitePartial=false, the caller's one signal
that it did not get what it asked for, reporting that it did. The check lives
in issueops.ValidateClaimNextRequest, which is the shared rule both ready
claimers and BatchCloser's claim already run, so all four backends refuse it on
the same line.

BuildReadyCountFilter CARRIES it, which is the opposite treatment and the
opposite reason. A count reads no field of any row, so the projection cannot
make the number wrong, and the count is not always cheap enough for that to be
the end of it: the unit-of-work seam has no COUNT(*) over the ready predicate
and sizes the set by running the unbounded page and taking its length
(uow/ready_counter.go), so dropping the field there would hydrate every heavy
column of the whole ready set to answer `bd ready --brief`, a larger read than
the page it was asked for. Carrying it also keeps that builder what its doc
says it is: the listing's filter with the PAGE removed and nothing else.

TWO ASYMMETRIES on the page path, both deliberate and both stated in code:

  - Brief IS carried onto the --ready arm (ReadyFilterFromIssueFilter) where
    SkipLabels and SkipCounts are dropped. Those two hide a number the ready
    renderings print; this drops a body no listing prints, so carrying it is
    what makes `bd list --ready` and `bd ready` answer one request one way.
  - types.WorkFilter carries Lite and neither of the other two, so the ready
    paths get readyHydrationFor rather than hydrationFor. Before this, both
    uow ready call sites passed a hardcoded CountsHydration{}, a literal that
    could not carry a filter's answer at all, which is how that path would have
    been missed.

CONFORMANCE at all four registered sites, one Test per case, for the two page
cases and for the claim refusal. Every field the cases assert stripped is
seeded heavy first and the premise is checked, so a backend that never
round-trips one of the six fails loudly instead of turning that clause into one
that cannot fail. Identity is asserted too (ID, Title, Status, IssueType,
Priority), or a body that stripped the row to its id would satisfy every
emptiness clause. IsLitePartial is asserted in both directions.

THE LITE COLUMN LIST IS PINNED BY ORDER, not only by membership. Both lists are
scanned positionally, so two columns of the same SQL type can be transposed
with no membership change at all: the pre-existing set-based parity test stays
green, the scan succeeds, and every row silently carries one column's value in
another's field. TestIssueSelectColumnsLite_IsFullMinusHeavyInOrder derives the
expected list by deleting HeavyDropList from IssueSelectColumns in place, which
makes the lite list a derivation rather than a second hand-maintained copy.

RED BEFORE GREEN, five sabotages, each verified and reverted:

  - deleting the lite branch from CountsHydration.IssueColumns fails both page
    cases with "expected 58 destination arguments in Scan, not 52";
  - accepting Brief without plumbing it to either filter, the silent no-op this
    change exists to close, fails both page cases on all six text fields and on
    IsLitePartial, which is the run that proves the assertions are
    load-bearing;
  - transposing created_by and owner in IssueSelectColumnsLite fails only the
    new order test, on IssueSelectColumnsLite[9] = owner, want created_by,
    while the set-based test stays green, which is the gap it was added for;
  - dropping the claim's refusal fails the claimer contract with "ClaimNext
    with brief: error = <nil>, want ErrValidation"; and
  - clearing Brief in BuildReadyCountFilter fails
    TestBuildReadyCountFilterIsTheUnboundedReadyFilter, which already existed to
    catch a ReadyRequest field the count builder forgets to carry and gains
    Brief in its fixture here.

The recorded ready-filter golden gains "Lite": false in 62 cases because
types.WorkFilter gained the field and the test compares marshaled JSON
byte-for-byte. False is what a request that did not ask for the projection
resolves that field to, so the replay stays exact; the test comment says so.

Gates: go build ./..., go vet ./..., gofmt, internal/storage/... (dolt,
embeddeddolt with BEADS_TEST_EMBEDDED_DOLT=1, uow, issueops, sqlbuild,
domain/db), internal/workapi/..., backend/conformance/..., issueops/...,
make api-check.

Refs: #5546, #3906

Co-authored-by: sjarmak <t@t.co>
2026-08-10 10:45:23 -07:00
Isis Anisoptera
c8dd08c262
fix(human): respond/dismiss text sources, bd list parity, and proxied-server support (#5333)
* fix(cli): one text-source layer for comment, note, and human respond

`bd comment`, `bd note` and `bd comments add` each read their body text a
little differently, and all three applied a SILENT precedence when a caller
gave two sources: positional text plus --stdin or --file resolved to the flag
and dropped the positional half with no message. In every case we could find,
the dropped half was the text the caller meant.

One textSources layer now owns the reading for all of them. Naming two sources
is an ERROR ("cannot combine positional text ... with --stdin") rather than a
precedence question; --file content is passed through verbatim, matching every
other file-input flag (--body-file, --design-file, --reason-file), while stdin
keeps trimming the trailing newline a shell appends; and an explicitly-set-but-
empty text flag counts as a source via cobra's Changed, so `--response ""` gets
"cannot be empty" rather than "no text provided".

`bd human respond` joins them: its response can come from positional args,
--response, --file or --stdin, so --response is no longer a required flag.
`bd human dismiss` takes its reason positionally as well as via --reason, and
both accept trailing free text (`<id> [text...]`) the way `bd comment` does —
a second argument is text, never a second id. The "Response: " prefix and the
shared Dismissed close reason are now formatted ONCE, before the proxied
dispatch, so the two backends cannot shape them differently; the same move
lets the proxied comment entry points take resolved text instead of re-reading
the flags themselves.

`human stats` classifies dismissals by that shared Dismissed prefix instead of
a case-insensitive substring search for "dismiss", so the writer and the
classifier cannot drift. Beads closed earlier with a lowercase or mid-string
"dismiss" move from the Dismissed count to Responded; CHANGELOG carries the
note.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzyFzAJkmN3MGhXSo9AMwQ

* fix(human): bring `human list`/`stats` to bd list parity via IncludeAllTypes

`bd human list` built its own two-field filter: a label match plus whatever
--status the caller typed, unvalidated. So it showed closed beads by default
where `bd list` hides them, answered a typo'd status with a silent empty list
instead of an error, and — because it never went through the shared builder —
could not be told what a default listing is SUPPOSED to hide.

It goes through workapi.BuildListFilter now, which gets it the done/frozen
status exclusions, the pinned default, status validation against built-in and
custom names, comma-separated sets, and "all". `human stats` counts the same
universe (--status=all) through the same path, and the proxied side calls
openAndPrepare rather than hand-building a second filter, so the command
cannot mean one thing in direct mode and another behind the proxy.

What it must NOT inherit is the type suppression: a `human` label is an
explicit request for a person's attention, and this command is the only place
a person sees it, so gates, wisps, infra beads and templates all show. That is
the new issueops.ListRequest.IncludeAllTypes — the union of IncludeTemplates,
IncludeGates, IncludeInfra AND IncludeEphemeral. Both the type exclusions and
the PLANE decision now live in one applyTypeSuppressions that the flag skips
whole, so it decides the ephemeral plane too rather than lifting three type
knobs and leaving `bd human list` blind to human-labeled wisps. A suppression
added there in future is lifted here without touching this command.

Two pinned fixes fall out of parsing the status selector ONCE instead of
comparing the raw string in three places:

  * --status=all no longer forces Pinned=false. "all" promises every status;
    the string comparison never matched it, so the one selector that hides
    nothing kept hiding pinned beads. The golden case status_all_keyword is
    re-recorded (Pinned false -> null) and TestPinnedDefaultBySelector owns
    the rule now.
  * --status=pinned,closed no longer excludes the pinned beads it asks for —
    the same comparison missed every multi-status set.

--ready is deliberately unaffected: it forces status open and otherwise
ignores the selector, so an "all" the query never applies must not have a
pinned side effect either.

BEHAVIOR CHANGE, called out in CHANGELOG: scripts using --status=all as a way
to list everything EXCEPT pinned beads will see pinned beads appear. Add
--no-pinned to keep the old result.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzyFzAJkmN3MGhXSo9AMwQ

* fix(human): let proxied respond/dismiss answer wisps, and stop the phantom label warning

Two gaps in the proxied twins of `bd human respond`/`dismiss`, both of which
`bd human list` showing every bead type now makes reachable:

WISPS. The pair resolved through proxiedRequireIssue and then wrote the
comment and the close against the DURABLE tables. A human-labeled wisp is a
bead a person can see in `bd human list` — so it has to be one they can also
answer. Resolution goes through workapi.GetIssueOrWisp and the write side
branches: AddCommentToWisp/CloseWisp for the ephemeral plane, unchanged calls
for the durable one, still inside the single RunTx the proxied write
convention asks for.

THE ADVISORY WARNING FIRED ON A FAILED LOAD. The missing-'human'-label warning
read labels with the error discarded, so a label load that FAILED was
indistinguishable from a bead with no human label, and the user was told the
label was missing when nothing had been checked. The result now carries
labelsKnown, and a failed load simply warns nothing.

NOT salvaged: the post-commit close-hook firing this branch originally carried.
It was written when each proxied call site hand-wired its own hooks; main has
since moved firing onto the unit-of-work plumbing (uow.NewNotifyingProvider,
bd-opisf), which buffers during the transaction and drains after Commit. The
proxied human close already fires its hooks — a hand-wired call here would
fire each one twice. The reason is recorded on closeHumanProxied so the next
reader does not re-add it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UzyFzAJkmN3MGhXSo9AMwQ

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-08-10 05:36:11 -07:00
Julian Knutsen
9a2c918b0e
Admit the ephemeral plane from a list request, on the facade and on the wire (#5476)
* feat(reader): admit the ephemeral plane from a list request

`issueops.Reader.Ready` has had an ephemeral gate since it was written;
`List` has not. The wisp plane was reachable from a list request only as
a SIDE EFFECT of `IncludeInfra`, which also drops the infra-type
exclusions, or by naming an infra type, which routes to that plane
ALONE. A caller that wants the ephemeral rows of ordinary types — a
message bead, say — could ask for them on the ready query and not on the
listing, and the wire said so in prose: listIssues published no
`include_ephemeral`, and the document called the asymmetry out.

ListRequest.IncludeEphemeral closes it, with the same semantics
ReadyRequest.IncludeEphemeral already has.

  false (zero value)  durable rows only — today's listing, unchanged
  true                the wisp plane merged IN ADDITION; the answer is a
                      superset of the false answer under the same
                      filters, and never ephemeral-only
  WispType            a predicate on the wisp_type COLUMN, which BOTH
                      tables carry, so it selects no plane: it narrows
                      whatever was admitted. WispType alone answers with
                      nothing, since no durable row carries a
                      classification; WispType + IncludeEphemeral is
                      lawful and composes as an ordinary AND
  order               ONE order across both planes, by SortBy, as if
                      they were a single table — not durable rows
                      followed by ephemeral ones. A Limit truncates the
                      merged order, and the keyset position is applied
                      to BOTH legs, so a cursored walk over the merge
                      drops no row and repeats none. The non-snapshot
                      caveat is the one every multi-page walk already
                      has; the ephemeral plane only turns over faster
  --ready             CARRIED, not dropped. The ready query has an
                      ephemeral gate of its own, so
                      ReadyFilterFromIssueFilter now reads the plane bit
                      off the list filter. That also carries
                      IncludeInfra's plane half, which the projection
                      used to drop silently — `bd list --ready
                      --include-infra` now answers with the wisps `bd
                      count --include-infra` already counts

It is a PLANE knob and not a TYPE knob, which is the whole difference
from the three fields beside it: templates, gates and infra types stay
hidden by their own predicates. IncludeInfra remains strictly wider.

The wire gets `include_ephemeral` on listIssues, spec-first. There is no
capability-token change: it is an ordinary optional query parameter, so
an older server answers it with 400 `unknown_parameter` — the designed
skew signal, whose recovery is to degrade rather than retry.

Conformance runs on all three legs (server-backed store, embedded store,
unit of work) and covers admission, the merged order, every page bound
across the interleaving, a cursored walk across the plane boundary, and
the WispType interaction. The two seams arrange the merge differently —
one merge-sorts two independently ordered legs in Go and trims, the
other ORDERs a SQL UNION ALL — so the bounded and cursored arms are a
genuine two-body case rather than one body twice.

* fix(reader): correct the flag's reach, and settle the merge seam it lands on

Review follow-up. Three of these are documentation being wrong about the
code; one is the code itself.

THE MOTIVATING EXAMPLE WAS FALSE. `message` is one of the DEFAULT INFRA
TYPES (agent, role, message), so "the ephemeral rows of ordinary types —
a message bead, say" named the one row this flag cannot reach: the
infra-type exclusion is a TYPE predicate and survives the plane knob, as
the golden already recorded and nothing asserted. `bd ready` cannot
deliver it either — ReadyWorkExcludeTypes appends the infra set
unconditionally. The field doc, the operation description and the
parameter text now say that ephemeral agent/role/message rows need
IncludeInfra, and what the flag alone reaches is the ephemeral rows of
the types a listing already shows.

The contract case is what makes it more than a corrected sentence. The
fixture's only wisp was a task, which comes back under EITHER knob, so a
body that wired the plane flag to IncludeInfra's branch answered every
row correctly. An infra-typed wisp is hidden twice over — once by the
plane, once by the type — and is the only row that can tell the two
apart. Three rows now pin it: absent under IncludeEphemeral, present
under IncludeInfra, present under both. Wiring the flag into the
type branch fails it.

TWO MORE DOC CORRECTIONS on the same field. It admits the wisps TABLE,
which holds no-history rows (ephemeral = 0) alongside true ephemerals —
stated, rather than left as "the ephemeral plane". And it is NOT
identical to ReadyRequest.IncludeEphemeral: ready reads both planes
either way and adds a per-ROW ephemeral predicate when unset, where this
selects which TABLES are read. The difference is observable on exactly
those no-history rows, which a DEFAULT ready answer already contains and
a default listing does not.

The ready projection's predicate is negative, on a field whose zero
value means admit, so it fires for a filter that merely never set
SkipWisps rather than for one that asked. Every caller is handed a
BuildListFilter result, which decides that field for every request, so
"unset" is unreachable today — named at the site so the next hand-built
filter does not walk into it.

THE SEAM DISAGREEMENT, which is the code change. A cross-plane duplicate
id was tolerated by the per-table seam (collapse to the canonical wisp,
answer) and HARD-ERRORED by the union seam, and this flag routes every
wisp-inclusive read onto the union. Two implementations of one role
answering a page and an error is a divergence, not a design, and leaving
it silent while making it reachable is worse than either behavior.

The union now resolves it the way its sibling does, at all four sites,
and the strict flag is gone rather than left as a footgun. Three things
say that is the right verdict and not merely the convenient one: the
per-table seam has said so since be-iabdi ("hard-erroring breaks every
lookup city-wide"); `bd doctor` detects the state with a query of its
own, so answering blinds no detector; and its fix deletes the stale
ISSUES copy, which is exactly the row the union now drops. Its own check
text names the hard failure as the damage — "stale issues-table copies
break every lookup for the affected IDs". The four tests that pinned the
error now pin the wisp-canonical answer; inverting the preference fails
all four.

Preferring the wisp needs a second pass: the outer ORDER BY can place
either copy first, so which leg produced a row is known in full only
after the scan.

Last, a stale comment: issueops/count.go claimed SearchIssuesInTx was
the corruption detector. It has not been one since be-iabdi. The count
trusts the disjoint-table invariant and no read enforces it, so a
dual-resident id is counted twice and listed once; doctor is the
detector and the repair.

---------

Co-authored-by: Review Sim <ci@beads.test>
2026-08-09 05:06:36 -07:00
CI Bot
aa10a725e5 feat(list): put bd list's row cap and counts hydration on ListRequest (bd-b34o7)
STAGE ONE OF TWO. Fields, not methods, and no route flips — those are stage 2
(bd-5k21g). `issueops.ListRequest` gains MaxRows, MaxRowsSource and SkipCounts,
each with a conformance contract running at all three backends and zero parks.

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

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

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

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

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

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

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

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

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

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-05 16:36:31 +00:00
CI Bot
1c35a769d3 feat(issueops): add the Reader role and wire both front doors through it
Reader is Lifecycle's read counterpart, built as its mirror image: a role in
the leaf `issueops` package, reached through a capability accessor on the
storage seam, implemented at the same six sites. `Storage` gains
`IssueReader() (issueops.Reader, error)` beside `IssueLifecycle()`, and the
governing rule holds — a new capability got a new role and a new accessor,
not four more methods on an existing one.

SUBSUME, NOT COMPOSE. Reader takes the whole high-level request and performs
filter and default construction INTERNALLY, supplying its own ConfigSource
from the store or unit of work it already holds. Under compose both front
doors would each build a ConfigSource, load config, call a builder and execute
— two callers again, which is the topology that shipped a bare IssueFilter to
a viewer and silently served in_progress rows as "ready". Under subsume the
ritual is not callable from a front door: handlers and RunE bodies can only
say rd.List(ctx, req), so the failure mode is unwritable rather than merely
discouraged.

The three read endpoints are implemented against the frozen OpenAPI v0
document and consume the accessor; the 501 stubs and their self-deleting
exemption list are gone. `bd show --json` reaches the same role through the
same accessor, resolving the canonical id first so fuzzy and cross-repo
lookup stay CLI-local.

The workapi builders are re-typed onto the leaf request types, so there is no
second params struct to drift; both recorded goldens replay byte-identical,
which is the proof the re-typing changed nothing.

Load-bearing details:

- `sort` is forwarded EXPLICITLY as priority when absent. The storage layer
  reads an empty policy as hybrid, which demotes older high-priority work and
  therefore changes the item SET once a limit truncates — while the document
  still reads correctly. Pinned by a handler test on the recorded filter and
  by the parity oracle's order assertion.
- The parity oracle compares FULL ITEM JSON, not id sets. An id-set oracle
  passes while ready ships a bare Issue against the CLI's IssueWithCounts.
- internal/workapi no longer imports internal/storage/uow; it names the slice
  of a unit of work it reads through, so the uow provider can implement the
  role without closing an import cycle.
- internal/utils' cgo store test moves to an external test package for the
  same reason, with its two unexported-symbol cases split out.

Verified: issueops is still a leaf (internal/types + stdlib only); the
protocol corpus is unchanged structurally and behaviourally under
BEADS_PROTOCOL_REQUIRE_DOLT=1; a real `bd serve` answers all six operations
against a real workspace with CLI and HTTP JSON identical field for field.
2026-07-31 18:37:25 +00:00
CI Bot
6b04f94ef0 refactor(workapi): add BuildReadyFilter with a golden recorded from both old builders (bd-ehi)
First half of the bd-ehi collapse, kept separate so the golden table is
provably generated from the OLD code: this commit adds
internal/workapi/ready.go (BuildReadyFilter, ReadyParams,
DefaultReadyLimit) without touching either of cmd/bd's copies, and records
what BOTH of them produce for 39 command lines into
internal/workapi/testdata/ready_filter_golden.json.

Recording both columns is the point. `bd ready`'s defaults are built twice
today - inline in ready.go's RunE for the direct path, and in
gatherReadyInput for the proxied path - and the golden is what turns "they
look the same" into a fact. They agree on 33 of the 39 cases, including
Status: "open" (the tracked description says only one copy hard-codes it;
that has not been true since ready_input.go was added in 911ff8025). The
six disagreements are pinned by TestReadyFilterGoldenDivergences with the
branch that was kept and why:

  - Offset: only gather sets it. The direct RunE rejects --offset before
    any filter exists, so this is not observable.
  - MaxRows/MaxRowsSource: only the direct path sets them, and only the
    direct path can enforce them. Kept in cmd/bd rather than ReadyParams.
  - --max-rows -1 / --claim --gated / --offset -1: each rejected by one
    builder because the other path's RunE rejects it upstream.

DefaultReadyLimit = 100 is today's CLI default, not a new choice: it is
readyCmd's --limit default at HEAD. 0 still means unlimited, so the builder
does not substitute it.

The generator (cmd/bd/zz_ready_filter_golden_gen_test.go) is scaffolding
and is deleted in the follow-up commit that removes ready.go's inline copy.
It clones readyCmd's real flag definitions rather than re-declaring them,
and its args -> ReadyParams mapping cannot launder a mistake into a false
pass: the golden records the ReadyParams, so a field set in params but not
on the command line makes the replay fail rather than succeed.

Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of CI Bot
2026-07-31 07:19:59 +00:00
CI Bot
af56541bb3 refactor(workapi): add internal/workapi with the list-filter builder and a pre-extraction golden (bd-fv4)
First half of the bd-fv4 extraction, kept separate so the golden table is
provably generated from the OLD code: this commit adds
internal/workapi/list.go (BuildListFilter, ListParams, ListConfig,
ConfigSource, DefaultListLimit) without touching cmd/bd's copy, records
what cmd/bd's buildListFilter produces for 35 inputs into
internal/workapi/testdata/list_filter_golden.json, and asserts the moved
builder reproduces it byte for byte.

DefaultListLimit = 50 is today's CLI default, not a new choice: both
cmd/bd/list.go's --limit flag and internal/config's list.limit default are
50 at HEAD.

The generator (cmd/bd/zz_list_filter_golden_gen_test.go) is scaffolding and
is deleted in the follow-up commit that removes cmd/bd/list_filter.go. Its
params -> listInput conversion cannot launder a mistake into a false pass:
the golden records the ListParams, so a mis-mapped field there makes the
replay fail rather than succeed.

Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of CI Bot
2026-07-31 05:42:40 +00:00