beads/internal/httpapi
Julian Knutsen 2a4b75b810
Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540)
Relations is one of the facade methods the ext-api-store audit lists with no
wire operation, and it is the one gc's infra-over-http read surface cannot do
without: `bd dep list`'s dependents view has no other direction-aware wire path,
because EdgeReader is outgoing-only. This is that operation. The role, its
contract and all three legs already exist; this slice wires them.

Spec first, then `make api-gen`, then the handler.

IT IS A SUB-RESOURCE OF THE ISSUE, and the argument is ELEMENT IDENTITY rather
than a claim about what the dependency collection answers with — getDependencyTree
answers hydrated TreeNodes, so "everything under /dependencies is about edges"
would be false and is not said. What decides it is narrower and checkable: the
rows here are the SAME pinned struct `GET /v0/beads/issues/{id}` already carries
under `dependencies` and `dependents`, so this operation is that pair,
standalone, direction-parameterized and type-filterable, and it belongs on the
resource whose members it publishes: `/v0/beads/issues/{id}/related`. The route table's first sub-resource: the
segment is a LITERAL after a single-segment wildcard, so pattern and specPath
agree and the claim row's exception does not apply. It collides with nothing —
`/v0/beads/issues/{id}` is a different whole path, which is what ServeMux
matches on, and the custom-method dispatcher is POST-only and one segment
shorter.

The consequence is stated in the document rather than left to be discovered:
the length of `items` is a NEIGHBOR count and not an EDGE count, because a
target that is an `external:` reference or another repository's id has no far
end here and is silently not a neighbor. The same edge IS a row on
`GET /v0/beads/dependencies`. That single observation is what separates the two
operations, and the proxied test asserts both halves of it against real Dolt.

THE ANCHOR-BOUND maxItems GATE DOES NOT APPLY. The facade signature is
single-anchor — one `RelatedRequest.ID`, not a slice — so there is no question
to bound at 100 the way the three dependency-collection reads bound theirs, and
`TestSpecDefaultsMatchSharedConstants`' three-op loop is deliberately untouched.
The other side of single-anchor is the 404: those reads report a miss per anchor
because failing would throw away the ids that were found, and here there is one
anchor and nothing to preserve. `getDependencyTree`'s operationCodes row,
unchanged, is this one's.

TWO-PLANE, AND BOTH HALVES ARE REAL. The neighbours are collected from
`dependencies` AND `wisp_dependencies` and hydrated from `issues` AND `wisps`,
so a durable anchor's `in` answer includes the wisps that depend on it and a
wisp id is a legal ANCHOR. Resolved from the bodies, not assumed, and pinned
against real Dolt: a durable anchor with one durable and one wisp dependent
answers two, and the wisp element carries `ephemeral` — which is what catches an
implementation that spanned the edge tables and hydrated one issue table.

VALIDATION STAYS IN THE ROLE, on `dependencies:count`'s terms rather than
`issues:count`'s. Relations has two bodies and every accessor calls
ValidateRelatedRequest, so its refusals are reachable over the wire: the handler
forwards `direction` raw and classifies on the sentinel, naming the parameter by
re-asking the validator's own questions in its own order. Only two of the
validator's three refusals are reachable — the path bound turns an unusable id
into the 404 a real miss gets, which is why there is no `id` arm in the picker
and why the tests say so.

Census: +1 spec path, +1 schema (`RelatedIssues`, unpinned for `EdgeCounts`'
reason — the element under it is the pinned one), +1 route row, +1 capability
(`issues.related`, hand-edited only in the document's vocabulary — `Capabilities()`
is derived and untouched), +1 `Op*` const, +1 `operationCodes` row, +1 required
`Config` field with its `sourceRoles`/`roleSourceNames`/accessor lines, +1 `bd
serve` binding. No code was minted: every problem code on the row is inherited.

THE "STEP WITH NO NUMBER" IS NOW A BUILD ERROR, and this is the first role to
measure that rather than assert it. #5539 landed the serveRoleSource subset while
this was in review, so `IssueRelations` joins that interface and both `cmd/bd`
stubs are COMPELLED to declare it — omitting either is

    *serveRolesStore does not implement serveRoleSource (missing method IssueRelations)

in the file that has to grow the method, checked both ways. Counter and
GraphCounter had to be FOUND, the second only by a full-package CI shard; this
one could not be missed. Both stub comments are rewritten to say so: the
promoted-method-on-a-nil-embed narrative is history now, not instruction, and on
the identity stub the surviving load-bearing fact is PLACEMENT — the accessor
sits at depth 1, shallower than serveStubRest's nil store, so it shadows the
promotion and the assertion can see it. Swept for a third stub site reaching this
path: serve_registered_backend_test.go reuses serveIdentityDoltStore and a real
embeddeddolt.Open, so there is none. A drive-by one-liner beside all that:
timedProvider gained the `uow.GraphCounterSource` compile-time assertion #5536's
accessor landed without.

One arm was DELETED after measurement. failRelatedErr shipped with an explicit
`storage.ErrNotFound` case, mutating it out left every case in the package green
— ClassifyError already carries that row, so the 404 travels through the one
shared mapping — and a green arm named for half the contract is worse than no
arm. The ErrValidation arm is the opposite: deleting it turns every refusal on
this operation into a generic 500, and both measurements are recorded at the
site.

Evidence, six mutations. The picker's arms collapsed reddens the four direction
cases and nothing else; the ErrValidation arm deleted reddens all five refusal
cases; `items` as a nil slice reddens the empty-array case; the path bound
dropped reddens the impossible-anchor case; the dependents read narrowed to
`dependencies` and the hydration narrowed to `issues` each redden the two-plane
case against real Dolt at 1-of-2. A seventh, a json tag on types.Issue.RowVersion,
reddens the no-revision case — and TestWireTagBijection too, which the test now
says out loud.

Rebased onto #5539 (06b0dffb2). Fable review: APPROVE, zero blocking findings
— the reviewer re-ran every mutation, probed the router live (an issue literally
named "related" does not shadow the detail read), and confirmed the
environmental-failure set name-identical to pristine main. Its one INFO, the
overclaimed placement rationale, is the paragraph rewritten above.

Gates: `make api-check` a no-op, `go build ./...`, `go vet ./...`, `gofmt -l`
clean, `internal/httpapi` + `internal/telemetry` + `internal/storage` +
`internal/storage/uow` (the nine-minute parity run) green, and
`BEADS_TEST_PROXIED_SERVER=1 CGO_ENABLED=1 go test ./cmd/bd/ -run
TestProxiedServerServeRelatedIssues` green against real Dolt in five cases. The
pre-commit hook's `go run golangci-lint@v2.10.1` downgrades the toolchain to
go1.25 and refuses this go1.26.5 module outright (ga-2ltro.13), so the
CI-pinned binary was run by hand — `golangci-lint run --new-from-rev=origin/main`,
0 issues — and this commits with --no-verify citing that bead.

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-10 05:23:30 -07:00
..
apigen Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540) 2026-08-10 05:23:30 -07:00
spec Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540) 2026-08-10 05:23:30 -07:00
auth.go feat(serve): optional bearer auth and a Host allowlist for bd serve (#5516) 2026-08-09 18:05:56 -07:00
auth_test.go feat(serve): optional bearer auth and a Host allowlist for bd serve (#5516) 2026-08-09 18:05:56 -07:00
batch_apply.go Publish the row-version guard on close, reopen and delete (#5506) 2026-08-09 17:02:53 -07:00
batch_apply_test.go Add issueops.BatchApplier: one plan, one transaction (#5480) 2026-08-09 06:59:34 -07:00
batch_close.go claimNext + batchClose + incremental labels: the three role-backed ops with no wire (ga-g3gg8) (#5510) 2026-08-09 16:02:52 -07:00
batch_close_test.go Make the next serve role a compile error, and check the one role with a positional result (#5539) 2026-08-10 04:34:15 -07:00
batch_create.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
batch_create_test.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
blocking.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
blocking_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
claim.go Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540) 2026-08-10 05:23:30 -07:00
claim_next.go claimNext + batchClose + incremental labels: the three role-backed ops with no wire (ga-g3gg8) (#5510) 2026-08-09 16:02:52 -07:00
claim_next_test.go claimNext + batchClose + incremental labels: the three role-backed ops with no wire (ga-g3gg8) (#5510) 2026-08-09 16:02:52 -07:00
claim_test.go Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -07:00
close.go Publish the row-version guard on close, reopen and delete (#5506) 2026-08-09 17:02:53 -07:00
close_test.go Publish the row-version guard on close, reopen and delete (#5506) 2026-08-09 17:02:53 -07:00
context_test.go feat(serve): bd serve skeleton — lifecycle, mode gate, /healthz, /v0/beads/context (bd-60z) 2026-07-31 10:07:14 +00:00
count_test.go Publish GET /v0/beads/issues:count, with the role's whole filter surface (#5508) 2026-08-09 19:39:13 -07:00
create.go Publish POST /v0/beads/issues: the single create, with the whole vocabulary (#5483) 2026-08-09 09:21:56 -07:00
create_test.go Publish POST /v0/beads/issues: the single create, with the whole vocabulary (#5483) 2026-08-09 09:21:56 -07:00
cursor.go feat(issueops): add the Reader role and wire both front doors through it 2026-07-31 18:37:25 +00:00
cycles.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
cycles_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
delete.go Publish the row-version guard on close, reopen and delete (#5506) 2026-08-09 17:02:53 -07:00
delete_test.go Publish the row-version guard on close, reopen and delete (#5506) 2026-08-09 17:02:53 -07:00
dependency_edit.go feat(httpapi): publish addDependencies on the v0 surface 2026-08-08 00:19:48 +00:00
dependency_edit_test.go feat(httpapi): publish addDependencies on the v0 surface 2026-08-08 00:19:48 +00:00
doc.go docs(httpapi): stop the orientation prose enumerating a surface it no longer has 2026-08-08 01:34:33 +00:00
edge_counts_test.go Publish GET /v0/beads/dependencies:count, the wire half of issueops.GraphCounter (#5536) 2026-08-10 02:06:57 -07:00
edges.go Publish GET /v0/beads/dependencies:count, the wire half of issueops.GraphCounter (#5536) 2026-08-10 02:06:57 -07:00
edges_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
events.go feat(httpapi): stream the events journal over SSE (bd-opisf) 2026-08-09 07:55:23 +00:00
events_test.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
events_watch.go feat(httpapi): stream the events journal over SSE (bd-opisf) 2026-08-09 07:55:23 +00:00
events_watch_test.go feat(httpapi): stream the events journal over SSE (bd-opisf) 2026-08-09 07:55:23 +00:00
get_issue_test.go Publish revision on the detail read: the token a guarded write is composed from (#5535) 2026-08-10 00:27:49 -07:00
handlers.go refactor(context): one snapshot-to-fields projection for both context surfaces 2026-07-31 22:35:09 +00:00
memories.go Put the memory plane behind memoryops, conformance-tested at three backends (#5387) 2026-08-07 03:57:04 -07:00
memories_test.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
metadata_cas.go Add issueops.MetadataCAS: compare-and-set over one metadata key (#5473) 2026-08-09 04:15:34 -07:00
metadata_cas_test.go Add issueops.MetadataCAS: compare-and-set over one metadata key (#5473) 2026-08-09 04:15:34 -07:00
pinning.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
problem.go Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540) 2026-08-10 05:23:30 -07:00
problem_test.go feat(httpapi): OpenAPI v0 spec, types-only codegen, and the drift gates (bd-ilb) 2026-07-31 08:37:34 +00:00
project_stamp_test.go feat(httpapi): per-request project-id enforcement (Bd-Project-Id header) 2026-08-10 01:26:42 -07:00
query.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
reads.go Publish GET /v0/beads/issues:count, with the role's whole filter surface (#5508) 2026-08-09 19:39:13 -07:00
reads_test.go feat(serve): optional bearer auth and a Host allowlist for bd serve (#5516) 2026-08-09 18:05:56 -07:00
ready_count_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
related.go Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540) 2026-08-10 05:23:30 -07:00
related_test.go Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540) 2026-08-10 05:23:30 -07:00
release.go Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -07:00
release_test.go Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -07:00
reopen.go Publish the row-version guard on close, reopen and delete (#5506) 2026-08-09 17:02:53 -07:00
reopen_test.go Publish the row-version guard on close, reopen and delete (#5506) 2026-08-09 17:02:53 -07:00
roles.go Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540) 2026-08-10 05:23:30 -07:00
roles_test.go Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540) 2026-08-10 05:23:30 -07:00
routes.go Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540) 2026-08-10 05:23:30 -07:00
server.go Publish GET /v0/beads/issues/{id}/related, the wire half of issueops.Relations (ga-81p36) (#5540) 2026-08-10 05:23:30 -07:00
server_test.go feat(httpapi): per-request project-id enforcement (Bd-Project-Id header) 2026-08-10 01:26:42 -07:00
settings.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
spec_parity_test.go Publish GET /v0/beads/dependencies:count, the wire half of issueops.GraphCounter (#5536) 2026-08-10 02:06:57 -07:00
stats.go Merge branch 'facade/wave-3' into facade/wave-4 2026-08-06 21:39:05 +00:00
stats_test.go Merge branch 'facade/wave-3' into facade/wave-4 2026-08-06 21:39:05 +00:00
sweep.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
sweep_test.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
timed_provider_binding_test.go feat(httpapi): publish removeDependency on the v0 surface 2026-08-08 00:19:48 +00:00
tree.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
tree_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
update.go Publish the row-version guard on close, reopen and delete (#5506) 2026-08-09 17:02:53 -07:00
update_test.go claimNext + batchClose + incremental labels: the three role-backed ops with no wire (ga-g3gg8) (#5510) 2026-08-09 16:02:52 -07:00
wire_bijection_test.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00