beads/issueops
Julian Knutsen 3eab445b0a
Add issueops.GraphCounter: how many edges, in one named direction (ga-itny5) (#5485)
* Add issueops.GraphCounter: how many edges, in one named direction (ga-itny5)

The graph counts are the last read on the storage surface with no role behind
them. `storage.DoltStorage` publishes CountDependents, CountDependencies and
CountDependentsByStatus as three methods that differ only in a direction and a
narrowing, and every one of them is a raw method a front door can call with no
decorator, no probe and no plane story. This is their facade.

ONE METHOD, AND THE DIRECTION IS IN THE REQUEST. The raw seam spells the
direction in the METHOD NAME, which is the one thing a request field can get
wrong, so `EdgeCountRequest.Direction` is REQUIRED and an empty one is
ErrValidation before anything is read — including for a request that names no
ids at all, which is otherwise the empty answer EdgeReader gives. There is no
`both`: the two numbers are over different edge sets, summing them
double-counts an edge between two requested anchors, and a paired answer would
make Status — which narrows by a row only the inbound direction has — govern
half an answer silently. internal/workapi's detail assembly already makes two
calls for the pair today, so nothing pays a round trip it was not paying.

STATUS IS INBOUND-ONLY AND SAYS SO RATHER THAN BEING IGNORED. Narrowing by
status means joining the far end of an edge to the row holding its status, and
an OUTBOUND edge's far end may be a row this database does not hold — an
"external:" reference or a foreign-repository id, both of which
DependencyEditor accepts. A status filter there would silently drop every
dangling edge, which is the class of edge EdgeReader exists to return verbatim.
The raw seam has the same asymmetry: CountDependentsByStatus exists and
CountDependenciesByStatus does not.

A MISSING ANCHOR IS A FLAG, NOT ErrNotFound. 0 is the common answer — most
issues have no edges in at least one direction — so an id typo would never
surface, and a batch that failed on one absent id would discard the answers for
the ids that were found. That is EdgeReader's rule, and it is what forces the
existence probe and the tally into ONE transaction.

WHAT IS EXCLUDED, since the never-append rule makes each one a decision. The
COMMENT count is genuinely consumed — `bd show` prints it beside the two edge
counts — and is still out: a comment has no direction, no type and no far end,
so every field of the request below IDs would be meaningless to it. CountEvents
has no caller in the tree at all and follows the journal. GetDependencyCounts
is expressible as two calls with Types set to the blocking type, and naming it
as a method would have added a map-shaped answer no wire operation can carry.

THREE LEGS, ONE BODY. All three reach issueops.ExecuteEdgeCount — the two
stores wrap it in their own read transaction, the unit of work reaches it
through the domain repository, whose runner publishes exactly the DBTX method
set — so the contract header says one reading plus two engine checks and three
wrapper checks, not "three backends agree". Validation moved INSIDE that body
for the same reason: with one body there is no second implementation for a
per-leg check to belong to.

FACADE ONLY. No HTTP operation: the wire half follows in the graph-counts wire
slice per the program's council gating. No `bd` command either, and that is the
larger of the two decisions — the numbers are printed today through
internal/workapi's detail seam, which an HTTP handler shares, so moving it is a
change with its own parity argument. Both absences are written into the leaf
doc beside the promises, as VersionReconciler writes down its absent HTTP half
and BatchApplier its absent CLI.

Contract: 14 cases, wired on all three legs. Mutation-checked — a constant
count reddens 7 including both per-direction cases, ignoring the direction
reddens the 4 inbound ones, and dropping the ephemeral plane reddens the 2
cross-plane ones. The pure halves (the request vocabulary, the missing-anchor
rule, the SQL shape) are pinned without a database beside the body.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Review: reattach the Importer note, cite the collision, size the id list

Three corrections, none behavioral.

The four-line note about Importer's uow-only accessor was left stranded above
the GraphCounter row by this slice's insertion, where it asserted three things
that are false of it: GraphCounter IS a storage.DoltStorage accessor, a
store-built backend CAN fill its field, and importer_contract.go's header says
nothing about it. Moved back onto the row it describes.

"Nothing in this contract's reach can produce one" reads too easily as "it
cannot happen". A cross-table id collision is real and constructed:
TestDependentRecordsCrossTableCollision seeds one logical edge into both
dependency tables and names the two production paths that make them — a wisp
promoted to durable, and two Dolt clones merged. The leaf now cites it and says
what this role promises against it (the sum) versus what
CountDependentRecords' question is (the distinct total).

And EdgeCountRequest.IDs says out loud that it carries no size cap, which
EdgeReadRequest.IDs also does not: the bound belongs to the wire operation,
where the request arrives from somewhere else and the cost of an unbounded one
is a stranger's. ApplyBatchRequest.Items makes the same split explicitly.

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>
2026-08-09 11:29:32 -07:00
..
batchapplier.go Add issueops.BatchApplier: one plan, one transaction (#5480) 2026-08-09 06:59:34 -07:00
batchcloser.go Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436) 2026-08-08 11:23:34 -07:00
batchcreator.go feat(create): put bd create --file behind the BatchCreator role (bd-lu170) 2026-08-05 16:43:11 +00:00
blockedstate.go Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436) 2026-08-08 11:23:34 -07:00
blockingannotator.go feat(list): put bd list behind Reader.List and the new BlockingAnnotator role (bd-5k21g) 2026-08-06 02:56:57 +00:00
bootstrapper.go feat(init): put bd init's identity seam behind Bootstrapper and InitVerifier (bd-zl3u8) 2026-08-06 03:01:33 +00:00
claimer.go chore: retire a zombie test, drop a dead field, true up two leaf docs (#5492) 2026-08-09 10:42:34 -07:00
claimer_external_test.go Add issueops.Claimer and route the HTTP claim through it (#5334) 2026-08-04 08:40:18 -07:00
commenter.go chore: retire a zombie test, drop a dead field, true up two leaf docs (#5492) 2026-08-09 10:42:34 -07:00
counter.go feat(issueops): put bd count behind the Counter role (bd-m8hn7) 2026-08-05 05:27:39 +00:00
cycledetector.go feat(issueops): put bd dep cycles behind the CycleDetector role (bd-wfkbv) 2026-08-05 09:36:14 +00:00
deleter.go Add DeleteRequest.ExpectedVersion: a compare-and-delete on the named row (#5481) 2026-08-09 07:17:54 -07:00
dependencyeditor.go Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436) 2026-08-08 11:23:34 -07:00
edgereader.go feat(issueops): put multi-id bd dep list behind the EdgeReader role (bd-nhsno) 2026-08-05 09:42:06 +00:00
errors.go Add issueops.Releaser: give a claim back, optionally only a named holder's (#5482) 2026-08-09 07:48:56 -07:00
graphcounter.go Add issueops.GraphCounter: how many edges, in one named direction (ga-itny5) (#5485) 2026-08-09 11:29:32 -07:00
importer.go feat(import): port bd import to proxied-server mode (bd-o58fz) (#5355) 2026-08-05 09:05:22 -07:00
initverifier.go feat(init): put bd init's identity seam behind Bootstrapper and InitVerifier (bd-zl3u8) 2026-08-06 03:01:33 +00:00
issueops.go Pin the is_blocked invariant as a postcondition of the roles that maintain it (#5436) 2026-08-08 11:23:34 -07:00
issueops_external_test.go feat(issueops): name the two dependency-endpoint refusals (bd-yby99.9) 2026-08-07 19:45:54 +00:00
metadatacas.go Add issueops.MetadataCAS: compare-and-set over one metadata key (#5473) 2026-08-09 04:15:34 -07:00
querier.go Converge Offset and MaxRows on all three legs, and fix the panic and the breaker hole under them (#5435) 2026-08-08 11:37:09 -07:00
reader.go Admit the ephemeral plane from a list request, on the facade and on the wire (#5476) 2026-08-09 05:06:36 -07:00
reader_ready_scope.go Admit the ephemeral plane from a list request, on the facade and on the wire (#5476) 2026-08-09 05:06:36 -07:00
readyclaimer.go feat(issueops): put every issue capability behind one library surface 2026-08-04 12:27:56 -07:00
readycounter.go feat(ready): put bd ready's published total behind the ReadyCounter role (bd-s10oa) 2026-08-05 09:47:24 +00:00
relations.go feat(issueops): put every issue capability behind one library surface 2026-08-04 12:27:56 -07:00
releaser.go Add issueops.Releaser: give a claim back, optionally only a named holder's (#5482) 2026-08-09 07:48:56 -07:00
statsreporter.go Wave 2 review fixes: dep list shape, stats 400, and the blocked-count promise 2026-08-06 21:18:26 +00:00
sweeper.go Version embedded role deletes and sweeps, and replace the range that hid it (#5458) 2026-08-08 23:53:57 -07:00
treewalker.go Converge Offset and MaxRows on all three legs, and fix the panic and the breaker hole under them (#5435) 2026-08-08 11:37:09 -07:00
versionreconciler.go feat(issueops): put the startup version reconciler behind the VersionReconciler role (bd-gkmft) 2026-08-05 16:35:01 +00:00
workspaceconfig.go Refuse kv.* point reads on the settings role and stop printing them (#5493) 2026-08-09 11:06:51 -07:00