8 commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
d10a388340 |
feat(list): put bd list behind Reader.List and the new BlockingAnnotator role (bd-5k21g)
STAGE TWO OF TWO. Stage 1 (
|
||
|
|
aa10a725e5 |
feat(list): put bd list's row cap and counts hydration on ListRequest (bd-b34o7)
STAGE ONE OF TWO. Fields, not methods, and no route flips — those are stage 2
(bd-5k21g). `issueops.ListRequest` gains MaxRows, MaxRowsSource and SkipCounts,
each with a conformance contract running at all three backends and zero parks.
MAXROWS IS THE EXACT INVERSE OF OFFSET, which is why it needed no new shape.
Offset is honored by the unit-of-work body — it renders OFFSET — and refused by
the store-backed one with a typed *ErrUnsupported. The cap points the other way:
the store search path enforces it after the scan (EnforceMaxRowsCap), and the
unit-of-work query path (internal/storage/domain/db) reads no cap at all, so a
request carrying one would come back as the FULL uncapped answer with nothing on
it to say so — a caller that set a circuit breaker handed exactly the runaway
query it was guarding against. It refuses instead, naming the operation and the
backend. `bd list --max-rows --proxied-server` has always refused one layer up
in the CLI for that reason; this is the same refusal for the callers that are
not the CLI. RunReaderListMaxRowsIsHonoredOrRefused mirrors
RunReaderOffsetIsHonoredOrRefused, including the never-silently-ignored clause,
and asserts the complement too: a cap the result set FITS inside must still come
back as an ordinary page, or a body that refused every cap out of hand would
pass.
MAXROWSSOURCE is the third field and the bead named two. It is attribution
only — it decides no answer — but `handleMaxRowsError` falls back to
"BEADS_MAX_ROWS" when it is empty, so a request that carried the number without
the source would make stage 2's route flip start telling operators to raise the
wrong knob. The contract asserts it comes back on the cap error.
SKIPCOUNTS is the SkipLabels precedent one column over: the three cardinality
joins are dropped and DependencyCount/DependentCount/CommentCount come back
zero, to be read as unknown rather than as none. It has to land WITH MaxRows —
stage 2 moves `bd list`'s TEXT path onto the role, and that path calls
SearchIssues today and projects no counts at all, so arriving on a counted page
without a way to opt out is a straight perf regression. The expensive member is
the reverse-blocker aggregate, which joins on a COALESCE key the pure-Go
analyzer cannot auto-index — the known embedded sore point, and the reason the
knob is worth having at all.
The contract's second half is the load-bearing one: NOTHING ELSE MOVES. Same
rows, same order, same has-more, same Parent — asserted by running the identical
request both ways rather than against a written-out expectation. Parent is the
tripwire: it rides the same mega-query and is not a cardinality, so an
implementation that made an aggregate join inner, or suppressed the parent join
too, would answer a strict subset and still look like it had "skipped the
counts".
WHAT THE SQL DOES. sqlbuild.SearchCountsSQL's two trailing hydration bools
become one CountsHydration value, so a path cannot pick up one opt-out and drop
the other, and both stores plus the unit-of-work repository read the pair
through one helper. A suppressed aggregate is projected as a constant IN PLACE
rather than removed: the scan reads the six extra columns positionally, so the
shape is invariant. Ready work passes the zero value at every call site —
types.WorkFilter carries neither knob, which is what "SkipLabels and SkipCounts
are not carried onto the ReadyFlag arm" means, now stated where a caller reads
it. MaxRows IS carried there; reader_ready_scope.go already claimed so, and this
is the commit that makes the claim true, since until now the field existed only
on the filter.
ONE HAND-ROLL DELETED. `bd list` built the filter through the shared builder and
then reached in and stamped filter.MaxRows/MaxRowsSource onto it — the
"build it, then change it" half-step this programme exists to make unreachable,
and the reason the cap was invisible to every implementation of Reader.List. The
cap is resolved in gatherListInput onto the request, BuildListFilter is now the
only writer of those two filter fields, and the proxied refusal reads the
already-resolved value (rejectResolvedMaxRowsUnderProxiedServer) so a malformed
BEADS_MAX_ROWS still warns exactly once.
PROVABLY INERT AT THE CLI, measured rather than argued: 22 `bd list` / `bd
children` invocations — every output mode, both max-rows knobs, the malformed
and negative cases — run against a binary built from integration/facade-wave-2
and one built from this commit, over ONE shared workspace so both read identical
data, differ on exactly one line of 617. `bd list --max-rows -1 --status bogus`
now reports the malformed flag instead of the invalid status; both exit 1, it
needs two bad arguments to reach, and it is recorded as A-lst1-3.
NO OPENAPI OPERATION AND NO NEW QUERY PARAMETER, deliberately, recorded as
A-lst1-1. `bd list`'s operation (GET /v0/beads/issues) already exists and is
already on the role, and neither field can be published on it yet: `bd serve`
always builds a provider-backed server, which REFUSES max_rows, so the parameter
would be one the reference server can never honor; and skip_counts would set
three unconditional integers on a PINNED response component to zero, leaving a
client unable to tell "no dependencies" from "not computed" — the failure
comments_omitted exists to prevent on the detail view. `make api-check`
regenerates nothing.
Verified: build, vet, gofmt clean; golangci-lint 0 issues; the two new cases at
dolt, embeddeddolt (BEADS_TEST_EMBEDDED_DOLT=1) and uow, plus the whole Reader
contract at all three; the builder golden (35 recorded cases plus two new ones
for the new fields) and the counts-SQL shape test; internal/httpapi and
make api-check; internal/storage/{issueops,domain/...}, internal/workapi,
internal/types, internal/telemetry, the root package; the embedded
`bd list`/`bd children`/max-rows CLI suites, TestProxiedServerList under
BEADS_TEST_PROXIED_SERVER=1 (including reject_max_rows_flag,
reject_max_rows_env and allow_max_rows_zero), TestProxiedLookup*, and the
protocol corpus package.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
||
|
|
0380accb62 |
feat(issueops): put bd count behind the Counter role (bd-m8hn7)
`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>
|
||
|
|
d801ec43dc |
feat(issueops): put every issue capability behind one library surface
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>
|
||
|
|
7f7f27de6c |
docs(workapi): say where the shared epilogue stops, and what limit 0 does
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> |
||
|
|
a0d38c5d34 |
docs: state exactly what the reader role now enforces, and what it does not
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> |
||
|
|
1108af95ee |
refactor(workapi): one execution epilogue for every list and ready read
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> |
||
|
|
de9fc833e2 |
refactor(workapi): move the store reader where a front door cannot reach it
`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> |
Renamed from internal/workapi/reader_store.go (Browse further)