beads/issueops
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
..
batchapplier.go Add issueops.BatchApplier: one plan, one transaction (#5480) 2026-08-09 06:59:34 -07:00
batchcloser.go Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436) 2026-08-08 11:23:34 -07:00
batchcreator.go feat(create): put bd create --file behind the BatchCreator role (bd-lu170) 2026-08-05 16:43:11 +00:00
blockedstate.go Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436) 2026-08-08 11:23:34 -07:00
blockingannotator.go feat(list): put bd list behind Reader.List and the new BlockingAnnotator role (bd-5k21g) 2026-08-06 02:56:57 +00:00
bootstrapper.go feat(init): put bd init's identity seam behind Bootstrapper and InitVerifier (bd-zl3u8) 2026-08-06 03:01:33 +00:00
claimer.go chore: retire a zombie test, drop a dead field, true up two leaf docs (#5492) 2026-08-09 10:42:34 -07:00
claimer_external_test.go Add issueops.Claimer and route the HTTP claim through it (#5334) 2026-08-04 08:40:18 -07:00
commenter.go chore: retire a zombie test, drop a dead field, true up two leaf docs (#5492) 2026-08-09 10:42:34 -07:00
counter.go feat(issueops): put bd count behind the Counter role (bd-m8hn7) 2026-08-05 05:27:39 +00:00
cycledetector.go feat(issueops): put bd dep cycles behind the CycleDetector role (bd-wfkbv) 2026-08-05 09:36:14 +00:00
deleter.go Add DeleteRequest.ExpectedVersion: a compare-and-delete on the named row (#5481) 2026-08-09 07:17:54 -07:00
dependencyeditor.go Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436) 2026-08-08 11:23:34 -07:00
edgereader.go feat(issueops): put multi-id bd dep list behind the EdgeReader role (bd-nhsno) 2026-08-05 09:42:06 +00:00
errors.go Add issueops.Releaser: give a claim back, optionally only a named holder's (#5482) 2026-08-09 07:48:56 -07:00
graphcounter.go docs: the ext-api-store documentation tranche — post-#5516 auth sweep, wave doc coherence, role checklist refresh (#5545) 2026-08-10 08:05:07 -07:00
importer.go feat(import): port bd import to proxied-server mode (bd-o58fz) (#5355) 2026-08-05 09:05:22 -07:00
initverifier.go feat(init): put bd init's identity seam behind Bootstrapper and InitVerifier (bd-zl3u8) 2026-08-06 03:01:33 +00:00
issueops.go fix: canonicalActor collapses the --/__ axes correctly; claim-verify uses ActorMatches (be-p7dzx, bundled be-vc51) (#5856) 2026-08-19 13:23:35 -07:00
issueops_external_test.go feat(issueops): name the two dependency-endpoint refusals (bd-yby99.9) 2026-08-07 19:45:54 +00:00
metadatacas.go docs: the ext-api-store documentation tranche — post-#5516 auth sweep, wave doc coherence, role checklist refresh (#5545) 2026-08-10 08:05:07 -07:00
querier.go Converge Offset and MaxRows on all three legs, and fix the panic and the breaker hole under them (#5435) 2026-08-08 11:37:09 -07:00
reader.go feat(httpapi): serve bd list's order with sort on listIssues (#5666) 2026-08-27 09:21:12 -07:00
reader_ready_scope.go feat(httpapi): serve bd list's order with sort on listIssues (#5666) 2026-08-27 09:21:12 -07:00
readyclaimer.go feat(workapi,storage): opt-in Brief projection for the list and ready pages (#5554) 2026-08-10 10:45:23 -07:00
readycounter.go feat(ready): put bd ready's published total behind the ReadyCounter role (bd-s10oa) 2026-08-05 09:47:24 +00:00
relations.go feat(issueops): put every issue capability behind one library surface 2026-08-04 12:27:56 -07:00
releaser.go fix: canonicalActor collapses the --/__ axes correctly; claim-verify uses ActorMatches (be-p7dzx, bundled be-vc51) (#5856) 2026-08-19 13:23:35 -07:00
statsreporter.go Wave 2 review fixes: dep list shape, stats 400, and the blocked-count promise 2026-08-06 21:18:26 +00:00
sweeper.go Version embedded role deletes and sweeps, and replace the range that hid it (#5458) 2026-08-08 23:53:57 -07:00
treewalker.go Converge Offset and MaxRows on all three legs, and fix the panic and the breaker hole under them (#5435) 2026-08-08 11:37:09 -07:00
versionreconciler.go feat(issueops): put the startup version reconciler behind the VersionReconciler role (bd-gkmft) 2026-08-05 16:35:01 +00:00
workspaceconfig.go Refuse kv.* point reads on the settings role and stop printing them (#5493) 2026-08-09 11:06:51 -07:00