* feat(stats): count the rows the default listing suppresses
bd status counts the issues table; bd list hides gates and templates on
account of what they are. The two therefore disagree, and nothing
reconciles them: a teardown driven by bd list leaves a gate behind and
status reports a total the operator cannot account for from any listing.
Break the suppressed rows out as their own counts. TotalIssues keeps
counting the database, which is what a command titled "Issue Database
Status" should report; these say how much of that total no default
listing will show. Every backend's statistics path funnels through
ScanIssueCountsInTx, so one query serves all of them.
Infra types need no counterpart here: they live on the wisp plane, which
this query does not read.
* fix(status): disclose the counted rows bd list will not show
bd status reported "Total Issues: 2" for a workspace whose every listing
showed one, because gates and templates are suppressed from a default
bd list. Nothing connected the two numbers, so the remainder read as a
phantom -- most visibly after a teardown driven by bd list, which leaves
its gates behind and then cannot see them.
Report the suppressed rows under the summary they qualify, naming the
flag that reveals each kind. The breakdown is printed rather than a
single hidden-total, since a template gate would otherwise be counted
twice. Nothing is printed when there is nothing suppressed.
Stacked on the statistics counts that make this reportable.
* docs(api): put gate_issues and template_issues on the Statistics schema
The Statistics schema is pinned to types.Statistics, so the two new
counts were on the wire the moment the struct grew them, and
TestWireTagBijection fails the openapi gate until the spec says so:
Go fields with no spec property: [gate_issues template_issues]
Document both as a breakdown of total_issues rather than an addition to
it — they count rows the default `bd list` suppresses, which
total_issues already includes — and warn against summing them, since a
row can be both a gate and a template.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(status): give --assigned the same disclosure, and test the behavior
Three points from review.
1. `bd status --assigned` never printed the line. AssigneeStats does not
go through ScanIssueCountsInTx - it folds one actor's rows through
workapi.FoldStatsAssigneeSummary, which left both new fields zero. That
route's filter sets only Assignee, so IsTemplate stays nil and the
actor's gates and protos really ARE in those rows while
`bd list --assignee` suppresses both: the same reconciliation gap, one
scope down. The fold now counts them, and its doc says they are set
deliberately rather than borrowed from a workspace-wide answer.
2. The infra-type suppression is now explained rather than asserted away,
and the answer is that a durable infra row is NOT unreachable, so the
third breakdown is filed as GH#6439 rather than dismissed. Both the
plane routing and the listing's exclusions read the workspace-configured
types.infra set, and writing that key only invalidates a cache
(dolt/config.go) - it never moves rows already written. So durable rows
created while a type was not infra stay durable once it becomes one, and
a type evicted from the set creates durable rows outright, which the
create contract already pins ("evicted infra type",
issue_operations_contract.go). Counting them needs that configured set,
which ScanIssueCountsInTx - portable SQL with no config seam, called
from six backend sites - cannot reach; guessing with the built-in names
would be wrong in exactly the workspaces where it matters.
suppressedTypeSummary's doc now carries that reasoning.
3. The behavior itself had no test - both existing cases exercised a pure
string formatter, and would pass with the render call site deleted. Now:
- TestRenderStatusEmitsTheSuppressedRowsLine captures renderStatus's
stdout, asserts the line and both parts, and asserts it sits after the
totals it reconciles rather than in the extended block. It fails with
the call site removed ("renderStatus did not emit the disclosure
line"), plus a companion asserting the line is absent when there is
nothing to disclose.
- Three conformance cases in stats_reporter_contract.go, wired into all
three role wirings (dolt, embeddeddolt, uow), so the new SQL is
checked cross-backend rather than at one call site:
BreaksOutTheRowsTheDefaultListingSuppresses (with the negative rows a
loose predicate would also move), BreaksOutAGateThatIsAlsoATemplate
(the two suppressions are independent, so a proto's gate step counts
in both), and AssigneeStatsBreaksOutTheSuppressedRows for the fold.
statsReporterCounts and assertStatsReporterDelta carry the two fields.
All three are behavioral reds against zeroed counts, not compile
errors:
GateIssues moved by 0 (0 -> 0), want 1
TemplateIssues moved by 0 (0 -> 0), want 1
GateIssues = 0, want 1 - the actor's gate is in this answer but
not in `bd list --assignee`
4. Nit: pluralCount takes both spellings instead of appending "s", so a
caller with an irregular plural is not silently mis-served.
Also adds the CHANGELOG entry the behavior change was missing, including
the GH#6439 gap.
Reported-by: bee-ghosttrack
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(conformance): declare the new stats cases in the order the table runs them
TestRoleContractCasesCoverEveryContractCase checks more than coverage: the
roleContractCases table has to list cases in the order their contract file
DECLARES them, because that is the order the unit-of-work leg's runners use
and the order its config-writing cases depend on.
I declared all three new cases together, then registered the assignee one
with the other assignee cases in the table, so the two orders disagreed:
roleContractCases is out of declaration order at position 449: table
has RunStatsReporterAStatusOutsideTheTalliesIsCountedOnlyInTotal,
source has RunStatsReporterAssigneeStatsBreaksOutTheSuppressedRows
Fixed by moving the declaration rather than the table entry, since the
assignee case belongs beside the other assignee-scoped ones anyway - the
grouping the table already had was the correct one. Caught by CI because I
ran go vet over backend/conformance but not its tests; both now pass.
Agent-Signature: claude-code-opus-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs(changelog): move this PR's entry under [Unreleased]
The 1.3.0 cut renamed the old [Unreleased] block, so the entry this branch
added there now merges cleanly into the released [1.3.0] section (#6643).
Agent-Signature: claude-code-opus-5-5-unknown-reasoning on behalf of Harry Miller
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(status): complete the disclosure's remedy and pin its population
Maintainer review fixes for PR #5763 (adopt-pr iteration 1). Four of the
five review findings taken; the nit is declined with its measurement.
Finding 2 (minor, gate impact minor) - the printed remedy was incomplete.
The two counters come from the same scan as TotalIssues and are status-blind
with it, but the flags they named lift only the TYPE exclusion, so a CLOSED
gate was counted while `bd list --include-gates` still would not show it.
Gates are closed as the work they guard completes, so that is the ordinary
case rather than an edge.
Took the "complete the hint" arm over the "scope the counters" arm. Every
other field ScanIssueCountsInTx fills is workspace-wide; the disclosure
exists to account for TotalIssues, a database number printed three lines
above it; and scoping these two to the listing's population would leave them
explaining nothing about the total they are broken out of. `--all` "replaces
the status exclusions only" and lifts no type exclusion of its own
(backend/conformance/reader_contract.go:487), so the two flags together are
exactly the remedy. Recorded the population in the types.go field comment,
the status.go doc, and the CHANGELOG, which printed the old example verbatim.
Finding 3 (minor) - the three new conformance cases seeded only open rows,
so a backend counting over every status and one counting only the listing's
population returned identical numbers on all of them. Added a closed gate and
a closed proto to the first case. Proved it now decides the question: scoping
both SQL SUMs with `AND status <> 'closed'` reds exactly that case
("GateIssues moved by 1 (0 -> 1), want 2") while the all-open sibling
BreaksOutAGateThatIsAlsoATemplate stays green.
Finding 4 (minor) - the normative role doc in issueops/statsreporter.go
enumerated only the six prior counts. Added the two to that scan's bullet and
corrected two statements this PR had falsified: the headline "six counts of
one set", and the AssigneeStats bullet's "the fold ... tallies the five
statuses and nothing else", which stopped being true when the fold gained the
two increments.
Finding 1 (minor, gate impact minor) - ran `make bazel-sync`. It proposed
exactly one line, `+ "status_suppressed_test.go"` in cmd/bd/BUILD.bazel, and
nothing else, confirmed by porcelain rather than by bazel-sync-check.
Generator-owned, not hand-edited.
Finding 5 (nit) - declined. The three helpers already in package main
(pluralIssue, pluralize, plural) all DERIVE the "s" and cannot render a
caller-chosen pair; the tree's one two-form helper, pluralWord, is unexported
in internal/storage/issueops, and exporting it so a CLI string could reach it
would add exported surface to a storage role for a cosmetic. Recorded that
trade in pluralCount's doc comment instead.
Validation: `go build ./...` and `go vet` (6 pkgs) clean, gofmt clean,
`git diff --check` clean; cmd/bd 4/4 named PASS, internal/httpapi
TestWireTagBijection|TestSpec* PASS, internal/workapi PASS,
internal/storage/uow TestStatsReporterContract 18/18 subtests PASS. Both new
pins are mutation-proved: reverting `--all` reds all four table cases, both
flag subtests and the render-path pin, while the absence assertion stays
green.
Not done here: the PR body carries the same stale example line
("1 gate (--include-gates)"). Review iterations do not touch the PR surface,
so that correction is stamped for finalize.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
* feat(count): --include-ephemeral, the plane knob `bd count` never had
`bd count` can admit the wisps table only through `--include-infra`, which
makes four changes at once. This adds the flag that makes just the first one,
mirroring the `--include-ephemeral` that `bd list` gained in #6098.
## Why the plane is unreachable on its own
The write path routes on STORAGE CLASS, not type — dolt's `useWispsTable` is
`Ephemeral || NoHistory || WispType != "" || IsInfraType`. So a `no_history`
task lives in the wisps TABLE while remaining ordinary durable work, and a
default `bd count` never sees it.
Recovering it today means `--include-infra`, which this repo's own doc calls
"FOUR changes at once and not one": it admits the plane, drops the infra-type
exclusions, changes the template treatment, and reconciles cardinality with
`bd list --all`. Its template exclusion then silently drops template rows of
the named type — so a caller who wanted the plane trades one silent undercount
for another.
`ListRequest.IncludeEphemeral` has been the narrow answer on the listing side
since #5476, and #6098 gave it a CLI flag. `CountRequest` had no equivalent
field at all. This is the missing half of that pair.
## The change
- `issueops.CountRequest.IncludeEphemeral` — the plane knob alone: exactly the
first of `IncludeInfra`'s four changes, with none of the other three.
- `internal/workapi/count.go` — one line, `} else if !in.IncludeEphemeral {`.
- `cmd/bd/count.go` — flag registration, matching `bd list`'s wording.
- `internal/httpapi` — `include_ephemeral` on `countIssues`, in the spec; the
generated `types.gen.go` is `make api-gen` output, not hand-edited.
Unset, the count is durable-plane only: the historical answer, unchanged. Every
default is untouched.
It does NOT promise a count and a listing agree. They already differ on
TEMPLATES without this flag and still do with it — a count includes template
rows unless `IncludeInfra` excludes them, a listing excludes them unless
`IncludeTemplates` admits them. That predates this and is unchanged by it; only
`IncludeInfra` sets out to reconcile cardinality, and it pays with three
changes beyond the plane.
## Verification
ok github.com/steveyegge/beads/internal/workapi
ok github.com/steveyegge/beads/internal/httpapi
ok github.com/steveyegge/beads/issueops
--- PASS: TestEmbeddedCountIncludeEphemeral (39.71s)
--- PASS: TestCountIncludeInfraFlagShape
--- PASS: TestParseCountRequestCarriesEveryFilterFlag
`TestEmbeddedCountIncludeEphemeral` was run with `BEADS_TEST_EMBEDDED_DOLT=1`
and really executed — 39.71s, not a skip. The default fast tier would have
skipped it and reported `ok`.
`make api-gen` reproduces `types.gen.go` byte-for-byte from the spec hunk, so
the two cannot drift apart in review. `go build ./...`, `go vet` and `gofmt`
clean.
Claude-Session: https://claude.ai/code/session_01X1jMLQTSrCwtzFRS1xeUC6
* count: reframe the comments for this repo, not the fork they came from
Review on #6240 (bee-ghosttrack): five comment blocks were written from the
fork's point of view and become false once merged here — "belongs upstream",
"the half that still has to go upstream", "the fork's old wide default",
and "upstream's default" meaning the current default.
Find-and-replace, as asked: the reasoning is kept, only the frame of reference
changes. "upstream's default" -> "the default before this change"; the bd
list sibling "landed in #6098"; the infra-type divergence is "pinned, not
fixed, here" with the reason; the embedded test's fork-maintenance history is
replaced by what it actually pins. No code changes.
* build(bazel): list the two test files this PR adds in their go_test srcs
Maintainer review fixes for #6240, review iteration 1. The synthesis and the
quality scorecard both returned approve with no required changes; this commit
takes the one minor whose subject is the PR's own added files.
Taken:
- Change Impact / Blast Radius (minor, gate impact minor). The PR adds
cmd/bd/count_include_ephemeral_embedded_test.go and
internal/workapi/count_skipwisps_test.go, but neither was listed in its
package's explicit go_test srcs, so the PR's own assertions were invisible to
`bazel test`. Both rows are now listed.
Gazelle's verdict, not a hand-guess: `make bazel-sync` was run (bazel 9.2.0 is
available here) and it produced exactly these two entries. Its full output
also rewrote 12 other BUILD.bazel files -- pre-existing base drift from other
PRs' files, plus dep/select churn -- which is out of scope for this PR, so the
generated result was reverted and only the two rows this PR is responsible for
were re-applied, at the slots gazelle chose. Both srcs lists remain sorted
with no duplicates (cmd/bd bd_test 637 entries, internal/workapi workapi_test
24 entries).
The cgo build tag on count_include_ephemeral_embedded_test.go does not exempt
it: the repo lists tag-gated *_embedded_test.go files anyway (99 of the 101 in
cmd/bd are listed, and the sampled ones are simultaneously listed and tagged).
Declined:
- Test Evidence Quality (nit, gate impact none). The filing lane itself marked
it optional and explicitly said not to gate on it, and its own reasoning holds:
internal/storage/dolt/counts.go and internal/storage/embeddeddolt/counts.go
both delegate to the same issueops.CountIssuesInTx, differing only in
transaction acquisition.
Validation: go build ./... and CGO_ENABLED=1 go vet on cmd/bd, internal/workapi
and issueops all clean; go test ./internal/workapi/ ./issueops/ ok. No
production code changed -- the commit is two generated-list rows.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
bd list, bd ready and bd search all take --has-metadata-key. bd count did
not, so counting the rows that merely carry a key meant listing them and
measuring the page. This is the last metadata-filter parity gap between
count and the listings.
The storage layer already carries the filter: types.IssueFilter has
HasMetadataKey and sqlbuild.AppendMetadataClauses consumes it. What was
missing is the role field, the builder wiring, the CLI flag and the HTTP
contract, so this is one change rather than a stack.
Parsing matches list_input.go and ready_input.go, including the key
validation. BuildCountFilter now passes the key to ValidateMetadataFilters
instead of the empty string it passed before, which makes the role's
existing refusal reachable from the count surface; failReadErr already
classifies that error as a 400 on has_metadata_key.
apigen types are regenerated from the spec via go:generate, not hand
edited. The pinned CLI docs are untouched.
Fixes#6160
Co-authored-by: postoso <postoso@users.noreply.github.com>
Co-authored-by: Gas City Adopt-PR <noreply@example.com>
* feat(purge): live-dependent protection, --wisps-plane selector, hour-precision --older-than
An orchestrator's wisp retention step deletes every closed row in the
wisps table older than N hours, except a closed wisp that an
open/hooked/in_progress wisp depends on through parent-child, tracks or
blocks. `bd purge` could not express that: it selected the ephemeral
TIER (so closed --no-history beads, which live in the wisps table, were
left behind), it deleted a closed molecule root whose step was still
open, and it floored --older-than hours to whole days (36h swept rows
24h old). All three land together so `bd purge --wisps-plane
--older-than 168h --force` covers that step.
Live-dependent protection (issueops.SweepRequest.ProtectLiveDependents,
SweepSkips.LiveDependent): a candidate is held back when a live row
depends on it through a SweepLiveDependentEdgeTypes edge (parent-child,
tracks, blocks), read from both dependency tables. "Live" is the same
not-done set the reference scan uses, custom statuses included, so it
is a superset of open/hooked/in_progress. `bd purge` always asks for it
(no opt-out: removing live work's root is `bd delete`'s job); `bd prune`
does not. Reported as live_dependent_skipped in --json.
Wisps-plane selector (issueops.SweepWispsPlane, `--wisps-plane`): the
candidates are every closed row in the wisps TABLE, whatever its
ephemeral/no_history/wisp_type values, via a new single-plane search
(issueops.SearchWispsPlaneInTx) that the store backends call directly
and the unit-of-work provider reaches through
IssueUseCase.SearchWispsPlane, so embedded, server and proxied share one
body. It reaches durable-tier (no-history) rows, so it carries the
durable tier's require-a-filter gate.
--older-than (purge and prune): day values keep their meaning (7, 7d,
2w); anything else is a Go duration taken exactly (36h, 168h, 90m).
Tests: three new Sweeper contract cases (wisps plane clears the whole
table, wisps plane requires a filter, protects live dependents) run on
dolt, embeddeddolt and the uow provider; workapi unit tests; a CLI
retention scenario run in embedded, shared proxied and managed-local
proxied modes (fails against origin/main); TestParseOlderThan.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(uow): classify IssueUseCase.SearchWispsPlane as a read in the notifying parity partition
TestRecordingIssueUseCaseCoversItsSurface requires every IssueUseCase
method to be either wrapped by the notifying decorator or exempted with
the reason it fires no hook. SearchWispsPlane reads state and changes
none, like SearchIssues beside it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(purge): refuse out-of-range --older-than; add --limit for bounded drains; cross-plane protection test
Review follow-ups on #6883.
--older-than: a day count past what a time.Duration holds (213504d,
30501w) used to wrap silently — 213504d became 25m26s, which on a
destructive command selected almost every closed row. It is now refused
as out of range; ParseDuration already refused oversized h/m/s values.
--limit N (issueops.SweepRequest.Limit, SweepResult.Remaining): one
purge deletes at most N rows, oldest closed_at first (then id), after
every protection, and reports the rest. --json adds remaining and
has_more when --limit is given. At ~15ms/row on the proxied path a
single unbounded sweep of a large backlog can outlive a caller's
deadline, roll back, and never clear; a bounded loop cannot. Negative
limits are ErrValidation at the role and refused at the CLI.
Tests: TestParseOlderThan out-of-range rows; contract cases
LimitTakesTheOldestClosedFirst and ProtectsLiveDependentsAcrossPlanes
(a live issues-table bead depending on a closed wisp via parent-child,
tracks and blocks keeps it) on dolt, embeddeddolt and uow; workapi
units for the ordering and the negative-limit refusal; the CLI
retention scenario now drains with --limit 1 and checks the overflow
refusal. CHANGELOG notes that sub-day Nh values used to round UP to a
day (12h is now taken exactly) and lists the protection under Changed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* test(bazel): add internal/testutil/bazeltest runfiles helpers
Repository-path resolution for tests that works identically under plain
go test (package cwd, full checkout), bazel test locally, and remote
execution (declared runfiles only):
- IsBazel, RepoRoot (BEADS_TEST_REPO_ROOT, then the runfiles workspace
root, then a go.mod walk), OverrideRoot (drop-in condition for existing
helpers; empty under plain go test), CallerDir
- Runfile for $(rlocationpath) values, GOROOT for type-checking tests
- ShardFreeEnv for helpers that re-exec a test binary
Every helper reduces to the pre-Bazel behavior under go test.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): declare source/data reads for 14 scan-guard targets
Source-scanning and repo-file tests read files their Bazel targets never
declared, so they failed under `bazel test` (and could not run on remote
workers at all). Declare narrow inputs as `data` and resolve paths through
bazeltest where the test located the tree via runtime.Caller:
- tools/bazel/go_srcs.py (run by `make bazel-sync` after gazelle) keeps a
managed `go_srcs` filegroup in the packages whose Go source tests scan,
plus `//internal/storage:tree_go_srcs` for the storage-tree walk. Bazel
globs stop at package boundaries, so the aggregate needs one filegroup
per package; the script keeps it in sync and gazelle-stable.
- Hand-written narrow inputs: //internal/storage/schema:migrations,
//:docsync_files, //plugins/beads:plugin_files, and exports of
.gitattributes, .claude-plugin/marketplace.json, cmd/bd list.go and
ready.go, testutil/testdoltcommon.go, scripts README.md and the release
catalog, each visible only to its consumer.
- runtime.Caller-based roots in backend, backend/conformance,
internal/storage, internal/formula and test/docsync now go through
bazeltest.CallerDir / OverrideRoot; relative-path tests need data only.
- integrations/ leaves .bazelignore (it is still gazelle-excluded) so the
docsync link check can declare integrations/beads-mcp/PYPI.md.
Under --config=prcore every target reports the same PASS/SKIP/FAIL test
set as `go test -race -short` for its package, locally and remotely.
Plain `go test` behavior is unchanged.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): guard generated go_srcs and harden bazeltest root override
- tools/bazel/go_srcs.py: add --check (print diff, exit 1 on stale blocks);
new `make bazel-sync-check` target runs it.
- scripts/bazel_policy_test.go: under go test, assert every tree_go_srcs
(//internal/storage) lists exactly the BUILD.bazel packages below its
root, run go_srcs.py --check, and forbid BUILD files under docs/ and
engdocs/ (they would cut subtrees out of //:docsync_files).
- bazeltest: honor BEADS_TEST_REPO_ROOT only when it holds go.mod
(RepoRoot fails loudly otherwise); drop the unused GOROOT() helper,
whose compiled-in branch could never fire under rules_go.
- scripts/ci/lib/test-env.sh: unset BEADS_TEST_REPO_ROOT.
- Document the hand-listed out-of-tree link targets in //:docsync_files.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* build(bazel): re-sync BUILD files with main
Regenerated with make bazel-sync after commits that landed while the
scaffold PR was in CI (new internal/execenv, gitenv, gitignore packages
and new sources/deps).
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): declare init_safety_help.go for docsync
TestInitSafetyCLIHelpCoversReCloneGotchas (#6431) reads
cmd/bd/init_safety_help.go; export it to //test/docsync only.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* build(bazel): add side-by-side Bazel scaffold (module + gazelle)
Add a Bzlmod Bazel build alongside the Go toolchain. `go build` and
`go test` are unchanged; nothing in CI invokes Bazel yet.
- MODULE.bazel: rules_go 0.63.0, gazelle 0.53.0, Go SDK 1.26.7 (matches
the go.mod toolchain directive), go_deps from go.mod.
- ICU policy (engdocs/ICU-POLICY.md): a go-mysql-server gazelle_override
selects the pure-Go regex backend and excludes regex_cgo.go, and
.bazelrc builds with --@rules_go//go/config:tags=gms_pure_go, so no
target depends on go-icu-regex or links libicu.
- third_party/patches: three module_override patches for dolt deps that
ship WORKSPACE-era BUILD files, adapted from the gascity project.
- .bazelrc: prcore/ci test configs (inert for now; they match pr-core's
test selection, not yet its environment isolation) and a generic
remote-exec config with a bounded remote timeout. Executor endpoints and
TLS credentials come only from a gitignored .bazelrc.local/user.bazelrc
or a CI rc outside the workspace.
- .bazelversion pins Bazel 9.2.0; .bazelignore skips separate modules,
non-Go trees, nested agent worktrees (.claude, .worktrees) and local
data/output dirs (.beads, .dolt, dist, .runtime, tmp), so a primary
checkout neither builds nor gazelle-rewrites nested worktree copies.
- Gazelle-generated BUILD.bazel files for every Go package.
- Makefile: `make bazel-sync` (gazelle + bazel mod tidy).
- .gitignore: bazel-* output symlinks and machine-local rc files.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(bazel): policy tests for the Bazel configuration
Add scripts/bazel_policy_test.go, plain Go tests that run under both
`go test ./scripts` and `bazel test //scripts:scripts_test`:
- MODULE.bazel go_sdk.download version equals the go.mod toolchain.
- ICU policy: .bazelrc sets gms_pure_go for build, the go-mysql-server
gazelle_override excludes regex_cgo.go, and the root BUILD.bazel
carries `# gazelle:build_tags gms_pure_go`.
- .bazelversion pins an exact Bazel release.
- .bazelrc.local and user.bazelrc are gitignored (parsed from .gitignore
and cross-checked with git check-ignore when in a checkout).
- No remote-execution endpoints or credentials in committed bazelrc-like
files, Markdown docs or .github/**: remote/BES/TLS flags
(--remote_executor, --remote_cache, --bes_backend, --remote_header,
--tls_client_certificate, ...) with a literal value, with or without a
URL scheme, and non-loopback gRPC URLs in rc/.github files. Placeholders,
$VARIABLES, and loopback are allowed; Markdown gRPC URLs (OTel exporter
docs) are not flagged. Skipped outside a git checkout, e.g. in the Bazel
sandbox.
Each check is a pure function also exercised against fixtures that break
the invariant. The files the tests read are declared as data via
//:bazel_policy_files so they resolve from runfiles under Bazel.
scripts/check-build-tags.sh now treats Bazel invocations as governed by
.bazelrc: the shell command segment that invokes Bazel (split on &&, ||,
;, |, $( and backticks) is exempt from the per-line `go` tag check, while
a bare `go` in another segment of the same line is still flagged. When
any scanned file invokes Bazel (or .bazelrc exists) .bazelrc must set
--@rules_go//go/config:tags=gms_pure_go for build.
scripts/check_build_tags_test.go covers both in a temp repository.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(scripts): split bazel lines in pure bash so check-build-tags works with BSD sed
BSD sed (macOS) does not expand \n in s/// replacements, so the segment
split never happened and the Bazel-exemption tests failed on macos-latest.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* test(scripts): skip check-build-tags tests when bash lacks mapfile
macOS runners use /bin/bash 3.2, which has no mapfile; check-build-tags.sh
has always required bash >= 4, so the new tests are skipped there.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
* fix(list): expose comment bodies and mark the omission in bd list --json (be-73x)
`bd list --json` reported comment_count and carried no comment text and no sign
that any was missing. The consequence is not a missing field: a content search
over a listing answers with a well-formed, NON-EMPTY result set whose matching
rows are absent, and nothing about that answer invites a second look. An empty
result invites suspicion; eight rows do not.
Two halves, and the second is the one that fixes what was actually reported:
1. --include-comments on `bd list` populates each row's comments with the
full bodies, the list twin of `bd show --include-comments`. Opt-in: it
costs one query per row that has comments.
2. Every row with a nonzero comment_count whose bodies were NOT hydrated now
carries comments_omitted=true, by default, with no flag. A flag nobody
knows to pass does not fix a silent hole; a marker on the row does.
The bodies ride on types.Issue.Comments, which already carried the `comments`
key for export/import and was simply never populated on this path, so the only
new field is the marker.
Hydration is one shared body (workapi.HydrateListComments) called from BOTH
issueops.Reader.List implementations, the store-backed and the unit-of-work
one. Those are separate bodies that have answered one contract method
differently before; it runs in the page epilogue beside FinishPageAt, after the
trim, so a page never pays for rows it is about to drop.
The source parameter is a CONSTRUCTOR rather than a source, and that is
load-bearing. Building the unit-of-work comment source eagerly made a
capability only the opt-in path uses into a requirement every caller had to
satisfy, and turned `GET /v0/beads/issues` into a 500 on a provider without a
comment use case — on requests that had asked for no comments. A count-only
listing now constructs nothing, pinned by a test that fails if the constructor
is called.
Tests pin each implementation separately rather than duplicating: unit tests
over a fake source, an embedded-dolt test over the real CLI on the direct
route, and a proxied-server test over the real CLI on the unit-of-work route.
Sabotage-controlled three ways — no-op the shared body and all three suites go
red; unwire either reader alone and only that reader's CLI test fails, which is
what proves neither integration test is redundant.
Not addressed, deliberately: gt-mfp5 (bd comment does not advance updated_at,
the orthogonal recency axis) and be-ozp (bd ready --json carries no marker; it
does not route through Reader.Ready).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XK4B7N2CrgfKGEQvDTPM4D
Executed-By: beadsrig/polecats/dag
* fix(list): do not read a skipped comment count as proof of no comments (be-73x)
Codex review of the parent commit, correctly.
`IncludeComments: true` combined with `SkipCounts: true` returned a page with
no comment bodies at all — no error, no marker, nothing — while
`IncludeComments` documents a guarantee to populate them. The hydration loop
skipped any row whose CommentCount was zero as an optimisation, and SkipCounts
zeroes every count: `issueops.ListRequest.SkipCounts` says in its own doc that
a zero then means UNKNOWN rather than none.
That is this bead's own failure mode reintroduced one layer down by the fix for
it: a silent, well-formed, empty answer to a request that asked for content.
I had considered the interaction and resolved it wrongly, in a comment reading
"the count is authoritative here because the JSON route never sets SkipCounts".
True of today's CLI callers, and not a property of the contract — issueops
.ListRequest is a PUBLIC request type and permits both fields at once. A
comment saying "X cannot happen because of how callers behave today" on a
public type is a bug with a justification attached, and worse than no comment,
because it tells the next reader the case was checked.
countsKnown is now a parameter rather than an assumption; call sites pass
!req.SkipCounts.
countsKnown true a zero count proves a row has nothing; skip its query.
countsKnown false query every row, because nothing proves otherwise, and
mark no row omitted, because comments_omitted asserts a
nonzero count the page cannot support.
The second half is the mirror defect on the marker path — the same conflation,
the other direction — which the review did not name.
No behaviour change on any current CLI path: the JSON route never sets
SkipCounts, so it passes countsKnown true, and the text route asks for no
comments and marked nothing before either. Verified: `bd list --json` output
identical, and text output identical with and without the flag.
Regression tests HonorsIncludeWhenCountsAreSkipped and
MarksNothingWhenCountsAreSkipped. Sabotage-controlled: restoring the
count-authoritative skip fails the first with "issued 0 comment reads, want 2".
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XK4B7N2CrgfKGEQvDTPM4D
Executed-By: beadsrig/polecats/dag
* fix(list): resolve the comment plane by residence, not by the row's flags (be-73x)
Maintainer review fixup for #6473, iteration 1. Both review lanes reached the
same major independently and the synthesizer re-verified it against the tree.
The new list hydration derived the comment table from the row's own
Ephemeral/NoHistory flags - issueops.IsWisp's rule, which is right for routing a
record being WRITTEN and wrong on a read. `bd import` pins a `no_history` record
to the DURABLE table while preserving the flag on the row, because clearing it
would change the content hash and break export->import->export byte-identity,
and every clone materializes its database by importing JSONL. So a promoted
no-history bead that has been through a round-trip is a durable row whose flags
say wisp:
bd list --json --include-comments read wisp_comments, found nothing, and
returned comment_count=N beside an empty
`comments`, with no marker and no error
bd comment, bd show write and read that same row's comments on
the issues plane, by found-table
That is be-73x's own failure mode reintroduced under the flag whose contract is
"gets them or gets an error", and a cross-role divergence: `bd list` and
`bd show` disagreed about one row. The mirror case is real too - an import
record whose `wisp_plane` key pins it to the wisps table with neither flag set
reads back as durable - so no flag-based rule gets both directions right.
The plane now comes from the seam that knows it. HydrateListComments takes a
CommentPlanes lookup instead of inferring; the unit-of-work reader answers it
from the wisps TABLE (IssueUseCase.GetWispsByIDs, the call edgeReader.ReadEdges
already makes for the same question), once per page, inside the page's own read
transaction. The store-backed seam passes SourceRoutesCommentPlanes because its
source routes ids itself (DoltStore.GetIssueComments picks the table from
isActiveWisp) and would buy a lookup for an argument it ignores. isWispPlane is
deleted: nothing on this path infers a plane any more. A nil lookup is an error
rather than a silent "durable", so a third seam has to answer the question
rather than inherit the default this bug was.
A MISSING WISPS TABLE STAYS "NO WISPS" rather than a failed listing, classified
through the same two helpers the counts query that produced the page uses
(dberrors.MissingTableName + sqlbuild.OptionalWispTable). Any other failure of
the lookup fails the call: a guessed plane answers with the wrong table's
contents and nothing in the response shows it.
Tests. The unit table now asserts residence AGAINST the flags, with each row's
comments present only on the plane it lives on, so a wrong-table read shows up
as missing TEXT and not merely as a wrong flag in a recorded call. Restoring the
flag inference reds exactly the two rows where flags and table disagree
(durable-carrying-no_history, wisp-table-carrying-no-flags) and leaves the two
agreeing rows green. The old `override_wins_over_flags` case is gone:
WispPlaneOverride is `json:"-"` and set only by import, in memory, so no scanned
row can carry it and that branch was unreachable on this path - which is what
made the suite look sufficient (Codex's separate minor, folded in here as the
same root cause). New seam-level tests drive the real uow Reader.List over both
shapes, and pin that a listing without the flag resolves no planes at all, that
a missing wisps table is tolerated, and that any other lookup failure
propagates; emptying the residence answer reds the wisp-row leg.
Also from the review, non-gating:
- types.IssueWithCounts.CommentsOmitted and the OpenAPI property stated the
marker rule unconditionally on a type Reader.Ready and the claim response also
return, neither of which calls the epilogue. Both now scope the rule to the
List surfaces and cite be-ozp, which is where the parent commit deliberately
left the ready surfaces. (`bd ready --json` does not route through
Reader.Ready; GET /v0/beads/ready and ClaimNextResponse.claimed do.)
- GET /v0/beads/issues gained no `include_comments` parameter, so its
description now says so and points at the detail read, in the idiom the
`revision` paragraph above it already uses.
- One internal/httpapi list test for the new wire field: the marker present for
a commented row, absent for an uncommented one. It was asserted only by the
spec file; the detail twin has get_issue_test.go. Neutering
markCommentsOmitted reds it.
Validation: go build ./...; go vet over the changed packages and again with
CGO_ENABLED=0; make api-check clean, so the spec edits oblige no regeneration;
go test ./internal/workapi/... ./issueops/... ./internal/types/;
TestBothReaderImplementationsAgreeOnTheListEpilogue plus the new plane tests in
./internal/storage/uow/; BEADS_TEST_PROXIED_SERVER=1
TestProxiedServerListComments 3 PASS and BEADS_TEST_EMBEDDED_DOLT=1
TestEmbeddedListComments 4 PASS.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Maintainer review fixups for #6731. The review found no blocker and no major;
these are its two gate-impact minors plus two nearby nits.
- externaldeps.Store.ReadyCounter built a fresh store-backed counter, so the
documented storage.ReadyCounter.CountReady span stopped being emitted for
every text-mode `bd ready` in the cmd/bd chain (hooks -> externaldeps ->
telemetry -> store). PR-introduced: at base this decorator had no
ReadyCounter at all, so the embedded passthrough reached the instrumented
layer -- and this PR edits the very otel document that lists the span. The
accessor cannot simply recurse, because the exclusions live on this store, so
it now hands the finished counter to the inner store's WrapReadyCounter,
which telemetry already exported for exactly this case and had no caller for.
Pinned by TestExternalDepsReadyCounterSurvivesThisLayer, which fails with the
old body (verified by reverting it).
- CHANGELOG: GetReadyWorkWithCountsAndTotal is a new REQUIRED storage.Storage
method with no optional-interface fallback, so an out-of-tree `backends`
registrant stops compiling on upgrade. The entry names the method, the
contract an implementer owes, and why the compile-time posture is deliberate.
- The ready probe's facts now record each index as its column is appended.
Two conditional columns were read back through a mix of literals and a
computed `next`, so the two conventions disagreed inside one function and a
future column inserted above would silently mis-read a different fact.
Behavior-identical; the four excludeDeferred x wantCollision combinations are
covered by the embedded filter matrix.
- The combined family count wraps as `count ready work: issues+wisps:`, so it
is distinguishable from the issues-only retry beneath it, and
storereadycounter's package doc no longer claims only two importers.
Validation: go build ./...; go vet and go test on issueops, externaldeps,
telemetry; BEADS_TEST_EMBEDDED_DOLT=1 TestReadyWorkPageTotal,
TestReadyWorkPageTotalFilterMatrix, TestReadyWorkStatementBudget
(embeddeddolt) and TestEmbeddedReady (cmd/bd).
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Forward-ports the 38 commits that shipped on release/1.3.0 (tagged v1.3.0 at
f45b249ce) into main, as RELEASING.md mandates after a tag. None of them had
ever been forward-ported. Recorded as a merge so main becomes a superset of
the release branch and the lineage is in the history.
Migration ordinal collision (the reason this needed a human-shaped merge):
both branches independently claimed clone-local ignored slot 0026 under
different filenames, so git merged both in with no conflict and left the
series with two migrations at ordinal 26 — a single-integer cursor cannot
address that, and migrationSource.list() panics on it.
Main's ignored/0026_add_wisps_current_revision is renumbered to 0027.
Release's 0026_dep_rekey_dedup_marker is in the shipped v1.3.0 tag, so field
stores have already recorded it at 26 and it can never move; main's twin has
never shipped in any release, so it is the one that is free to move. 0027 was
unused in the ignored series (both sides topped out at 26).
This trips check-migration-hygiene.sh Check C (frozen migrations), which has
no exemption mechanism. That is expected and accepted: breaking the collision
requires a rename, and the ignored series' cursor table is itself dolt-ignored,
so its content hashes are clone-local and never participate in the cross-clone
ContentHashSkew comparison that Check C exists to protect. Main's 0067 body is
deliberately NOT edited for the same reason in reverse — it is main-plane and
its hash IS compared across clones.
Conflicts resolved:
CHANGELOG.md release's finalized [1.3.0] section kept
byte-identical; main's two unreleased
entries (#6023, #5859) moved up under
[Unreleased] where they belong
cmd/bd/init_safety.go union — release's added paragraph is
cmd/bd/init_safety_help.go accurate against the merged code (three
exit-12 sources, incl. init.go:3147)
internal/storage/uow/dolt_sql_provider.go
kept main's newProvider refactor AND
release's readOnly field/assertion;
newProvider gained readOnly: opts.readOnly
so release's read-through-refused-migration
behavior survives main's refactor
.github/workflows/main.yml single -timeout=30m per release's #6091
scripts/ci_workflow_test.go design (flag on the invocation, not in
matrix.test-flags); the shadowed 25m in
matrix.test-flags removed
scripts/migration-test/lib/versions.sh
union — main's darwin/arm64 corpus plus
release's v1.2.2 linux/amd64 entry
integrations/beads-mcp/uv.lock ruff 0.16.5 (release, newer); block is
internally consistent, uv lock --check ok
default.nix vendorHash left at main's value and is
KNOWN STALE — see below
Version stamp lands at 1.3.0 (main had been sitting at the previously-released
1.2.2, this project's between-releases pattern). check-versions.sh: 24/24.
Known follow-up: default.nix vendorHash. The merged go.mod/go.sum is a genuine
union (release's kin-openapi/oapi-codegen bumps + main's newer Dolt stack) and
matches neither side, so neither recorded hash is correct. It must be
regenerated with scripts/update-nix-vendorhash.sh. The repo's automatic fixer
(update-vendor-hash.yml) is dependabot-only and will not run on this PR.
* 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".
External (cross-project) dependency blockers are now enforced everywhere a bead's readiness or closability is decided: `bd ready` / `--claim`, `bd blocked`, `bd close` / done-status `bd update` (direct and proxied), `bd dep tree`, and served HTTP ready/claim. The policy is a storage-boundary decorator (`internal/storage/externaldeps`) applied on both the DoltStorage chain and the UOW provider, with full capability-forwarding parity, `Unwrap` at every level, and the backend's advisory defer-wake preserved on the claim path.
Review trail: maphew rounds 1–4 (Jul–Aug), bee rounds 1–4 (Sep 2): D1 recording-parity exemption, D2 ready-filter goldens, D3 UOW-level Unwrap for the proxied importer, D4 claim-path defer wake. Verified at head 3468d62f on a clean merge with current main; CI fully green at that head.
Fixes#4769.
* fix(metadata): restore v1.2.2 scalar typing for --set-metadata values
8ebd53e88 moved the CLI's metadata-edit helpers into
internal/storage/metadata.go and, in the move, replaced v1.2.2's
toJSONValue inference with a MetadataEditValue that always json.Marshals
the value as a string. The intent was GH#4146 (a numeric-looking id or a
version like "1e3" came back as a JSON number, breaking map[string]string
Go consumers), but it silently changed the shipped CLI contract:
`bd update --set-metadata k=5` started storing "5" instead of 5. That
regression shipped only in the deprecated/superseded v1.2.1, never in
v1.2.2, and 1.3.0 would freeze it.
Restore v1.2.2's inference body-for-body inside MetadataEditValue, so the
parity claim stays checkable against `git show v1.2.2:cmd/bd/update.go`:
"null" is JSON null, "true"/"false" are booleans, a spelling that scans
as a float AND is valid JSON on its own is emitted as that literal
(5 -> 5, 1e3 -> 1e3, 0.50 -> 0.50, while 05, +5 and NaN stay strings),
and everything else is a string. Every --set-metadata caller funnels
through this one function: embedded (cmd/bd/update.go ->
storage.ApplyMetadataEdits), proxied (parseSetMetadataFlags) and the
update executor's []string path.
GH#4146's concern is served by the explicitly typed routes, which are
untouched: --metadata / --metadata-json on the CLI (MergeMetadataJSON)
and the typed set map on the HTTP/Go path (applyTypedMetadataEdits).
No data migration: a "5" written by an in-window build is
indistinguishable from a string a user set intentionally through the
typed paths, so normalizing stored metadata would corrupt intended data.
Re-running the same --set-metadata k=5 retypes any given key.
Tests: new table in internal/storage/metadata_edit_value_test.go pinning
the v1.2.2 matrix plus an ApplyMetadataEdits end-to-end; the tests that
pinned the string-always behavior are flipped (domain/db mergeops suite,
update_lifecycle patch mapping, cmd/bd toJSONValue table) and the
embedded + proxied CLI suites now assert a stored JSON number. The
contract corpus is regenerated: its update/list/ready goldens run
`--set-metadata phase=2`, so `"phase": "2"` becomes `"phase": 2` and
nothing else moves.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(create): echo full-precision timestamps from bd create, not the DATETIME(0) re-read
b92442d1a routed `bd create` through issueops.Lifecycle, whose executors
build their result by re-reading the row they just wrote
(HydrateIssueOperationResult -> GetIssueInTx). created_at/updated_at are
DATETIME(0) columns, so that snapshot comes back at whole-second
precision and cmd/bd/create.go echoes it. v1.2.2 returned the caller's
own in-memory struct, which PrepareIssueForInsert stamps with
time.Now().UTC() including nanoseconds, so `bd create --json` used to
print e.g. 2026-08-28T12:34:56.789012345Z. Agents that create several
issues in a burst order them by exactly that fraction; rounded to the
second they all tie.
Restore the echo with OverlayCreateTimestamps: after hydration, put back
the created_at/updated_at (and closed_at, when the write set one) the
INSERT actually sent. Everything else on the snapshot stays DB-truth,
which is the facade's contract — only create, and only these fields.
Applied at every create body, not just the two the CLI reaches:
issueops.ExecuteCreate and ExecuteCreateBatch behind the dolt and
embedded-dolt stores, and the unit-of-work provider's own Create,
CreateBatch and batch-apply create item, which is what the proxied server
and POST /v0/beads/issues run on. Fixing only the shared executors would
have left the two bodies disagreeing about the same promise.
What is NOT changed, because it is not a regression: `bd show --json` and
`bd list --json` answered whole seconds in v1.2.2 too — they read the
column — and update/close/reopen re-read after writing there as well.
Widening the columns to DATETIME(6) would give reads sub-second times
too, but that is a schema migration on user Dolt DBs and touches paths
that deliberately compare at second precision; it is a 1.4 change.
The accepted skew, which predates this and stays: the engine ROUNDS to
the column rather than truncating, so a later read of the same row can
sit up to half a second either side of the create echo.
Tests: two new conformance cases, run on all three backends —
RunLifecycleCreateEchoesSubSecondTimestamps (a caller-supplied
nanosecond stamp must survive to the result exactly; the auto-stamped arm
stays a bounded smoke check, since requiring a non-zero fraction off the
clock is flaky by a billionth) and RunBatchCreatorEchoesSubSecondTimestamps
(per item, since both bodies build the result one snapshot at a time).
Plus a cmd/bd embedded test asserting `bd create --json` prints a
fractional part, and one httpapi assertion that the wire does not round
the role's snapshot on the way out. All four fail on the pre-fix tree.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(httpapi,types)!: revision / expected_version tokens are opaque JSON strings
The optimistic-concurrency token is minted by freshRowLock over the FULL
int64 range (crypto-random, non-zero) and published on the wire as a JSON
number: `revision` on responses, `expected_version` on guarded requests.
A JSON number does not survive a consumer that decodes into an IEEE-754
double — JavaScript's JSON.parse, Go's `any`, Python's `float`, jq. Live
tokens run past 5e17, where a double's ulp is already 64, so such a
client reads back a value NEAR the token, echoes that as its guard, and
earns a 409 against a row nobody else touched. The spec already carried
"DECODE IT AS A 64-BIT INTEGER" paragraphs telling clients to work around
this; that is a workaround for a wire type that should not have been a
number.
Emit and accept the token as a decimal STRING instead. It is documented
as opaque and EQUALITY-ONLY — compare it, never order or interpret it —
and a string round-trips exactly in every JSON consumer. It also leaves a
future backend free to mint a token that is not an int64 at all.
Internals are untouched: freshRowLock, the row_lock BIGINT column, its
migration, types.Issue.RowVersion and the ExpectedVersion *int64 guards
on the issueops requests all stay int64. Only the wire projection moves,
through the one spelling of the encoding — types.RevisionToken and
types.ParseRevisionToken.
STRICT STRING ONLY, with no transitional number-or-string acceptance.
This API already refuses unknown members by name and keeps one spelling
of the guard, and a number is precisely the shape a double-based client
has already rounded before it left the client — accepting it would
preserve the defect. A numeric guard is a 400 naming the member.
Chosen over clamping freshRowLock to 53 bits: a clamp does not fix rows
already minted with full-range tokens by in-window builds, so a JS
consumer reading one still rounds past 2^53 — repairing that would need a
row_lock normalization sweep over issues and wisps, a migration days
before a tag.
Surface: types.IssueDetails.Revision (what `bd show --json` prints and
GET /v0/beads/issues/{id} returns), the five hand-assigned httpapi
response fields, applyVersionGuardMember (now the reader for the batch
update item too, ahead of its typed decode, so a mistyped token still
earns a 400 naming the member), Problem.expected_version, and 14 OpenAPI
members regenerated through `make api-gen`. actual_version goes with them
— it is documented as "the `revision` the row was found holding", so
leaving it an integer would make the expected/actual pair disagree about
its own type; it is declared but never populated, so nothing changes
behaviorally.
Nothing shipped in a tagged release ever carried this member: v1.2.2 has
no internal/httpapi at all and no `revision` anywhere on the wire, so the
whole surface is in-window and can still be changed compatibly. Legacy
migration-0054 rows read as the string "0" with the same CAS semantics.
Corpus goldens are UNCHANGED: the canonicalizer already replaced any
`revision` value with the string "<REVISION>" whatever its JSON type.
Tests: types-level pins that the marshaled member matches `"revision":
"-?\d+"` and that RevisionToken/ParseRevisionToken round-trip MinInt64,
MaxInt64 and 2^53+1, plus a JS-realistic decode of 2^53+1 with a float64
control proving the token really is one a number would corrupt; httpapi
refusal tests for a numeric guard on update, close, reopen, delete and
both batch item kinds; a 409 echo asserted as the string; and the proxied
serve integration tests now splice the response's own token back in
verbatim rather than re-rendering a parsed one.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* 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>
* 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.
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>
Three beads (ga-uwix0.1, ga-2yaqp.5, ga-2yaqp.6) plus a fable review round.
Docs and spec prose only: all 19 touched .go files are gofmt-normalized,
comment-stripped byte-identical to main. The one exception is deliberate and
reviewed — scripts/check_doc_freshness_test.go gains a data row, because the
delegated gate ruling required it.
ga-uwix0.1 — #5516 gave bd serve optional bearer auth and made it MANDATORY
beyond loopback; fifteen prose sites still said the opposite. The three the
council named are reworded to the stronger true form (the actor is not the
authenticated principal even where a bearer is required; a shared token admits
a client to the WHOLE surface and grants no narrower right). The sweep for a
fourth found eight more in five spellings the audit's grep could not reach,
including claim.go's "any client can claim as any name", release.go's
no-AUTHORIZATION variant, and six memory/settings-plane sites where the true
statement is sharper: a bearer decides WHO may call, never what a caller who
is let in may read. The review round found four more in the CHANGELOG's
UNRELEASED section, which round one had misclassified as released history —
they would have shipped false in the same release as the auth entry.
The serve runbook's "Binding beyond loopback" section was actionably wrong: it
said the flag "prints a warning and changes nothing else", and its refusals
table quoted a string not in the binary. Rewritten against a build, with every
flag, error string, event name and reason value produced by running the
command. It gains the operational trap nobody had written down: /healthz is
auth-exempt and GET /v0/beads/ready is not, so an unauthenticated readiness
probe earns a 401 forever while liveness stays green. The runbook is now IN
scripts/check-doc-freshness.sh, pinned to the four files it is read against.
ga-2yaqp.5 — nine prose defects, every count re-derived rather than trusted;
three of the audit's own numbers had moved again. 38 route rows and 36
capability-bearing ones; thirteen pinned schemas, not twelve or seven; six
missing entries in the no-query-parameter list, not five; twenty-eight role
accessors, not twenty-seven; nineteen patch members, not thirteen. Two prose
"code counts" were counting paragraphs. CodeAlreadyClaimed claimed the holder
is always attached when only one of four producers always attaches it and
releaseIssue never does. MetadataCAS's leaf contradicted its own shipped wire.
The path/operationId inversion is now recorded where a spec author looks.
ga-2yaqp.6 — the role checklist refreshed against what this wave's additions
actually cost, traced to real commits. Step 10 sent people to a name list
#5460 deleted. The "four more edits" claim was stated twice and undercounted
both times: the two freshest wire slices share a nine-file core plus
roles_test.go. The step-with-no-number gained the fact that explains its
instances — write-role decorators wrap, read-role decorators recurse, so the
call lands on the stub, and both real instances are reads. The wave got its
first CHANGELOG entry: six new public operations, not three, and zero new role
accessors in the window.
Review verdict: FIX-REQUIRED then all items addressed. The reviewer
live-falsified the strong auth form and failed to break it, and confirmed
every recount re-derives exact.
be-4d36f2 gave the dependents side a shallow shape after hub beads made
`bd show --json <hub>` allocate 5-13 GB marshaling full Issue records. The
dependencies side of the same builder never got it, and still returns the
complete body of every dependency.
Measured on a 16,051-issue store, one `bd show <id> --json` returned 214,456
bytes, of which 193,039 was the dependencies array; a single dependency carried
a 180,975-byte notes field. Reading one issue costs the full text of everything
it depends on.
BriefDeps reuses the shape collectDependents already settled on (id, status,
type, priority, title, dependency_type) and drops the free-form text. It is
opt-in and the default payload is unchanged, so no existing caller loses a
field it reads. That matters here: #4122 objects to default payload changes
and #5078 records what the last one cost.
The reduction runs after the Parent scan, which reads DependencyType and ID off
the full rows, and builds a new slice rather than overwriting the one the source
returned, which a caching source would keep shallow for later callers.
collectDependents now routes through the same shallowDep helper so the two
shapes are identical by construction rather than by coincidence.
Storage layer only, per CONTRIBUTING_PR_GUIDELINES.md; the cmd/bd flag that
reaches this is the follow-up PR.
Refs #5546
Co-authored-by: sjarmak <t@t.co>
* 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>
Every `expected_version` on this surface is composed from a token some response
carried, and until now every response that carried one was a WRITE. A client
that wanted to read a row, decide from what it said, and write it back under a
guard had to precede its first guarded write with a write it did not want to
make — or guard on nothing, which is the lost update the whole family exists to
refuse. Five places in the document said "no READ on this surface publishes a
revision yet" and named the member a read would have to agree with. This is that
member.
Spec first, then `make api-gen`, then the projection.
GET /v0/beads/issues/{id} PUBLISHES IT; GET /v0/beads/issues DOES NOT, and the
reason is not payload. Measured against a 20,482-row production export the
member is 28 bytes on a 1449-byte median row — under 2%, and the list rows are
already fat enough that a token would disappear into them. The reason is that
`types.IssueWithCounts` is ALSO THE INTERCHANGE ROW: `exportIssueRecord` embeds
it in both `bd export` and the auto-export that flushes a git-tracked
`issues.jsonl`, and the token is re-minted by every write, so publishing it on
that element would put a per-write-random value into a file whose whole value is
that it diffs when something meant something. That is precisely the loss
`types.Issue.RowVersion`'s `json:"-"` is there to prevent, and a wire member
cannot opt out of it — the list element and the export element are one pinned Go
struct. `types.IssueDetails` has neither problem: nothing interchanges it, and
`workapi.BuildIssueDetails` is its ONE production construction site against
IssueWithCounts's SIX, which is the second half of the argument. (Six
field-populating non-test literals: export.go, export_auto.go, search.go,
claim_next.go, ready_work_counts.go and uow/ready_claimer.go. The `[]*T{claimed}`
spellings in ready.go and ready_proxied_server.go are slice literals wrapping a
role-built element, not independent places to forget a field, and they are not
counted.) A token field on a struct built in six places is silently 0 wherever a
site forgets it, and 0 is a LEGAL token (the migration-0054 backfill), so
nothing — no test, no client — can tell a forgotten one from a legacy row.
So the projection moved onto the canonical type behind ONE DOOR. types.Revision
is set by types.NewIssueDetails and nowhere else, because a struct literal with
an unset token publishes a wrong answer that looks exactly like a right one.
THE DOOR IS WRITTEN INTO THE DOCUMENT, not just into this description. A later
revision that wants the token on the list rows needs a list element that is NOT
the interchange element, and the listing's own prose now says so — together with
the rule a client needs meanwhile: model the absent member as ABSENT, never as
0, because 0 is a real token and a client that defaulted would compose guards
matching exactly the rows it is most dangerous to be wrong about.
THIS DELETES A PARITY DIVERGENCE RATHER THAN ADDING ONE. `bd show --json` has
published this token for as long as guarded writes have existed, through a
CLI-only wrapper, and `readsParityAllowlist` waived the difference with the note
"if the token is ever needed over HTTP, extend that surface and delete this
entry". The wrapper is gone, both front doors read the member off the one detail
seam, and the allowlist is now EMPTY — kept declared, because an empty allowlist
is a stronger statement than no allowlist.
The wire council's outstanding fix rides along, because it is the same member
family: `ApplyItemResult.revision` and both apply-item `expected_version`
members gained the DECODE-AS-64-BIT clause every other revision-bearing member
already carried. The batch spelling is where it bites hardest — a token
corrupted by an IEEE-754-double parser refuses the WHOLE plan rather than one
write.
Evidence. Four mutations, each watched to go red in the right place and only
there: the constructor stopping projecting reddens all three legs; the seam
regressing to a struct literal reddens the workapi pin ALONE and leaves the
httpapi case green, which is why both exist; `omitempty` reddens exactly the
legacy-zero arms; and adding the field to `types.IssueWithCounts` reddens the
new list case while leaving `TestRowVersionNeverSerialized` GREEN — the separate
unset field carries none of the forbidden spellings — and reddens
`TestWireTagBijection` only while the document has not caught up. That measured
pair is written into the new case's own comment, because it is why the case is
not redundant with either gate.
Real Dolt through a real `bd serve`: read the token, guard a patch with it, watch
it land; watch a write move it; watch the read and the write agree on the new
one; watch the stale guard 409 with `param: expected_version`; re-read and watch
the retry land. The same loop on `close`, and the ephemeral fallback — where the
token is a different column on a different table and the failure mode is a zero
rather than an absence.
Gates: `make api-check`, `go build ./...`, `go vet ./...`, `gofmt -l` clean,
`golangci-lint run --new-from-rev=origin/main` on the touched packages (0
issues), the internal/types, internal/workapi, internal/httpapi and
internal/storage package runs, the byte-pinned `cmd/bd/protocol` corpus, and
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
'TestProxiedServerServeReadRevision|TestProxiedServerServeReadParity'` green
against real Dolt. The pre-commit hook's `go run golangci-lint@v2.10.1` fails on
this host with a toolchain mismatch unrelated to this change, so the hook's
contents were run by hand before committing with --no-verify.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Refuse kv.* point reads on the settings role and stop printing them
The `bd kv` keys and the `bd remember` memories nested under them are user
data stored as config rows. They ride in the settings table without being
settings, and only the ENUMERATION was filtered: a caller naming an exact
key still got the value back from GetSetting. That is not a smaller hole
than the enumeration was. `bd remember` derives its key from the content it
stores, so the keys are guessable, and the walk-around is one request to
GET /v0/beads/config/kv.memory.<slug> — a surface with no authentication
whose redaction decides on the key NAME while a memory's secret is in the
VALUE.
The point read now answers a `kv.` key exactly as it answers a key nothing
ever stored: the echoed key, an empty value, a nil error. Indistinguishable
from absence on purpose — this role has no ErrNotFound to give, and an
error of any kind would confirm the guessed key to the caller. The row is
not touched, and no read reaches the store at all.
The refusal lives in internal/workapi beside FilterSettingsEnumeration,
where both WorkspaceConfig bodies already reach for the enumeration rule,
so the three legs inherit one decision. Both filters now decide with
workapi.KeyIsOnTheKVPlane, which is the single statement of where the plane
boundary runs.
`bd config show` gets the same rule (bd-klko9). Its database section reads
GetAllConfig raw rather than through the role, so it inherited neither
filter, and it prints values in FULL because it is the operator's
provenance view — every stored memory went into every terminal and pasted
bug report that ran the command. Nothing replaces the view; `bd kv list`
and `bd memories` are the surfaces that own those rows.
The writes are deliberately untouched: SetSetting and UnsetSetting still
take a verbatim `kv.` key, which keeps the escape hatch for a wedged
memory, and a write discloses nothing.
RunWorkspaceConfigPointReadRefusesTheKVPlane pins it on all three legs. It
reads the config table out of band around the refusal, because "the row is
there and the read refuses it" has to be a different fact from "there is no
row", and it asserts a settings key still reads back so a role that
answered "" to everything cannot pass. Reverting either half of the
production refusal turns it red on dolt, embeddeddolt and uow.
bd-rfwtv, bd-klko9
* test(memory): move the proxied leg onto the new settings-plane contract
The proxied memory journey asserted that `bd config get kv.memory.<key>`
returns the memory content, with a comment calling it "visible via bd
config get". That is exactly the behaviour this branch removes, so the
case was pinning the old contract from a shard that does not run locally
-- which is why it stayed green until CI reached it.
It now asserts the new one: the point read answers as an unset key does,
and the content does not appear in the output. The rest of the journey is
untouched and still proves the memory is readable through the surfaces
that own it -- `bd memories` lists it, `bd recall` returns it
byte-for-byte -- so this is the proxied leg of the same firewall the role
contract pins, not a weakened assertion.
Also records in the CHANGELOG what the change does NOT buy. `bd serve`
has no authentication and serves every memory in full through
/v0/beads/memories by design, so this is plane hygiene -- keeping user
data out of the routes that get republished into agent transcripts -- and
not a confidentiality boundary against anyone who can reach the port.
---------
Co-authored-by: Review Sim <ci@beads.test>
* Add issueops.Releaser: give a claim back, optionally only a named holder's
Claiming has had its own role since Claimer; releasing has never had one.
`bd unclaim` reaches the raw seam directly, and everything that isn't the
CLI has had to spell the release as a patch — assignee to empty, status to
open, started_at to null — which puts the transition's definition in the
caller three fields at a time and still leaves the lease row behind. A
release is one act with a known post-state, and the lease it drops is the
part a patch cannot express at all.
It is its own role rather than a method on Claimer for the reason
Bootstrapper and InitVerifier are two: a caller entitled to give its own
work back is very often not entitled to take new work, and a surface
carrying both hands it a capability it should not be able to reach.
THE SHAPE MIRRORS THE RAW SEAM, and the two places it does not are both
refusals rather than permissions. UnclaimIssueInTx and
UnclaimIssueIfAssigneeInTx refuse an unheld row and a status the release
transition is not defined over with UNTYPED strings — "issue X is not
assigned" and, for the second, "no matching row", which explains nothing
and no caller can classify. The role reads the row first and names them:
ErrNotClaimed and ErrNotReleasable. Which requests are refused is
unchanged; the raw calls still run their own checks underneath.
ErrNotReleasable is wider than "closed" and the leaf says so out loud: the
release UPDATE is pinned to status open or in_progress, so an issue parked
in `blocked` while still holding a claim is refused. That is a limitation
of the transition, not a policy, and it is now visible instead of arriving
as "no matching row".
A RELEASE IS NOT IDEMPOTENT and this keeps it that way. An unheld row is
ErrNotClaimed with or without Force, not a Changed-false no-op — the raw
rule, and the one a reaper can errors.Is in a line it writes knowingly.
ExpectedAssignee is the compare-and-set: a match REPLACES the ownership
fence, exactly as UpdateRequest.ExpectedAssignee does for a transfer, so a
supervisor can free a named agent's claim without Force and without being
able to clobber a claim that has since moved. Force may not accompany it —
the two answer one question and disagree — and a non-nil pointer to "" is
ErrValidation rather than "expected unassigned", because releasing a row
nobody holds describes no release.
ErrNotOwner MOVES to issueops and internal/storage aliases it forward. A
refusal the public role raises has to be classifiable by a caller that
cannot import an internal package; a Go alias preserves identity in both
directions, so every existing errors.Is site keeps matching the same value.
All three legs share one body (internal/storage/issueops.ReleaseIssueInTx),
so this is one reading plus two wrapper checks rather than three backends
agreeing — and the wrapper check earned its keep again, in the same place
MetadataCAS's did. An EPHEMERAL release writes a row and versions nothing;
the unit-of-work leg's commit message is what commits its SQL transaction
as well as what versions it, so composing the message from the durable
table set rolled the write back and the wisp came out still claimed. Green
on both stores, red on the unit of work, exactly as the engdocs predicted.
The domain reach now answers Wrote and the store legs take Tables.
Eleven contract cases on all three legs. The post-state is read RAW, cell
by cell, because the whole reason to state it on the role was that a caller
should not have to reconstruct it — including the lease row, whose survival
is the failure no role-answer assertion can see. The attribution case
forces a release by someone who is NOT the holder, the only arrangement in
which stamping the holder is distinguishable from stamping the actor, and
counts entries per actor because created_at is second-granularity and an
ORDER BY would decide it on a coin toss.
The contract does NOT carry a case for a false ReleaseResult.Changed, and
says so: nothing returns it false, so the case could not fail. What can
fail is the decorator's use of it, which internal/storage/hook_releaser_test
drives with the answer the role reserves the right to give.
FACADE ONLY: no wire, spec or httpapi change, and no bd command re-pointed.
The wire half follows in the conditional-update / release wire slice per
the program's council gating.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Delete the two release pre-checks a mutation proved could not fail
Written as defence in depth, measured as dead weight. ErrNotOwner and
ErrAssigneeMismatch already come back from UnclaimIssueInTx and
UnclaimIssueIfAssigneeInTx typed, wrapped and in this same order, so
removing both copies left the whole eleven-case contract green on the
server-backed leg — the mutation-equivalence verdict that says a branch
exists to look reassuring rather than to hold anything.
What stays is the pair the raw seam answers with a bare string: an unheld
row ("issue %s is not assigned") and a status the release transition is not
defined over ("no matching row"). Those are the refusals this body is FOR,
and each one goes red when it is skipped.
The header now says which refusals this function owns and which it leaves
to the calls below, so the absence reads as a decision rather than as a
check somebody forgot.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Lint: one spelling of the holder, and drop two parameters nothing varies
golangci-lint's unparam found releaserSeedClaimed's holder and
releaserRowVersion's table taking one value at every call site. Both are now
gone, and the holder is one package constant rather than nine copies of the
same literal — which is worth more than the lint: half these cases are ABOUT
the difference between the holder and the caller, and two spellings of "the
holder" is how such a case comes to assert the wrong one.
Plus two British spellings misspell caught.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Review: say why Changed is asymmetric with Claimer's, and three prose fixes
Doc only; no behaviour changes and none intended.
THE RULING ON ReleaseResult.Changed, written where it belongs. Keeping the
unheld-row refusal was defended here as "the rule the raw seam already
has", which is an appeal to precedent rather than a reason. The reason is a
fact about the two POST-STATES. Claimer can afford an idempotent answer
because a claim's post-state IDENTIFIES THE CLAIMANT: a re-claim finds
assignee == Actor and StatusInProgress, the claim's own signature surviving
on the row, so the role can tell "you already did this" from "somebody else
holds it". A release leaves an ANONYMOUS post-state — assignee cleared,
status open, started_at gone — which is the same row whoever emptied it and
whether or not it was ever full. An idempotent release would answer Changed
false identically for "I already released this", "a reaper beat me to it"
and "nothing ever claimed it", with nothing left on the row to tell them
apart. Those three want different things from a caller, so the role refuses
and lets the caller pick. ClaimResult.Changed is now named at the
comparison rather than merely gestured at.
ExpectedAssignee compares BYTE FOR BYTE, now said out loud: " agent-a" is
not agent-a and refuses. The validator trims only far enough to tell a
blank expectation from a real one and never writes the trimmed form back,
and the no-mutation promise makes that permanent — so a padded expectation
loses every time rather than intermittently, which is the failure worth
warning about.
And the deleted-pre-checks note now states the CONSEQUENCE rather than the
shortcut: one leg was sufficient evidence BECAUSE all three legs run this
function and it reaches the same two raw entry points, so there is no
second implementation in which a deleted pre-check could still have been
load-bearing. "A mutation verdict is only true of the body you mutated" is
answered by there being one body. Where the legs DO differ is in what they
version — hence ReleaseWrite's two facts and the wisp case on all three.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Add DeleteRequest.ExpectedVersion: a compare-and-delete on the named row
`bd delete` is the one irreversible verb with no way to say "only if this
is still the row I looked at". Every other guarded write has one —
Lifecycle's Update, Close and Reopen all take an ExpectedVersion over the
same row_lock token — and the operation that most needs it is the one
where being wrong cannot be undone. A caller that reads a row, decides it
is finished with it, and deletes it has a window in which somebody else
reopened, reassigned or restarted the work; today the delete lands anyway.
The token is the ordinary one: server-minted, opaque, equality-only, nil
to disable, and read inside the deleting transaction so the pair is a
compare-and-delete rather than a read followed by a hopeful write.
TWO DECISIONS ARE WORTH THE REVIEW.
It requires a SINGLE-ID request, and a non-nil version beside more than
one distinct id is ErrValidation before anything is read. A row version
is per-row and the space is not shared, so one number checked against a
batch would pass a whole list of never-written rows by coincidence —
every one of them holds 0 — and fail forever for any list whose rows have
diverged. A guard that passes by coincidence and a guard nobody can
satisfy are the same defect from two sides. The shape a batch would need
is a token per ITEM, which BatchCloser.Items is, and this role is a list
of ids rather than a list of items; BatchCloseItem carries no version for
the same reason. Duplicates collapse first, so `bd delete a a` with a
token is one row and is legal.
It OUTRANKS the dependents guard and neither Force nor Cascade bypasses
it. A mismatch says the caller's whole view is stale, so reporting the
dependents refusal first would ask it to choose --cascade or --force over
information that has already moved; and force bypasses policy, never a
precondition, exactly as CloseRequest.Force does. It still ranks below
the existence probe: a request that named no row has nothing to be stale
about.
Two bodies, as ever. The store legs call the same CheckVersionInTx the
update and close guards use, on the transaction they delete in. The
unit-of-work leg compares the row its own existence probe already
loaded — the probe now keeps rows rather than a set of ids — which is
what updatePreconditionsHold does for the same token on the update path,
and avoids a second read of the same rows in the same unit of work.
Four contract cases on all three legs, written as a falsifiable pair: the
satisfied case takes the row's REAL token straight out of row_lock, on
both planes, so a body that refused every versioned delete reddens; the
stale case is the refusal, under DryRun too, with the rows counted raw
and the token asserted unmoved. The ranking case keeps a live outside
dependent on every arm, so "force did not bypass" is distinguishable from
"force was not needed", and ends on a matching-token force release so the
three refusals cannot be satisfied by a body that refuses unconditionally.
The arity case uses a token that MATCHES the first id, which is the only
arrangement that catches a body checking the first row and deleting the
list, and pairs it with the repeated-mention collapse so the rule cannot
be read as "expected-version deletes take one element".
FACADE ONLY. No wire, spec or httpapi change: the delete handler reads an
explicit member allowlist, so a new leaf field is invisible to clients
until the wire half follows in the conditional-update / release wire slice
per the program's council gating.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Review: pin existence-outranks-version, and say what the second SELECT buys
Three review items, one of which was a real hole.
THE HOLE: the leaf promises the version precondition ranks BELOW the
existence probe — "a request that named no row has nothing to be stale
about" — and nothing watched it. A second block on RefusesAnAbsentID does,
with a single absent id carrying a version.
It asserts the TYPE and not the sentinel, which is the whole point.
errors.Is(err, ErrNotFound) is satisfied by the WRONG order too: the store
legs run the guard through CheckVersionInTx, which answers a bare wrapped
ErrNotFound of its own for a row that is not there, so a flipped order
looks identical to a reader of the sentinel. Only *NotFoundError — which
nothing but the existence probe mints, and which carries the id — tells
them apart. The unit-of-work leg cannot answer at all: its comparison reads
the row the probe loaded, so a flipped order is a nil dereference.
Watched: moving the guard above the probe in the store body reddens it.
The other two are prose. workapi/delete.go cited `--expect-version`, a flag
that does not exist — the wire half is deferred — and now states the request
shape instead. And delete_role.go now says that CheckVersionInTx re-reads a
row the existence probe already returned, that what the second SELECT buys
is ONE definition of the guard shared with the update and close paths, and
that the unit-of-work leg answers the same trade the other way because the
shared function is not reachable from it — so the difference reads as a
consequence of where each leg sits rather than as drift.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* 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>
Offset and MaxRows were mirror-image splits: the unit-of-work seam honored
Offset and refused MaxRows; the two store legs did the opposite. Three contract
cases absorbed that with an "either HONORED or REFUSED with a typed
*ErrUnsupported" disjunction.
A contract that asserts a capability is either honored or refused is not pinning
semantics — it is ratifying a split. All three are gone, along with
assertReaderUnsupported. Converging upward rather than uow-matches-server is the
owner's one ratified exception, because the server refusing MaxRows was a
capability gap rather than a semantics choice.
Offset now runs in the shared page epilogue on every leg rather than in whichever
seam could render it: the skip must happen in the caller's display order, which
is not SQL-expressible for --sort id, and a row the database skips is a row the
query matched.
Two bugs fixed under it.
The panic: domain/db rendered LIMIT 18446744073709551615 OFFSET k for an
unbounded query, and Dolt sized a buffer from limit+offset and returned a
recovered makeslice panic instead of rows. The contract case had been shaped
around it, bounding every request, with a comment calling it a storage-seam bug
that predates the role. It now drives the unbounded shape.
The breaker hole, found by review: proxied bd list --watch with an offset and a
cap counted the cap against post-skip rows while the page route counted
pre-skip, so the same flags produced opposite verdicts — L=10, k=2, M=3 over 5
rows returned a page on one route and ErrTooManyRows on the other. Newly
reachable since 3b2385922 removed the proxied --max-rows rejection ahead of the
watch dispatch, and it falsified the comment claiming no caller combines an
offset with a cap.
MaxRows semantics are now ratified and documented: the cap counts the rows the
query TOUCHED (offset+limit), not the rows the caller receives. A skipped row is
still a matched row. Review reported the Limit+Offset == MaxRows boundary as an
off-by-one; measured under those semantics the code was already correct and the
doc was wrong, so the fix was the doc plus pinning the behaviour.
A seventh cannot-fail test was caught mid-slice: an unreachable "under a
defensive cap" branch in searchWindowFor absorbed the exact regression the new
MaxRows-behind-offset arm exists to catch, and the mutation returned
INCONCLUSIVE. Removed.
Equivalence of the epilogue skip to a SQL OFFSET was checked rather than
assumed. One narrow uncovered exception stands: under --sort title, SQL
collation and Go byte-compare can disagree on non-ASCII and then pick different
skip sets. Conformance seeds ASCII.
The memory commands get the treatment the sixteen issue commands got in #5378:
a role interface in a leaf package, conformance-tested at all three backends,
with the CLI routes and the HTTP handlers as thin callers over one
implementation.
memoryops is its own namespace rather than an addition to issueops. The two
planes share a config table and nothing else; a memory whose key shadows a
settings name is still a memory, and that separation is now the role's,
pinned by its contract, rather than a filter each caller reapplies.
Closes an unauthenticated disclosure found on the way: memory content was
served in cleartext on GET /v0/beads/config, and reachable through two more
doors — `bd config show` and `bd info --json`, the latter republished into
agent transcripts by MCP get_schema_info. Enumeration is now filtered at the
shared seam (workapi.FilterSettingsEnumeration); `bd config show` is left
alone deliberately, since an operator asks for it by name.
Two wire contracts were settled after the review council, recorded in full on
the PR: the search parameter is spelled `search` rather than `q`, because
issues:query already publishes `q` as a boolean expression and one surface
must not spell two questions one name; and getMemory keeps its 404, because
the status reports the distinction the front door already reports and
`bd recall` exits 1 on a miss where `bd config get` exits 0.
BuildListFilter pushes SortBy into the SQL filter; BuildQueryPlan did not. So
for a filter-expressible expression the database bounded the page in STORAGE
order and the display sort ran afterwards in Go, which makes "which N rows are
in the page" a property of whatever order the engine happened to return.
The two bodies then disagreed. The store body over-fetches one row as a
has-more probe and FinishPage sorted that probe INTO the page before cutting;
the unit-of-work body trims to Limit natively and never sees it. Same
expression, same --sort, same --limit, different rows — the exact failure
FinishPage's own comment cites as the reason it exists.
Pushed down, the bound and the order are one decision the engine makes: the
page is the first Limit rows in the requested order on every backend, and the
probe row is genuinely last, so cutting removes precisely it.
RunQuerierSortBoundsThePageInOrder pins it. The fixture is built so storage
order and sort order DISAGREE — four matches, limit two, and the two rows that
should win carry the worst priorities so the default engine order puts them
outside the three rows an over-fetch sees. Verified by mutation: without the
push-down the store leg returns [b y] where [a b] is correct.
It sorts by `title`, not `id`: sqlbuild routes `id` to a GO-SIDE sort
(natural id ordering has no SQL spelling), so no push-down can apply there and
both bodies bound in storage order alike. A first draft of this case used
`id` and passed against the unfixed code for exactly that reason.
Ten agents over 216 files, one directory-balanced group each, working to a
rubric that named what to cut (duplication narration, restatement of the next
line, the governing rule echoed in every command file, throat-clearing) and
what to keep (traps, invariants, security, tracker ids, behaviour changes, and
the "why a naive simplification destroys this assertion" rationale).
Net 1,523 lines. Density against this repo's own per-directory norm on main:
cmd/bd 33.6% -> 27.3% (main 10.7%)
internal/storage 26.1% -> 23.1% (main 14.1%)
backend/conformance 34.0% -> 29.6% (main 22.8%)
internal/httpapi 30.9% -> 27.8% (main 30.6%, now below)
overall 34.7% -> 31.6%
Every agent landed at 18-25% rather than the 30% asked for, and every one gave
the same reason independently: what remained was on the keep list. Ten separate
judgements agreeing is the most useful result here — the prose is dense, but it
is mostly load-bearing, and the shortfall is the honest answer rather than a
failure to try.
TWO REVERTS, both to protect something worth more than the lines.
issueops/ is back to its pre-trim state, giving up 610 lines. The conformance
contracts cite the leaf docs BY LINE — "pins treewalker.go:52-66" — 155 times.
Trimming the cited files silently repointed those at whatever text moved into
those numbers, across agent boundaries so no agent could see it. A semantic
remapper recovered 141 of them, but 23 needed judgement and several landed on
struct fields. The leaf docs are the spec the contracts are written against;
they are the one place in this change where dense prose IS the deliverable, and
keeping them stable is worth more than the 610 lines. tree_walker_contract.go
and version_reconciler_contract.go went back for the same reason: an agent had
deleted a paragraph containing a citation, so positional restoration could not
align them.
After the reverts, exactly 5 citations point into a still-trimmed file and 2 of
those are weak — both in cmd/bd/config_guard_test.go, which this series never
touched and whose citations were already wrong on main (init.go:361 pointed at
a closing brace; the guard it names is at init.go:1499).
VERIFICATION. A guard strips every comment and all whitespace from each of the
193 modified files at HEAD and in the worktree and requires the two to be
byte-identical, so a code change cannot hide in a comment diff. It handles `//`
inside string and raw-string literals, and was tested against a deliberate code
change before being trusted. gofmt clean, go build, go vet, golangci-lint 0
issues, and the two AST-based tests that PARSE trimmed files — the timed
provider binding pin over claim.go and the serve database-source gate over
serve.go — both pass.
One real defect found while trimming: checkDatabaseSource's doc block ran into
`// sourceRoles is ...` with no blank line, so godoc attached thirty-one lines
of the wrong prose to func sourceRoles and left checkDatabaseSource
undocumented. Fixed by separating them.
Fifteen paragraphs of the form "this file used to hold a second copy of <cmd>:
it parsed the flags again, opened a unit of work...". The fact that a second
implementation existed explains nothing about the code that is there now, and
the commit that removed it says so in more detail than a doc comment should.
Reviewed individually rather than pattern-matched. A first pass keyed on
phrases like "used to" and "this slice" flagged 130 paragraphs and would
have taken out design rationale with them — it cut bootstrapper.go's "WHY ONLY
THIS SLICE OF bd init IS A ROLE" because "THIS SLICE" matched a pattern
meant for programme slices. That pass was reverted. Of the 69 paragraphs a
tightened pass surfaced, these 15 are the ones carrying no live information;
the other 54 explain an invariant, a trap, or a behaviour change a user sees,
and stay.
`bd init` had two implementations of what a workspace's identity IS. The direct
route read issue_prefix out of the config plane at init.go:1358 and _project_id
four hundred lines later, decided adopt-vs-write with two helper predicates, and
wrote both keys by name. The proxied route called domain.BootstrapUseCase, which
held its own list of which keys an identity is made of, wrote them
unconditionally, and folded the Dolt remote into the same call. The two agreed on
the key names and disagreed on the rule, and no test compared them.
ONLY THE IDENTITY SEAM IS A ROLE. Everything else init does — creating .beads/,
writing metadata.json and config.yaml, initializing git, installing hooks,
starting a Dolt server — CREATES the substrate or the workspace around it, and a
role is reached through an accessor ON a store, so it cannot be what makes the
store exist. init.go alone is 3,060 lines; this commit touches the part that
happens inside the database.
TWO ROLES, AGAINST THE VersionReconciler PRECEDENT. That one is a read and a
write on one role because they are two shapes of one question, and every word of
that is true here too. The test that separates them is different: can one caller
be entitled to the READ and not the WRITE? Here yes, and not hypothetically —
`bd init --team-server` adopts a bts-provisioned identity and is forbidden to
write one, and a gateway credential may be read-only. Those paths now hold an
InitVerifier and never obtain a Bootstrapper, which the type system checks;
with one role they would hold the writer and the suppression would stay where it
is today, in three should* predicates on the CLI.
Q8 ANSWERED IN THE ROLE. Bootstrap over an already-identified substrate is
ErrAlreadyIdentified, carried by an *AlreadyIdentifiedError naming what was
found, decided from the same read the write would have followed inside ONE
transaction. Either marker is enough: a substrate several rigs share carries a
prefix one of them chose, and overwriting it renames every id the others are
about to mint. The guard now sits below both front doors instead of in front of
one, so gateway and adopt paths inherit it, and re-identifying is something
somebody asks for rather than something init does twice.
THE ROLE OWNS THE IDENTITY AND NOTHING ELSE. BootstrapProject wrote six values;
BootstrapRequest carries two. The fingerprints, the synced-at marker and the
recorded binary version are refreshed on EVERY init, adopt or not — a fresh clone
of an already-identified database needs its own fingerprints precisely because it
bootstrapped nothing — so a refusable one-time write would mean either a refusal
that stops recording them or a write that is no longer one-time. bd_version has a
second reason: it is VersionReconciler's key. The Dolt remote left too; it is
where the database syncs to, not what it is, and putting them in one call is what
let a remote that could not be created fail a bootstrap that had already
succeeded. domain.BootstrapUseCase is DELETED and domain.ConfigUseCase gains
SetMetadata, the write half of the GetMetadata it already published, so the
unit-of-work body can read, refuse and write in one transaction.
THE DEFECT. Proxied `bd init` against a database another rig had already
identified rewrote both markers with its own derived values. It verifies and
adopts now, printing the direct route's existing line, with the role's refusal as
the backstop. The direct route's two identity reads also became one snapshot, so
the prefix it adopts and the project id it reconciles against can no longer come
from either side of a concurrent write; shouldConsultInitProjectID still gates
whether the id is USED, so which identities init adopts is unchanged.
CONFORMANCE. backend/conformance/bootstrapper_contract.go holds twelve cases —
both roles in one file, because every promise on either is a statement about the
other — run at all three implementations with ZERO PARKS and zero divergences.
They deliberately do not re-test the decision: the validator's and the refusal's
whole tables are pinned without a database in internal/workapi/bootstrap_test.go.
What only a real backend can show is asserted instead: that the identity is there
for the NEXT caller (a new transaction on the unit-of-work backend), that a
refusal and a validation failure leave the markers EXACTLY as they were, that the
verifier reports an unreadable identity as an error rather than as an empty one,
and that a bootstrap costs at most one version-control entry. Two independent
bodies plus an engine check, not three votes: dolt and embeddeddolt share
internal/storage/issueops.BootstrapInTx and VerifyIdentityInTx and differ only in
how they reach a transaction. The bodies live there rather than in an importable
store<role> package because the read and the write it qualifies must see one
snapshot, which storage.DoltStorage cannot express — so there is no constructor
for a depguard entry to deny.
NO HTTP OPERATION, and that is a decision. A server can only serve a database it
is already bound to, and binding it required the identity this role writes, so
the only caller that could reach such an endpoint would be asking a running
server to identify a workspace that is by construction already identified — which
is the refusal. Bootstrapping over an unauthenticated surface is a different risk
class from reading one. The read half already has an endpoint:
ContextResponse.project_id on GET /v0/beads/context is InitVerifier's answer, on
the wire, today. Recorded in both leaf docs and in the checklist.
USER-VISIBLE, for the wave's changelog pass: proxied init adopts instead of
overwriting on a shared database; `bd init` no longer heals a substrate carrying
a prefix and no project id, which is Q8 as written; an explicit BEADS_DIR outside
the repo now gets a project id written from its own metadata.json instead of
being left half-identified. Reasoning and the alternatives are in
/data/tmp/sd-server/AMBIGUITIES.md as A-ini-0..7.
A-ini-0 IS A FALSE PREMISE IN THE BRIEF, not a finding about the code: bd-zl3u8,
bd-jtp1h and bd-yby99 do not exist in the workspace at BEADS_DIR. Verified by two
bd binaries failing to open it and by a direct SQL read of all 5,603 issues.
Everything else the brief asserted about the code checked out, so the spec used
was the brief plus Q8 plus A2.
Verified: build, vet, gofmt clean; golangci-lint 0 issues (its unparam check is
what found resolveInitIssuePrefix's now-dead `write` return, removed here);
TestBootstrapperContract 12/12 at dolt, embeddeddolt and uow; internal/workapi,
internal/storage, internal/telemetry, internal/jira, issueops, the root layering
pins and the whole internal/storage/domain and internal/storage/uow packages
green; internal/httpapi green and `make api-check` clean with no spec or
generated diff; TestInit* and TestResolveInit*/TestApplyInitGateway* and
TestCorpusGolden and TestDoctor* green under BEADS_TEST_EMBEDDED_DOLT=1;
TestProxiedServerExternalCreate, TestProxiedServerPing and TestProxiedServerUpdate
green under BEADS_TEST_PROXIED_SERVER=1, each of which runs
`bd init --proxied-server` in its harness; TestProxiedLookup green.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
THE TWO ROUTES DISAGREED ABOUT WHAT --force MEANS on a destructive command.
On a local database `--force` deletes the named beads and orphans their
dependents; on a team server it deleted the whole dependent subtree, `--cascade`
was REFUSED outright ("not supported in proxied-server mode (delete always
cascades)") and Cascade was hardcoded true at both call sites. So there was no
way to delete one bead on a team server without taking everything under it, and
asking for the safer behaviour was an error.
Q1 ANSWERED IN THE ROLE. issueops.Deleter has one method, reached through
store.Deleter() and the provider's own accessor, and the three modes are request
fields: no flags refuses over a dependent the request did not name, Force
orphans it, Cascade deletes the closure. The guard is workapi's and the body's,
below every front door, for the reason Sweeper's require-a-filter gate is: a
second front door that inherited the capability without the guard would orphan a
workspace's graph by omission — which is exactly what this commit's HTTP
operation would otherwise have been.
IT IS A DIFFERENT ROLE FROM Sweeper, not a mode of it. Sweeper erases a set the
caller DESCRIBED; this erases rows the caller NAMED. That is what decides where
each one's safety lives: a description can be accidentally too wide, so Sweeper
carries a require-a-filter refusal; a list of ids cannot be, so this one's guard
is about the graph.
THE DEFECT. The direct route's batch path deleted the rows in one transaction
and then rewrote `[deleted:ID]` into the neighbours' text afterwards, discarding
every update error. A failure in the window left a workspace whose beads were
gone and whose descriptions still cited them by id. The existence probe, the
guard, the cascade expansion, the deletion and the rewrite are now one
transaction. WHAT THAT COSTS is written into the leaf beside the promise: the
transaction is as large as the deletion plus its neighbourhood, so a batch with
a very large neighbourhood fails whole. It is NOT Sweeper's trade (bd-hysee) —
the delete itself was already one transaction on every route — and the part that
is new is named rather than measured, which is recorded for sign-off.
TWO MORE DEFECTS the single call site removed. The one-id path held its own
transaction that removed each edge by hand, so it never reported labels, events
or orphans; and `domain.DeleteIssuesParams.EnforceCascadePolicy` and `.Force`
were declared, documented in fifteen lines describing exactly these three modes,
and READ BY NOTHING. They are deleted; the policy lives in the role now.
THE CONTRACT IS WHAT WAS DELETED, not what was reported.
backend/conformance/deleter_contract.go holds eleven cases, each citing the leaf
doc, run at all three backends with ZERO PARKS and zero divergences. Every case
that acts asserts row counts through QueryScalar rather than trusting the result
the delete reported about itself. They are TWO INDEPENDENT BODIES plus an engine
check: dolt and embeddeddolt share internal/storage/issueops.DeleteInTx and
differ only in how they reach a transaction, and the unit-of-work provider
reaches the same questions through the domain use cases. It does NOT duplicate
backend/conformance/audit_issue-lifecycle.go, which stays the right home for
`DeleteIssues` at the STORAGE seam: that suite's Factory hands back a bare
storage.DoltStorage, so the unit-of-work backend — where the guard did not exist
at all before this commit — can never run a case placed there.
`bd serve` gains POST /v0/beads/issues:delete, spec first. The dependents guard,
the all-or-nothing id resolution and the reference rewrite are the role's, so
the handler is argument validation and a projection. `cascade` and `force`
default false, which is the guarded mode; DeleteIssuesResult is not
x-go-type-pinned for the reason SweepResult is not, and a reflection test keeps
the projection honest. No page envelope, so nothing to pin in pinning.go.
USER-VISIBLE, and the CHANGELOG says so loudly: a team-server script relying on
the implicit cascade starts leaving orphans; `bd delete <one-id>` without
--force now refuses over an outside dependent, converging the direct route's
three paths onto the answer two of them already gave; the proxied `--json`
result gains `orphaned_issues`. Reasoning and the alternatives are in
/data/tmp/sd-server/AMBIGUITIES.md as A-del-1..6.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
(regenerate-and-diff plus the httpapi suite) green; TestDeleterContract 11/11 at
dolt, embeddeddolt and uow; the internal/workapi delete unit tests; the
internal/storage, internal/telemetry and root layering pins;
TestConformance/Audit/issue-lifecycle and the dolt TestDeleteIssues* family
(this commit refactors DeleteIssuesInTx's guard); TestEmbeddedDelete,
TestEmbeddedDeleteJSONDependencyErrorContract, TestBurnWisps,
TestWispGCProtectsActiveWisps and TestCLI_WispGCExcludeType under
BEADS_TEST_EMBEDDED_DOLT=1; TestProxiedServerDelete{,ForceOrphans,Wisp,
Concurrent}, TestProxiedServerMolBurn and TestProxiedServerWispGC under
BEADS_TEST_PROXIED_SERVER=1; and TestProxiedLookup*.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
STAGE TWO OF TWO. Stage 1 (aa10a725e) added MaxRows and SkipCounts to
ListRequest and flipped no routes; this is the flip, plus the one role the
decoration needed.
TWO PARTS, and the role first because the flip needs it.
THE ROLE. `issueops.BlockingAnnotator` answers the decoration a listing prints
beside each row — `(parent: X, blocked by: Y, blocks: Z)` — for the ids of a
page that has already been chosen. It is its own role rather than EdgeReader
growth (Q12 asked and answered two), and the distance between them is larger
than it looks: EdgeReader returns STORED ROWS of every type with targets
spelled as stored, no status consulted, and a per-anchor Missing flag from an
existence probe; this one returns a DERIVED summary of two types with closed
blockers dropped, the inbound direction included, and NO existence probe at
all. It is not Reader growth either — it has no order of its own, nothing it
returns depends on how the page was chosen, and a ListRequest field would have
implied the annotation was part of the query.
THERE IS NO MISSING FLAG, and that is a decision the leaf states rather than an
omission: an id that names nothing and an id with no live blocking edges
decorate identically, so a probe would be a read whose answer no caller can
use. One conformance case asserts that ABSENCE of a distinction.
A BLOCKER THIS DATABASE HOLDS NO ROW FOR COUNTS AS OPEN — an `external:`
reference, a foreign-repository id, a row whose issue was deleted. An
unreadable status is not `closed`, and a listing that hid a blocker it could
not resolve would report work as unblocked on the strength of a row it never
found. Both implementations already did this; it now has a sentence and a case.
THE ORDER WITHIN EACH LIST IS NOW PINNED, ascending with repeats collapsed, and
this is the commit's ONE user-visible change. Both lists are joined into one
line of output, so the query's natural order was user-visible bytes that could
move between runs. It affects only rows with two or more live blockers, and it
is recorded as A-blk-2.
TWO BODIES, NOT THREE. dolt and embeddeddolt share
storage/issueops.ExecuteBlockingAnnotation inside their own read transaction;
the unit-of-work provider is the genuinely separate one — it reads BOTH
dependency tiers for every id and merges, where the store side partitions the
ids by plane, and it resolves statuses only for the ids a row mentioned.
FinishBlockingAnnotation is what makes the SHAPE of the answer one decision
rather than two. Seventeen cases, three wirings, ZERO PARKS.
THE HTTP HALF. GET /v0/beads/dependencies/blocking, spec first, `make api-gen`
after. `IssueBlocking` is x-go-type-pinned to the role package the way `Cycle`
and `CycleMember` are, and BOTH the schema and the envelope's Items are pinned
in internal/httpapi/pinning.go — the v2.6.0 allOf trap was checked (the
generated type is a bare alias) and bd-5o3gt did not become two. The size bound
is maxDependencyAnchors, SHARED with the stored-edge read rather than given a
constant of its own: the two operations are asked about the same page of ids,
and two numbers would let a client ask one about a page the other refuses.
`dependencies.blocking` joins the capability vocabulary; `checkDatabaseSource`
grows a required role, which is the edit that reaches code this commit did not
write.
THE FLIP, one mode at a time and named as such in the code. FIRST `--json`:
the role's List runs the same LoadStoreListConfig, the same BuildListFilter and
the same workapi.FinishPage the branch ran longhand, so the page is unchanged
bytes and ErrTooManyRows still reaches handleMaxRowsError for exit 2. SECOND
every text rendering, with SkipCounts set — stage 1 added that field for this
arrival, and without it the flip would trade a plain scan for three aggregate
joins on the most-run command in the tree. THIRD the decoration.
WHAT STAYS OFF THE ROLE is --watch and the hierarchical --parent tree, the two
modes that consume the FILTER as a value. The bead also named --deps and
--format, and its stated reason — "reach no epilogue on either route" — is
false for both: they run FinishPage and printTruncationHint today. What is
genuinely off-role in those two is the WHOLE-GRAPH dependency-record load they
perform, which is neither a page nor the blocking decoration; their page comes
from the role like every other mode's. Recorded as A-blk-3 with the reading
this commit proceeded under, which is also the reading stage 1's own message
states ("stage 2 moves bd list's TEXT path onto the role").
The proxied route loses `runListProxiedReady`: --ready is ListRequest.ReadyFlag
and picking the ready query from it is the role's job on both routes. Two
functions differing only in which use-case method they called is the drift this
replaces.
PROVABLY INERT AT THE CLI, measured rather than argued: 31 `bd list` / `bd
children` invocations — every output mode, both cap knobs, --ready, --parent,
--format, --deps — run against a binary built from integration/facade-wave-3
and one built from this commit, over ONE shared workspace, differ on exactly
the two multi-blocker lines A-blk-2 predicts and nothing else in 687 lines. A
base-against-base run isolates the one other moving line as the
once-per-period install tip.
The forbidigo exception list did NOT shrink, and the count in
issueops/reader.go's claim is unchanged. cmd/bd/list.go and
list_proxied_server.go were never on it; cmd/bd/list_show_filter_modes.go still
is, because the tree walk, the watch loop, the proxied builder call and `bd
show --current` all still name the type. Said in the config rather than implied
by silence.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; the seventeen new
cases at dolt, embeddeddolt (BEADS_TEST_EMBEDDED_DOLT=1) and uow, all green
with no skips; internal/httpapi and make api-check; internal/storage,
internal/telemetry, internal/jira, internal/workapi/..., issueops and the root
layering pins; the embedded `bd list`/`bd children`/max-rows CLI suites,
TestProxiedServerList under BEADS_TEST_PROXIED_SERVER=1 (58 subtests including
tree_parent, the three format modes, ready pagination and the three max-rows
refusals), TestProxiedLookup*, and the protocol corpus package.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd purge` selected closed wisps in one transaction and deleted them in
another. A bead closed, unpinned or cited in the window between the two was
judged on one state and acted on in a different one — the TOCTOU the bead
names — and the proxied twin held a second copy of the whole flow: its own
candidate filter, its own glob match, its own closed_at recheck, its own
reference scan and 190 lines of output kept character-identical to the direct
route's by hand.
PURGE AND PRUNE ARE ONE CAPABILITY, which the design left open and the code
answers plainly: both routes already ran ONE function with a `purgeScope`
struct choosing the tier. So issueops.Sweeper has ONE method, reached through
store.Sweeper() and the provider's own accessor, and SweepRequest.Tier selects
the plane — `ephemeral` is purge, `durable` is prune, and the two are disjoint
by construction. What genuinely differed became request fields rather than a
second role: the require-a-filter refusal keys on Tier, and the citation
protection is ASKED FOR (ProtectReferenced) instead of being inferred from a
command name, which is what the shared body did (`scope.cmdName == "prune"`).
Q9 ANSWERED IN THE ROLE. The require-a-filter gate is
workapi.ValidateSweepRequest, below every front door: a durable sweep with
neither a cutoff nor an id pattern is ErrValidation. It is a safety invariant,
not presentation — without it a second front door is one handler away from an
unguarded mass delete, which is exactly what this commit's HTTP operation would
otherwise have been. The CLI keeps its friendly message, and says in place that
it is there for the WORDING while the guard is the role's; the contract case is
what proves the guard survives that branch being deleted.
THE DEFECT, AND ITS PRICE. The whole sweep is now one transaction, so the set
the result describes IS the set it deleted. That gives up the server-backed
store's batched wisp deletion (200 per transaction, added for Dolt's 10s write
timeout after bd-2ehd and ff-tqm): a sweep too large now fails WHOLE. That is
the better failure — the partial one it replaces reported a deleted count of
ZERO while having deleted rows — and the other two backends already worked this
way. It is written down as a promise WITH its cost, and recorded for sign-off.
TWO MORE DEFECTS the single call site removed. `--dry-run` passed force=false
to the delete where the real run passed force=true, so a preview could FAIL
over dependents the sweep would have orphaned — and the CLI answered that
failure with zeros. And `filepath.Match`'s error was discarded on both routes,
so `--pattern '['` printed "No closed beads to prune" and exited 0; it is now
ErrValidation quoting the pattern.
THE CONTRACT IS WHAT WAS DELETED, not what was reported.
backend/conformance/sweeper_contract.go holds ten cases, each citing the leaf
doc, run at all three backends with ZERO PARKS and zero divergences. Every case
that acts asserts row counts through QueryScalar rather than trusting the
result the sweep reported about itself, which on a destructive operation is the
assertion that matters; every case scopes itself with an id pattern, because a
sweep is asked of a whole TIER and an unscoped one would clear the next case's
seeds. They are TWO INDEPENDENT BODIES plus an engine check: dolt and
embeddeddolt share internal/storage/issueops.SweepInTx and differ only in how
they reach a transaction, and the unit-of-work provider reaches the same four
questions through the domain use cases.
THE HTTP OPERATION, spec first (per bd-jtp1h's A2 scope decision):
POST /v0/beads/issues:sweep, capability `issues.sweep` — the first DESTRUCTIVE
operation on a surface that was reads plus one claim. It is a collection-level
custom method with a body rather than DELETE with a query string, because a
dropped query parameter widens what is erased where an unknown body member is
refused by name. The handler decodes six members and calls the role; it does
not implement the safety gate, the tier vocabulary or the glob, all of which
are the role's ErrValidation reaching the wire as a 400 through failSweepErr.
No component carries allOf and none is x-go-type-pinned — there is no canonical
Go struct whose JSON encoding is this body, since the CLI publishes these
numbers under `purged_count`/`pruned_count` — so the projection is tested
instead. `bd serve --help` grew a DESTRUCTIVE OPERATIONS section and the
--allow-non-loopback warning now says peers can bulk-delete closed beads.
`bd gc` keeps the closed-candidate recheck by calling the SAME pure function
the role calls (workapi.FilterSweepCandidates), so the two cannot drift; the
reference matcher and its 10K-body budget moved to internal/workapi with the
scan. cmd/bd/purge.go and purge_proxied_server.go LEFT the forbidigo exception
list, which is how a role commit proves its front doors reached the role.
USER-VISIBLE, for the wave's changelog pass: the version-control label for a
sweep is now `bd: sweep <n> <tier> bead(s)` on both routes, where proxied wrote
`bd: prune <n> bead(s)` and direct wrote `bd: delete <n> issue(s)` — an HTTP
sweep is not `bd prune`, so the label names the operation and the tier from
every door; a malformed `--pattern` now exits non-zero; `--dry-run` no longer
refuses over dependents the real sweep orphans; and `bd serve` gains a
bulk-delete endpoint. Reasoning and the alternatives are in
/data/tmp/sd-server/AMBIGUITIES.md as A-swp-1..9.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
(regenerate-and-diff plus the httpapi suite) green; TestSweeperContract 10/10 at
dolt, embeddeddolt and uow; the internal/workapi, internal/storage and
internal/telemetry suites; TestEmbeddedPurge, TestEmbeddedPurgeConcurrent,
TestEmbeddedPrune, TestPrune_protectsBeadCitedByCustomStatusBead and
TestEmbeddedGC under BEADS_TEST_EMBEDDED_DOLT=1; TestProxiedServerPrune under
BEADS_TEST_PROXIED_SERVER=1; TestProxiedLookup*; and the root layering pins.
The protocol corpus has no purge/prune case to account for.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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>
`bd query "type=bug OR label=urgent"` has been answering with a prefix of its
answer and calling it complete. The expression language has OR, NOT and
parentheses, which no storage filter expresses, so both routes fetched a WINDOW
of candidate rows — max(3*limit, 100) — and applied the expression to those in
memory. A match past row 100 was absent from the page and unreported by
has-more. The same six lines of arithmetic were written twice, once per route,
and both copies were wrong in the same way.
THE ROLE. issueops.Querier, reached through store.Querier() and the provider's
own accessor. One method over a request whose predicate is a SENTENCE rather
than a set of fields, which is what makes it a role instead of a mode of
Reader: a ListRequest is a conjunction — every field narrows — and no
arrangement of its twelve callers' fields expresses a disjunction. It is
equally not a raw query passthrough; the language names no table, no join and
no column outside a closed vocabulary, which is why a contract can promise
anything about it at all.
THE FIX, which Q3 approved as user-visible. A predicate query's filter now
carries NO row limit: the predicate sees every candidate row, the page is the
first Limit MATCHES of the complete matching set, and has-more is exact. The
decision has one home, internal/workapi.BuildQueryPlan, which both bodies
execute. The cost is stated rather than hidden — a broad OR over a large
workspace now reads every row its base filters admit — and CHANGELOG.md says so
in the same words.
WHAT PINS THE FIX, at three levels, because the contract alone cannot see it.
TestBuildQueryPlanLeavesAPredicateQueryUNBOUNDED asserts the arithmetic in
microseconds. TestAPredicateQueryFindsAMatchBeyondTheOldWindow seeds 101 rows at
ONE backend and reads back the match at row 101 — verified to discriminate:
with the old window temporarily reinstated it returns zero rows. The portable
contract asserts the PROMISE the window broke (a page is a prefix, has-more is
exact) and, confirmed by the same experiment, does NOT discriminate the old
window at its small scale; the contract's header says so rather than implying
coverage it does not have.
THE CONTRACT. backend/conformance/querier_contract.go holds nine cases, each
citing the leaf doc by line, run at all three backends with ZERO parks. TWO
independent bodies plus an engine check: dolt and embeddeddolt share
internal/workapi/storequerier, and the unit-of-work provider is genuinely
separate — it is the only leg on which the Offset case takes its HONORED branch,
since that seam renders OFFSET where the store body refuses uniformly.
TWO SMALLER USER-VISIBLE CHANGES ride along, both filed in AMBIGUITIES.md
(Q22, Q23) for the owner's batch. `--offset` with an OR/NOT expression is no
longer refused: the offset skips MATCHES, which is only meaningful now that
every match is seen, so an error became an answer. `--limit -1` is now
ErrValidation instead of an undocumented second spelling of unlimited. The
`--offset` + `--sort` refusal survives and moved INWARD — the role makes it, for
every caller, because the order is applied to the rows the query bounded and
each page of an offset walk would be sorted for itself — so its wording changed
with its address, as did the wording of a malformed expression on both routes.
A DEFECT FOUND AND NOT FIXED, recorded as A-qry-1 rather than papered over: an
UNLIMITED request carrying an Offset renders SQL the Dolt engine answers with a
recovered panic (makeslice: cap out of range, out of topRowsIter). It predates
this role — `bd query --offset N --limit 0 --proxied-server` built the same
filter — and it is a storage-seam bug, so the contract case asks its question at
a bounded limit and says why at the case site.
THE HTTP OPERATION, spec first (per bd-jtp1h's A2 scope decision):
GET /v0/beads/issues:query, capability `issues.query`, answering a new QueryPage
{items, has_more}. It publishes no cursor and no `offset`: a predicate query's
matching set is assembled outside the database, so there is no keyset position
to encode, and an offset is honored by one database source and refused by the
other, which is not a difference to put on a wire. QueryPage carries no allOf
and its Items are pinned in pinning.go beside ReadyPage's and IssuesPage's — the
edit wave 2 missed once (bd-8ri3m). Adding a second sort enum made oapi-codegen
disambiguate the FIRST one, renaming the generated ListReadyWorkParamsSort
constants (Hybrid -> ListReadyWorkParamsSortHybrid); nothing outside the
generated file named them. httpapi.Config's roles source grows a required eighth
member, and a Config complete under the previous release is now refused at
Listen rather than nil-dereferencing on the first issues:query request.
WHAT ELSE CONVERGED. Both output modes read ONE query — the counted one --json
always used — so a predicate can no longer be applied to two different row sets
depending on the flag (A-qry-1's neighbour, Q24). The direct route prints the
truncation hint for the first time, not by new choice but because it finally has
an honest has-more to print.
Incidental: internal/storage/role_accessor_decorator_test.go's four
near-identical "the four read roles" paragraphs — one appended by each wave-2
slice — are collapsed into the one accurate paragraph the table needs. Same
defect as bd-8ri3m, comments only.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check green;
TestQuerierContract 9/9 at dolt, embeddeddolt and uow;
TestAPredicateQueryFindsAMatchBeyondTheOldWindow; the internal/httpapi package
suite; internal/workapi, internal/storage, internal/telemetry, internal/query
and the root package; TestEmbeddedQuery under BEADS_TEST_EMBEDDED_DOLT=1 and
TestProxiedServerQuery under BEADS_TEST_PROXIED_SERVER=1; TestProxiedLookup*.
The protocol corpus drives no `bd query` invocation and is untouched.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The version markers had two implementations of one rule. The direct route read
bd_version and bd_version_max out of the metadata plane in
cmd/bd/version_tracking.go, compared them with doctor.CompareVersions and wrote
them back; the proxied route opened a unit of work and called a ReconcileVersion
method on the config use case, which held its own copy of the same comparison,
the same two downgrade guards and the same high-water rule. The two agreed, but
nothing made them agree and no test compared them. Both now ask for a role, and
the difference between the routes is which accessor answers.
THE ROLE BELONGS TO NO COMMAND, and it is the only one in this programme that
does not. It fires from PersistentPreRun on EVERY startup, on both routes,
before the command the user typed has run — which is exactly why it went
unnoticed: `bd version` prints two strings, opens no store and reaches none of
this, so the state machinery was hiding behind a command that does not use it.
THAT ORIGIN IS A CONSTRAINT ON THE PROMISES, not a piece of history, and the
leaf doc says so where a reader will meet it. A role that runs before every
command pays for itself on every command, so it does two point reads on the path
that changes nothing, loads no configuration, takes no lock, repairs nothing —
and, the clause that matters most, it NEVER refuses the command in front of it.
A downgrade is an OUTCOME with a nil error, because an older binary is allowed
to use a workspace a newer one has opened; a genuine failure is an error the
CALLER logs and walks past, which both front doors do at debug level. A role
whose callers must ignore its errors has to say so where the promise is made
rather than leave each caller to decide.
TWO METHODS, ONE ROLE. RecordedVersion and ReconcileVersion are two shapes of
one question — the write's promise IS a statement about what a later read
returns — which is what the governing rule permits a role to be born with, and
WorkspaceConfig set the precedent. It is not padding: the direct front door
needs the READ alone. autoMigrateOnVersionBump probes a read-only store first so
an already-current workspace never pays for the writable open, and before this
commit that probe read the metadata key by hand — the "CLI knows the storage
key" shape this programme exists to remove, on the hottest path in the codebase.
WHY IT IS NOT WorkspaceConfig WITH TWO MORE KEYS. Two planes, two lifetimes. A
workspace setting is durable and travels with the database; these two markers
are dolt-ignored, do not survive a clone and are deliberately different per
machine. Publishing them through the settings plane would put a value that
cannot be shared behind an interface whose whole promise is that its values are.
ONE DECISION, THREE SUBSTRATES. workapi.PlanVersionReconcile is the pure planner
every implementation decides through; domain.ConfigUseCase LOSES ReconcileVersion
and gains SetLocalMetadata, the write half of the GetLocalMetadata it already
published, so the unit-of-work body can read, plan and write in ONE transaction.
Deleting the use-case method is what makes the rule single-sourced rather than
duplicated under a role.
CONFORMANCE. backend/conformance/version_reconciler_contract.go holds nine cases
run at all three implementations with ZERO parks and zero divergences. They
deliberately do NOT re-test the decision: the planner's whole table — upgrade,
no-op, both refusals, the catch-up to the mark, the dotted comparison in which
1.2.0 and 1.2.0-rc1 are equal — is pinned without a database in
internal/workapi/versionreconcile_test.go, and repeating it here would be
testing one pure function three times over three sql-servers. What only a real
backend can show is asserted instead: that a recorded marker is there for the
next caller (a new transaction on the unit-of-work backend), that a refusal and
a validation failure write NOTHING, that reconciliation adds no history entry at
all, and that a reconciliation which CANNOT COMPLETE reports an error and leaves
both markers standing. Two independent bodies plus an engine check, not three
votes: dolt and embeddeddolt share internal/workapi/storeversionreconciler.
The fixture carries one hook the frozen roleFixtureKit cannot supply, built at
each wiring site the way CycleDetectorFixture.Exec is: the two states that
matter most — a recorded version BELOW the high-water mark, and its catch-up —
are states the role can never produce, so they are seeded past it.
THIS IS THE FIRST COVERAGE THE DIRECT ROUTE'S RECONCILIATION HAS EVER HAD. Its
round-trip tests (MigratesVersion, AlreadyMigrated, RefusesDowngrade,
TracksMaxVersion) were deleted with the SQLite backend and never replaced; the
note recording that is still in cmd/bd/version_tracking_test.go. The seven
subtests of the deleted use-case method go with it, replaced by the exhaustive
planner table plus nine cases at three backends.
NO HTTP OPERATION, and that is a decision rather than an omission — recorded in
the leaf doc and as A-ver-2 for the owner. The markers are clone-local: they
describe the machine holding the database, so a remote client reading them
learns something it cannot compare against anything it holds. The one version
fact a client CAN act on, the serving binary's release, is already published as
ContextResponse.bd_version, which the document already names as the only field a
client may compare as a version. A write endpoint is worse: reconciliation is an
effect of a PROCESS STARTING, and a client asking a server to record the
client's version would be asking it to lie about which binary holds the
database. If the owner wants a read-only GET /v0/beads/version, the role, the
accessor and both bodies are already here.
NO USER-VISIBLE CHANGE. Every outcome is identical; only three debug lines
moved. One accidental behaviour became deliberate: a binary whose Version string
is empty used to be handled by the downgrade guard on a populated workspace and
by an equality short-circuit on an empty one, and is now an explicit
ErrValidation that writes nothing either way.
ENFORCEMENT. storeversionreconciler joins the cmd-bd-role-constructors deny
list. The version path never named types.IssueFilter, so there is no forbidigo
exception to remove. engdocs/ADDING_AN_ISSUEOPS_ROLE.md gains the two things
this role taught the checklist: a role may honestly have NO HTTP surface, and a
contract case may need a fixture hook for a state the role cannot produce.
Verified: build, vet, gofmt clean; golangci-lint 0 issues;
TestVersionReconcilerContract green at dolt (9/9), embeddeddolt (9/9) and uow
(9/9); the planner unit tests, both decorator enumerations, the root layering
pins, internal/jira and the internal/storage/domain/db config suite green;
internal/httpapi green and `make api-check` clean with no spec or generated
diff; TestReconcileVersionPersistsAcrossUOW green; TestProxiedLookup green;
`-run 'TestTrackBdVersion|TestAutoMigrateOnVersionBump|TestGetVersionsSince|TestMaybeShowUpgradeNotification|TestInitDoltMetadata'`
green under BEADS_TEST_EMBEDDED_DOLT and TestProxiedServerContext /
TestProxiedServerInfo green under BEADS_TEST_PROXIED_SERVER; TestCorpusGolden
green, so no command's JSON moved.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd ready --limit 100` prints "showing 100 of 412", and the 412 came from
nowhere in particular. The direct route computed it inline: unwrap past the
storage decorators, type-assert to storage.ReadyWorkCounter, and fall back to
an unbounded ready query when the assertion missed — twice, once in the --json
branch and once in the text one, with two different fallbacks. The proxied
route could not compute it at all and published no `total` key, so the same
script read a number under one workspace topology and nothing under another.
THE ROLE. issueops.ReadyCounter, reached through store.ReadyCounter() and the
provider's own accessor. It answers a question neither neighbour can: Reader
answers with a PAGE and its verdict is has-more ("did the limit hide
anything"), where this is "how many" — strictly larger, and already published
output, so collapsing the two would change what a shipped surface says. Counter
answers a predicate over one table, and the ready predicate is blocker-aware:
it reads the dependency graph and the wisp tier, which no CountRequest can
describe. Counter's own doc already said the count of ready work would be its
own role for that reason.
It takes issueops.ReadyRequest VERBATIM, the precedent ClaimNextRequest set, so
a listing, a claim and a count ask ONE question of ONE set. Limit and Offset are
ErrValidation for the reason a claim refuses them: a cardinality has no page, so
a limit would answer "how many of the first N" and an offset would subtract the
rows it skipped from the size of a set that still holds them.
THE CONTRACT IS AN IDENTITY, not a resemblance:
CountReady(r).Total == len(Reader.Ready(r with Limit=0).Items)
at every implementation. backend/conformance/ready_counter_contract.go holds
seven cases, each citing the leaf doc by line, run at all three backends with
ZERO parks. They are TWO independent bodies plus an engine check: dolt and
embeddeddolt share internal/workapi/storereadycounter (one indexed COUNT(*) per
plane minus their overlap), and the unit-of-work provider is genuinely separate
code that runs the unbounded ready query and takes its length — which is why
the wisp-tier case is written the way it is, since that is where a COUNT and
the page it sizes are assembled by different arithmetic.
A DEFECT THIS FOUND, and it is not the count's. `bd ready`'s directory-label
default (GH#541) never reached the ReadyClaimer role. claimNextRequest re-ran
the gatherer's own emptiness test against in.filter — and the gatherer had
already written the default INTO that filter, so the test saw a non-empty label
set and skipped. The branch could never fire. In a directory with
`directory.labels` configured, `bd ready --claim` therefore claimed from the
WHOLE ready front while `bd ready` beside it listed only the configured scope:
exactly the "hand an agent work the listing never offered it" that
ReadyClaimer's contract exists to forbid. The gatherer now RECORDS its decision
(readyInput.dirLabels) and both roles read it, so there is one answer instead of
two derivations of it. Caught by writing the count's own test for the same
line, and pinned by cmd/bd/ready_role_request_test.go.
WHAT ELSE CONVERGED. Both routes and both output modes now ask one question
through one accessor: the direct route's two inline epilogues become one call,
and the proxied route's `pagination.total` exists for the first time. The
"showing X of N" text a human reads and the total a script parses are the same
number by construction. cmd/bd no longer names storage.ReadyWorkCounter at all
— the capability is required by the store body's PARAMETER TYPE, so a backend
that cannot size the ready set fails to compile instead of falling back to a
mega-query at runtime.
THE HTTP OPERATION, spec first (per bd-jtp1h's A2 scope decision):
GET /v0/beads/ready:count, capability `ready.count`, answering
`ReadyCount {total}`. It publishes no `limit` and no `sort`: a cardinality has
no page and no order, and the handler sends the listing's own sort default so
the request stays the listing's request rather than one that resembles it. The
filter vocabulary is decoded by ONE function shared with GET /v0/beads/ready
(readyFilters), so the two operations cannot admit different parameters — which
is what the identity rests on over the wire.
`TestCountReadyAndListReadyAdmitTheSameFilters` compares the two predicates
built from one query string. No component here carries allOf and none is
x-go-type-pinned: the pinned seven are canonical Go structs whose JSON encoding
IS the contract, and there is no canonical struct for this number — the CLI
publishes it inside its own stdout envelope, which is not a wire type — so
pinning would weld the body to a CLI presentation type rather than prevent a
drift. The generated output was read to confirm it (a struct with `Total
int64`, not an alias), which is the v2.6.0 trap this document warns about.
httpapi.Config's ROLES database source grows a REQUIRED third member. That is
the sharp edge for the next role commit and is now written down in
engdocs/ADDING_AN_ISSUEOPS_ROLE.md as step 13: a Config carrying the old pair
would bind and then nil-dereference on the first request that reached the new
handler, so Listen refuses it with the same message a half-set pair gets.
USER-VISIBLE, for the wave's changelog pass: proxied `bd ready --json --limit N`
now publishes `pagination.total`; `bd ready --claim` now honours the
directory-label scope on both routes.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
(regenerate-and-diff plus the httpapi suite) green; TestReadyCounterContract
7/7 at dolt, embeddeddolt and uow; the httpapi package suite; the direct-route
`bd ready` suites under BEADS_TEST_EMBEDDED_DOLT=1 and the proxied ones under
BEADS_TEST_PROXIED_SERVER=1, including the pagination envelope that now asserts
the total; TestProxiedLookup*; and the ready protocol-corpus tests, which are
byte-identical.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd status` (and its `bd stats` alias) had two implementations of the same
command. The direct route asked the store for statistics and, under
--assigned, built an assignee filter, ran a ready-work query and folded
five status counts itself; status_proxied_server.go did all four again
through a unit of work. Both now build an issueops request and ask for the
role, and the difference between the two routes is which accessor answers.
THE ROLE. Its numbers are DEPENDENCY-AWARE — the blocked count reads the
denormalized transitive is_blocked flag and readiness is derived from it —
so no predicate over the issues table describes them and this is its own
role rather than a sixth Counter dimension, which is what issueops/
counter.go already said it would be. Stats and AssigneeStats are born
together because they answer the same question of two sets; they are two
METHODS rather than one with an Assignee field because the assignee answer
fills four fields of the same struct by different definitions, and a
request whose optional string silently changed what a number meant is the
shape this programme exists to remove.
WHAT THE LEAF DOC NOW SAYS OUT LOUD, none of it written down anywhere
before: BlockedIssues counts the graph, not the "blocked" status;
ReadyIssues is arithmetic and NOT the cardinality of `bd ready`;
PinnedIssues overlaps every status bucket so the buckets do not sum to
Total; the workspace-wide answer excludes the wisp tier while the
assignee-scoped one merges it; --no-blocked is a HINT whose only report is
BlockedIssues being nil; and EpicsEligibleForClosure and AverageLeadTime
are structurally always zero, which is why `bd status`'s "Extended:"
branch has never once printed.
CONFORMANCE. backend/conformance/stats_reporter_contract.go holds thirteen
cases, each citing the leaf doc by line, run at all three implementations
with ZERO parks and zero divergences. Unusually for this suite they are
THREE genuine votes: the two stores share the role body (storestats) but
dolt/queries.go, embeddeddolt/statistics.go and domain/db/issue.go each
spell the blocked count and the ready subtraction themselves. Every
workspace-wide case asserts a before/after DELTA — a summary takes no
predicate, so there is no IDFilter to scope it with the way the Counter
contract scopes its cases.
HTTP. GET /v0/beads/stats is added to the Tier-1 document FIRST and the
types generated from it: a `Statistics` schema x-go-type-pinned to
types.Statistics (checked: the pin survives, and the schema is now in the
JSON-tag bijection test), a StatsResponse envelope mirroring the CLI's
--json shape minus `recent_activity`, which no shipped path populates. The
handler calls the same role both CLI routes call. `blocked_count_skipped`
is DERIVED from the answer, never echoed from the request, because the
hint is a hint. httpapi.Config's roles source grows a third field and
requires it with the other two: a source that answers some operations and
faults on others is not a source.
ENFORCEMENT. cmd/bd/status.go and status_proxied_server.go no longer name
types.IssueFilter or types.WorkFilter, so `status` LEAVES the forbidigo
exception list (63 -> 61 of 388 files). The role-constructor depguard list
gains storestats.
TWO USER-VISIBLE CHANGES, both improvements and both small: `bd status
--assigned` reports the underlying failure instead of the bare "failed to
get assigned statistics", identically on both routes; and the proxied
--no-blocked warning now fires from the ANSWER rather than from the route,
so a backend that gains a fast path stops printing it with no edit.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; make api-check
clean (no codegen drift, whole httpapi package green);
TestStatsReporterContract 13/13 at dolt, embeddeddolt and uow;
TestEmbeddedStatus and TestProxiedServerStatus green with their gates set;
TestProxiedLookup green; TestCorpusGolden green.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd config` had two implementations of the same four verbs. The direct route
called store.SetConfig/GetConfig/GetAllConfig/DeleteConfig in cmd/bd/config.go;
the proxied route opened its own unit of work and called the config use case in
config_proxied_server.go, then printed the same lines a hundred lines away. Both
now build an issueops request and ask for the role, and the difference between
the two routes is which accessor answers.
THE ROLE. issueops.WorkspaceConfig is the workspace's DURABLE SETTINGS PLANE:
the key-value rows the workspace database holds. It is born with four methods
because read, write, remove and enumerate over ONE keyed namespace are four
shapes of one question — the governing rule forbids appending to a role, not a
role being born whole — and because their promises are statements about each
other: SetSetting's promise is about what a later GetSetting returns, and
UnsetSetting's about what a later ListSettings omits.
The methods are GetSetting/ListSettings/SetSetting/UnsetSetting rather than
Get/List/Set/Unset, and that is not verbosity. Reader already has Get and List,
and the decorator conformance tests drive ONE sentinel that implements every
role at once; two roles with the same method name and different signatures make
that sentinel unwritable. The collision was the design telling us the short
names belong to issues.
ONLY THE KV SLICE IS A ROLE, and the rest is a deliberate no. `bd config show`,
`drift`, `apply` and `validate` are multi-source diagnostics over config.yaml,
environment variables, git config, this plane and server state at once. Three of
those five sources are files on the CLIENT's filesystem, which a server
answering for a remote workspace can never read, so a substrate role claiming to
answer them would be claiming to see something it cannot. `bd config set-many`
is off the role too, for a different reason: it exists to make N keys ONE Dolt
commit, the role writes and commits one setting per call, and
TestProxiedServerConfigSetMany pins the difference. A batched write is a
separate capability, exactly as `bd create --file` stays off Lifecycle.Create.
TWO LIVE DEFECTS FIXED.
1. THE PROJECTION, which is the Q11 user-visible change. Reads of the custom
status and type vocabularies are TABLE-first: they consult custom_statuses
and custom_types and fall back to the config string only when the table is
empty. The store backends have always rewritten the table in the same
transaction as the row; the unit-of-work backend wrote only the string. So
on a team server `bd config set types.custom "session"` reported success,
`bd config get` read it back, `bd doctor` re-verified against the string and
reported all-OK, and `bd create -t session` answered "invalid issue type"
for as long as the workspace lived. Fixed where dab71c5eb fixed it — in the
config repository, so the row and its projection commit together — and
verified by reverting the fix and watching ProjectsCustomStatuses and
ProjectsCustomTypes fail on uow alone.
2. `bd config set-many issue_prefix=x` re-prefixed the workspace. The
single-key verb refuses the prefix in both spellings and points at
`bd init --prefix`, `bd bootstrap` and `bd rename-prefix`; set-many
partitioned its pairs by source and wrote the database ones straight
through, so it never saw that guard. Beads created before the write and
after it disagreed about their own namespace with nothing to reconcile
them. The refusal is now in the role for every caller that goes through it,
and at set-many's front door because it does not.
THE BRIEF'S THIRD PREMISE IS FALSE, and it is worth saying so: "uow SetConfig
skips issue_prefix normalization" is not true at this base.
configSQLRepositoryImpl.SetConfig has trimmed the trailing hyphen since the file
was created (4fcbd5882, verified with git log -L). The normalization half needed
no fix; the custom-table half did, and dab71c5eb is NOT in this base.
WHAT ELSE CONVERGED. The status.custom parse lived in THREE places (both routes
of `bd config set` plus set-many) and is now one; the routing that stays at the
front door — which source owns a key, and whether writing it would leak a secret
into git — stays there, because those are questions about files on this machine.
CONFORMANCE. backend/conformance/workspaceconfig_contract.go holds fourteen
cases run at all three implementations with ZERO parks. Its shape is
deliberately not the issue contracts': there are no rows to seed, so it asserts
PRECEDENCE (which of two writes a later read sees, and whether a refusal leaves
the earlier value standing) and SIDE EFFECTS. Every projection case reads the
TABLE through QueryScalar rather than reading the setting back through the role,
because reading it back through the role is exactly the check that passed on the
backend where nothing took effect. Two independent bodies plus an engine check,
not three votes: dolt and embeddeddolt share
internal/workapi/storeworkspaceconfig.
TWO ASYMMETRIES ARE PINNED RATHER THAN FIXED, because all three backends agree
and closing either is a user-visible change this slice was not approved for.
UnsetSetting does not undo SetSetting's projection, so removing types.custom
leaves the custom types applying (bd-yby99.33); and `bd config unset
issue_prefix` is not refused where `bd config set` is (bd-yby99.34). Both are
stated in the leaf doc and asserted by a case, so neither can drift or be closed
on one backend while the owner decides.
HTTP. GET /v0/beads/config and GET /v0/beads/config/{key}, spec-first, taking
the v0 surface from six operations to eight. A setting whose KEY marks it as
credential-bearing — notion.token is database-backed — is published with
`redacted: true` and NO value: withheld values are omitted rather than masked,
which is the document's own "verbatim or absent" rule, and the CLI is unchanged
because its caller already holds the database while this surface has no
authentication. There is no HTTP WRITE, and that is the honest answer rather
than a hedge: `bd config set` routes most keys to config.yaml or git config
before the database is reached, so a server-side PUT of `export.auto` would
return 200 and land a row nothing reads. `Setting` is the one unpinned response
component, with the reason in the document beside it — the CLI marshals an
ad-hoc map, so there is no canonical struct to pin to, and minting one would
mean changing `bd config get --json` in order to satisfy a rule about not
changing it. All three are recorded in AMBIGUITIES.md as A-cfg-1..3.
ENFORCEMENT. storeworkspaceconfig joins the cmd-bd-role-constructors deny list.
`bd config` never named types.IssueFilter, so there is no forbidigo exception to
remove. engdocs/ADDING_AN_ISSUEOPS_ROLE.md gains what step 12 now costs since
the owner's scope decision: the spec operation, the route row, the Op constant
and operationCodes row, the capability token, and the Config field that a
store-shaped database source must now carry.
Verified: build, vet, gofmt clean; golangci-lint 0 issues;
TestWorkspaceConfigContract green at dolt (14/14), embeddeddolt (14/14) and uow
(14/14); the workapi validator unit tests, the two decorator enumerations, the
root layering pins and internal/jira green; internal/httpapi green and
`make api-check` clean; TestProxiedLookup green; `-run Config` green under
BEADS_TEST_EMBEDDED_DOLT and, under BEADS_TEST_PROXIED_SERVER, green except
TestConfigValidateReadOnlyIsHermetic, which fails identically on a pristine base
worktree under the same filter and passes standalone on both. TestCorpusGolden
green, so `bd config --json` is byte-identical to the committed corpus.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`bd count` had two implementations of the same command. The direct route
built a types.IssueFilter in cmd/bd/count.go, loaded the workspace list
config and applied the --include-infra policy; the proxied route did all
four again in count_proxied_server.go and executed against the use case.
Both now build an issueops.CountRequest and ask for the role, and the
difference between the two routes is which accessor answers.
THE ROLE. Counts are NUMBERS; Reader answers PAGES OF ISSUES. Different
question, so its own role per the governing rule rather than a counted
variant on Reader: a count has no order, no page and no cursor, and a
request type carrying paging fields a count must ignore is the shape that
makes a caller believe --limit 10 bounded the answer. Count and
CountByGroup are two shapes of ONE question and cannot be separated in
practice - the grouped answer carries the scalar Total, because label
buckets overlap and the sum is wrong - so the role is born with both.
WHAT CONVERGED, beyond the duplication:
- the wisp-tier policy. BuildCountFilter is now the single definition of
what `bd count` means, beside BuildListFilter, and the GH#4387
cardinality-parity test moved from cmd/bd to internal/workapi where it
compares the two SHARED builders instead of a CLI helper against one
of them.
- the grouped Total. "use the scalar count, not the sum, because label
buckets overlap" lived in cmd/bd; an HTTP surface adding grouped
counts would have had to rediscover it.
- the config load. It happens inside the role, and only under
IncludeInfra, so a plain count still makes one query.
CONFORMANCE. backend/conformance/counter_contract.go holds twelve cases,
each citing the leaf doc by line, run at all three implementations with
ZERO parks. They are TWO independent votes plus an engine check, not
three: dolt and embeddeddolt both hand back internal/workapi/storecounter,
and the unit-of-work provider is the second body.
ENFORCEMENT. cmd/bd/count.go no longer names types.IssueFilter, so `count`
LEAVES the forbidigo exception list - the hole it needed is closed rather
than merely unused. The reader-constructor depguard rule becomes
cmd-bd-role-constructors and gains storecounter, so it is a list the next
role extends by one line instead of a rule per role.
NO HTTP HANDLER EXISTS for count. `bd serve` publishes /healthz,
/v0/beads/context, /v0/beads/ready, /v0/beads/issues, /v0/beads/issues/{id}
and POST /v0/beads/issues/{id}:claim, and the spec is Tier-1 ratified, so
none was invented.
THE PER-ROLE COST, which no design budgeted, is now written down in
engdocs/ADDING_AN_ISSUEOPS_ROLE.md: twelve steps derived from this commit,
naming the accessor line in internal/storage/storage.go, the hook and
telemetry wrappers, the two store accessors, the unit-of-work source, the
three conformance wirings, the five places each decorator enumeration
lists a role, and the two lint edits. Every later new-role commit follows
it.
Verified: build, vet, gofmt clean; golangci-lint 0 issues;
TestCounterContract green at dolt (12/12), embeddeddolt (12/12) and uow
(12/12); TestEmbeddedCount* and TestProxiedServerCount* green with their
gates set; TestCorpusGolden green, so `bd count --json` is byte-identical
to the committed protocol corpus.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Beads had two implementations of most issue verbs: one for the direct route
(the CLI talking to a store it opened itself) and one for the proxied-server
route (the CLI talking through a unit of work over a running Dolt server).
They drifted — different commit messages, different transaction boundaries,
different refusals, occasionally different answers.
Seven role interfaces now live in the leaf package issueops: Lifecycle,
Reader, ReadyClaimer, BatchCloser, DependencyEditor, Commenter and Relations.
Each is reached only through a store accessor, never a constructor, because
the accessor is where the hook and telemetry decorators add their layers.
Three implementations back every role — dolt, embeddeddolt, and the
unit-of-work provider the proxied route uses. Both routes call the same role
for close, dep add/remove/list, comment, ready --claim and update.
A depguard rule (httpapi-domain-boundary) denies internal/storage/domain from
internal/httpapi, so a handler cannot reach uw.IssueUseCase() past the roles
and open a second front door one lint-clean commit at a time.
Behaviour users will notice, all in the CHANGELOG:
- bd close a b c is one Dolt commit, not three, and --claim-next moved
inside that transaction so it fires only when something landed
- the open-children guard moved into the transaction and its hand-rolled
cmd/bd copy is gone, removing a read-then-write window that made
bd close <child> <parent> depend on argument order
- bd dep add --file honours deferred version commit
- embedded bd comment writes the role's message and author
- dep verb commit messages are the role's on the direct route
Wisp-sourced dependency edges are restored. Moving bd dep add onto the role
had pinned an edge's SOURCE to the issues plane, and the two routes did not
even fail alike: direct refused with "issue <id> not found", proxied threw an
fk_dep_issue violation. The comment justifying the pin claimed the issues
plane was "the only one its unit-of-work sibling can reach" — that was false;
domain.DependencyUseCase declared a full set of wisp twins with no production
caller. All three implementations now route per edge by the edge's own
source. A mixed request stays one transaction: parent-child-first ordering
and the whole-graph cycle gate span both planes, and a refusal rolls back
both. Behind the role, three bulk add verbs collapsed into one source-routed
AddDependencies, so no plane-pinned variant is left to reach for by mistake.
Six Provenance fields with no production caller were deleted rather than
wired — CloseRequest, CloseBatchRequest, ClaimNextRequest, AddCommentRequest,
AddDependenciesRequest, RemoveDependencyRequest. Each role already composes an
id-bearing message, so a caller could only restate the default and make it
unreachable from production. Two are not caller-settable even in principle:
CloseBatchCommitMessage names what LANDED and ClaimNextCommitMessage names the
id the claim WON. UpdateRequest and ReopenRequest keep theirs; commit messages
users see are unchanged.
Verified: build, vet and gofmt clean; golangci-lint 0 issues; protocol corpus
byte-identical under BEADS_PROTOCOL_REQUIRE_DOLT=1; all twelve
DependencyEditor conformance wirings green (four contract functions against
each implementation); TestEmbeddedDepAddWispSource runs bd dep add <wisp-id>
at the front door and was demonstrated RED against the pinned routing first.
Three internal/storage/dolt failures reproduce on pristine origin/main.
Known gaps are enumerated in the PR description rather than left to be found:
comment listing is on no role, bd dep tree and bd dep cycles have no role,
bd create and bd reopen are on Lifecycle only on the direct route, per-edge
line attribution is lost in bd dep add --file, multi-store bd close
--claim-next rides only the first store's batch, and the is_blocked staging gap
(bd-2y9ke, predates this change). Seven of the eight role interfaces now have a
shared conformance contract in backend/conformance, run at all three
implementations; main's Claimer, added in parallel by #5334, is the eighth and
has none yet.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two claims were true of the function and not of the sentence around it.
"EXECUTION through workapi.FinishPage for `bd list` on both routes" is
mode-scoped and did not say so. The hierarchical --parent tree under
pretty output reaches no epilogue on either route: the direct route
computes a page at list.go, then discards it for getHierarchicalChildren's
recursive walk, and the proxied route returns into
runListProxiedHierarchicalParent before FinishPage is called at all.
Neither sorts, trims or reports has-more. Every other listing - JSON,
plain text, --watch, --ready - does run the epilogue, so the correction
is "in every mode but one", named, rather than a retreat to "shares
something".
FinishPage's own doc said a limit of 0 means "nothing is cut and there
is by definition nothing more". The first half is what the code does; the
second is not. With limit 0 the cut is skipped and the hasMore SEED is
returned unchanged, so a seam that already reported more rows behind an
unlimited request keeps saying so - which is the honest answer, since a
cut that never ran cannot contradict it. The doc now describes that, and
the test case that carried the old wording in its name is split: one case
for "never cut", one new case for a true seed surviving limit 0.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The doc comments claimed the property at the level it was true and
hand-waved the rest. They now say the whole of it, per surface:
- every read the HTTP surface answers goes through the role, and two lint
rules make reaching past it a lint failure;
- `bd show --json` is on the role on BOTH routes now, keeping only its own
id resolution, which has no place on a contract an HTTP client calls;
- `bd ready` and `bd list` are on neither route, and will not be until
there are more roles to route them through — what they share is the
builders (pinned by golden files) and, for list on both routes and ready
on the proxied one, workapi.FinishPage;
- `bd ready`'s DIRECT route shares no epilogue and cannot, because it
publishes a hidden-row total the role has no member for. Said plainly
rather than left out.
claimOnUOW records the claim-path decision instead of leaving it
unexplained: the CAS is already ONE implementation a level below both
surfaces (domain issueUseCaseImpl.claim, which ClaimIssue and
ApplyUpdate's spec.Claim arm are two names for), so there is no claim
logic above it to extract. What is above it is a batch-with-per-id-exit-
codes on one side and a typed 409 on the other, and a function spanning
those would be two halves with one caller each.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Both surfaces already shared CONSTRUCTION — one BuildListFilter, one
BuildReadyFilter, both over the same issueops request types, both pinned
by the builders' golden files. They executed separately: the two Reader
implementations applied the over-fetch/sort/trim/HasMore tail, and each
CLI route applied its own copy. That tail had already drifted twice, and
both times it was the same bug in the same three lines written in two
places — a --ready page under a sort the database cannot express came
back untrimmed from one implementation, and the proxied route answered
`--sort id --limit 5` with every row while the direct route answered
with five.
workapi.FinishPage is now that tail, once. It is called by both
issueops.Reader implementations, by both of `bd list`'s routes, and by
the proxied `bd ready` listing. Nothing about the contract widened: the
epilogue takes rows, an order, a page limit and the seam's own has-more,
and answers with the page and the verdict. A seam that reports has-more
natively seeds it; a seam that does not passes false and lets the
over-fetched row speak.
`bd ready`'s DIRECT route keeps its own epilogue, and the comment in
ready_input.go now says so instead of claiming otherwise: it answers the
strictly larger question "how many rows were hidden" with a second
counting query and publishes the total in its pagination meta, which the
role has no way to express and the CLI cannot stop printing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`workapi.NewStoreReader` was exported and lived in internal/workapi, which 22
cmd/bd files already import for the builders. It takes storage.DoltStorage — an
interface a command already holds — so it was a one-line drop-in replacement for
`store.IssueReader()` from any front door, and the wrong one: every storage
decorator adds its layer in its OWN accessor (telemetry's reader-level spans, the
hook store's deliberate pass-through), so a command that constructed a reader
directly would get a bare unspanned one and the code would look entirely
ordinary. The old doc comment said "nothing does; the accessor is the door",
which is a promise, not a guard.
It has real callers, so it cannot simply be unexported: dolt.DoltStore and
embeddeddolt.EmbeddedDoltStore both need one shared body for their accessors,
and they are in different packages. So the body moves down to
internal/workapi/storereader instead, where those two are the only importers,
and the cmd-bd-reader-constructor depguard rule keeps cmd/bd out. Nothing about
internal/httpapi changes: depguard matches pkg by prefix, so
httpapi-transport-boundary already denied the subpackage along with its parent.
The two store packages' own NewIssueReader are unexported at the same time. They
had no caller but their own accessor, they are in internal/ so no out-of-tree
consumer can reach them, and leaving them exported would have left the same door
open one package over.
SEEN TO FAIL, on the golangci-lint version CI installs. `bd show --json` switched
from the accessor to the constructor — the exact bypass — compiles and vets
clean:
$ golangci-lint run --config=.golangci.yml --build-tags=gms_pure_go ./...
cmd/bd/show.go:15:2: import
'github.com/steveyegge/beads/internal/workapi/storereader' is not allowed from
list 'cmd-bd-reader-constructor': a command reaches the reader role through
store.IssueReader(), never through the constructor ... (depguard)
exit 1
ErrUnsupported.Op moves with the function, "NewStoreReader" -> "storereader.New",
so the Op still names the function that refused; its test moves with it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
"Both front doors can only say rd.List(ctx, req)" was false for two of three
operations on the CLI side. `bd ready` and `bd list` still load config, build a
filter and stamp the --max-rows cap on it, on BOTH their routes — the exact
ritual the role exists to make unwritable — and five doc comments asserted
otherwise, including the leaf contract's own.
The gap is real and is not closed by moving MaxRows onto the leaf requests:
those commands consume the FILTER for --claim, --gated, --explain, --mol,
--watch, the hierarchical --parent tree and the text renderings that want
[]*types.Issue rather than a counted page. Routing only their JSON paths
through the role would fork each command in two, which is more drift, not
less. Closing it needs more roles, not more methods on this one.
So every claim now states its scope: the HTTP surface is on the role for all
three operations and machine-checked; `bd show --json` is on the role; the two
paging commands are not, and their protection is one level down — the same
builders over the same request types, pinned by the builders' golden files. The
two sites that still call the builders say why, in place.
Third structural divergence recorded on the parity oracle, which listed only
two: the endpoint always defaults to workapi.DefaultListLimit, while `bd list`
resolves a five-way CLI policy first (explicit --limit, --all, configured
list.limit, piped stdout -> unlimited per GH#4094, agent mode -> 20), so the
shared request-level default is unreachable from the CLI and `bd list --json |
...` swapped for the HTTP call loses rows past 50. The oracle passes an
explicit limit on both sides, so it never saw this.
TestListLimitPolicyIsResolvedBeforeTheRequest pins the policy branch by branch
against a real initialized config — removing the piped branch makes it report
50 where the CLI promises 0.
Two comments still naming the deleted ReadyParams type now name
issueops.ReadyRequest.
storeReader.Ready and storeReader.List had zero coverage: no front door reaches
them (the CLI's paging commands still call the builders directly, and the HTTP
surface goes through the uow reader), so the over-fetch and trim that moved out
of cmd/bd/list.go lived unexercised. They are pinned now — the +1 probe row, the
trim back to the page limit, an exact page reported as complete, an unlimited
query left unlimited, and SQLLimit's two cases — against a fake DoltStorage
that honors the row limit the way a query would.
TestCursorRoundTrips never round-tripped. The fixture's CreatedAt was the zero
time, decodeCursor rejects a zero instant as an empty position, so `ok` was
always false and BOTH assertion branches were dead: the test passed with
encodeCursor broken outright. It now mints from a real instant and asserts the
id and the instant come back exactly; dropping CreatedAt from cursorFor fails it.
Also aligns the nil-store refusal's Op with the constructor it names
(NewStoreReader, matching the store packages' NewIssueReader), which the new
test asserts.
The frozen document says an invalid `metadata_field` key is a 400. It was a
500: the only check lived in the SQL builder, so the failure arrived wrapped in
the storage method's name ("GetReadyWorkWithCounts: invalid metadata key ...")
— a shape nothing above storage can classify — and client typos landed in the
request_error alarm stream. Three doc comments already claimed otherwise,
including the leaf contract's "Keys are validated inside", which no Reader
implementation did.
Both builders now call one validator, so the claim is true of every
implementation of the role rather than of the CLI's flag parsing only. The CLI
keeps its own usage errors: it validates the same input at flag-parse time and
reaches the builder with the keys already checked, so its messages and exit
codes are untouched.
invalidFilterParam gains the two prefixes, and every row of that switch — the
three that were already there included — is now driven end to end by
TestABuilderRefusalIsTheDocumentedBadRequest. `invalid issue type ` was pinned
nowhere before: rewording it in list.go turns ?type=bogus into a 500 and now
fails that test.
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.