doc.go still opened with "the three reads ... and the one write, POST
/v0/beads/issues/{id}:claim" and stated that "the claim OPERATION is the
only mutation this surface has". bd-serve-v0.md still opened its surface
section with "Six operations" over a six-row table, sized the server
under "Claim throughput — the claim is the only mutation in v0", and
scoped the no-hooks and no-auto-commit contracts to the claim alone. The
route table serves twenty-seven operations, eleven of them writes. Both
pages name themselves sources of truth, and bd-serve-v0.md's own header
rule says nothing in it may contradict the spec, doc.go or the reader
role — so this was the rule violating itself.
The counts are not corrected, they are removed. routes.go is the router,
TestSpecRouteParity welds it to the spec by exact set equality in both
directions, and capabilities is derived from the same table: a fourth
copy of the list, spelled in prose, can only ever go stale — as this one
did, silently, across five merged PRs. Both pages now describe the
MECHANISM and point at it. What replaces the table in bd-serve-v0.md is
the surface's shape, which is what a design page is for and which does
not change when an operation is added: what answers from the process,
how reads reach roles, the two spellings a write comes in, and the
posture every write shares.
Statements that were true only of the claim are widened where the code
widened them (the JSON content type is enforced for every body-carrying
operation; hooks fire for no write; the idempotent-write commit skip is
the re-claim, the re-close and the reopen) and narrowed where they were
overstated (the reader property covers three named reads, not "all"
reads — the count, the query, stats, config, memories and the dependency
reads are on sibling roles). The design page's error table gains the
three codes the wave added, with the extension members each carries and
the absence that distinguishes the two dependency_cycle refusals.
Also sweeps the seven stale "one write on this surface" comments in
claim.go, claim_test.go, roles_test.go and update_test.go, and reads.go's
"the three read operations" header over a file that now holds five.
No wire change, no behavior change.
Co-Authored-By: Claude Fable 5 <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>
The closing claim was "every read this surface answers goes through the
role and cannot do otherwise". Two things wrong with it. /healthz and
GET /v0/beads/context are reads this surface answers and go through no
role - they answer from the process and its startup snapshot - so the
sentence is false as written even though the taxonomy that fixes it is
four paragraphs up. And "cannot do otherwise" is stronger than the
mechanism: the rules forbid NAMING types.IssueFilter and types.WorkFilter,
not holding a value of one, so what they establish is that no filter is
WRITTEN there.
internal/httpapi/doc.go and issueops/reader.go now carry the same
paragraph, which says what is shared, what is enforced and by which rule,
and what is not - including the parts a reader would otherwise have to
discover: the naming-versus-holding limit, the test exemption, the two
non-issue operations, `bd ready`'s direct epilogue, `bd list`'s
hierarchical tree, and that no check on this repository is
GitHub-required. Each sentence is one a reviewer can check against the
config or the code in front of them.
The bullet above it in reader.go stops restating the rules and points at
the paragraph instead, and "reaching past the role is a lint failure"
becomes "writing a filter there is a lint failure", which is what
forbidigo and depguard actually do.
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>
The depguard rule this branch already carries enforces a NARROWER claim than the
epic states. httpapi-transport-boundary denies a handler IMPORTING
internal/workapi, so the builders are not callable here. It does not deny a
handler NAMING types.IssueFilter, and internal/types is reachable from
internal/httpapi on purpose — reads.go uses CheckFieldLen and IssueWithCounts.
That gap is the whole failure. The hosted viewer did not misuse a builder; it
passed a bare `IssueFilter{}` and leaked gates, wisps, templates and closed beads
that `bd list` hides. Under the old rule that file would have linted clean.
forbidigo with analyze-types denies types.IssueFilter and types.WorkFilter by the
type a selector RESOLVES to, not by the text of the selector, so an aliased
import is caught and an unrelated package named `types` is not. `pkg:` pins the
import path; a deliberately wrong pkg makes the rule stop firing, which is how it
was checked that the field is load-bearing rather than decorative. It also
catches `var f types.WorkFilter` with no composite literal at all, which a grep
for `types\.IssueFilter{` would miss and which is the same bypass.
Scoped to internal/httpapi by a path-except exclusion, because the auditor's
suggested "outside internal/workapi and its tests" is not a claim this repository
could make: there are ~750 filter literals in storage, conformance, and the
`bd ready`/`bd list` front doors that consume the filter for --claim, --watch and
the --parent tree. The scoped claim is the one the epic actually makes.
SEEN TO FAIL, on the golangci-lint version CI installs (v2.10.1 built against
this module's Go, since the v2.10.1 the local hook uses refuses the 1.26.5
target — bd-0cc). A `leak := types.IssueFilter{}` planted in handleListIssues
compiles and passes go vet:
$ golangci-lint run --config=.golangci.yml --build-tags=gms_pure_go ./...
internal/httpapi/reads.go:168:10: use of `types.IssueFilter` forbidden because
"internal/httpapi is transport only: it never builds a filter. ..." (forbidigo)
leak := types.IssueFilter{}
exit 1
REBASE PRESERVATION, STATED PRECISELY, because the rebase report overstated it.
`git diff bd-serve-reader-role HEAD -- cmd/bd/ internal/httpapi/ internal/workapi/
internal/storage/uow/` does NOT return empty and cannot: bd-serve-v0 carries
merged work bd-serve-reader-role does not, so that command reports 27 files and
~1800 changed lines that have nothing to do with the Reader role. What is true is
that the SLICE replays byte-identically. Diff the slice patch on each side —
from each branch's `merge(bd-emv)` commit to its reader-role tip — and the two
patches differ by 34 lines, all three of them accounted for:
1. cmd/bd/serve.go, v0 only: drops the 501 readiness caveat, which was true on
the reader-role branch's base and false once the role landed.
2. cmd/bd/serve_claim_proxied_integration_test.go, v0 only:
startServe(t, bd, p) -> startServe(t, bd, p.dir, bdProxiedEnv(p.dir)),
because bd-emv changed that signature on v0.
3. internal/storage/storage.go: the SAME 11 added lines at a one-line-earlier
hunk offset (@@ -90 vs @@ -89) and the correspondingly different blob
hashes. Zero content difference — the added and removed lines compare equal.
(1) and (2) are the two rebase-repair commits already on this branch. There is no
third difference.
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.
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.
POST /v0/beads/issues/{id}:claim is the one write in v0, and it replaces the
transitional 501 stub. The handler runs domain IssueUseCase.ClaimIssue inside a
caller-owned uow.RunTxResult — the single retry/commit implementation, which the
proxied CLI writes already use — and commits "bd serve: claim <id> by <actor>",
one storage commit per successful claim. A re-claim by the current holder
changes nothing, so it answers 200 with already_claimed and no commit at all: a
polling client cannot fill the history with empty ones.
The 409s are typed. `assignee` and `issue_status` come from a read inside the
claim's own transaction, never from parsing "already assigned to" or "claimed
by" out of a sentinel's message — which is what lets a client delete its
substring error classification. When that read fails the refusal still stands as
a 409; degrading it to a 500 would trade a precise answer for an unactionable
one.
Actor validation happens at the wire edge, before the CAS: trim, then refuse
empty, over 256 bytes, past the assignee column's 255 characters, or bearing a
control character. The domain layer rejects only actor == "", so a
whitespace-only or megabyte actor would otherwise reach the assignee column AND
the storage commit message, where an unvalidated newline forges audit-trail
lines. The body is refused the same way, with the offending member named:
application/json only (a JSON content type is not CORS-"simple", so a
cross-origin claim always meets a preflight this server never approves), one
known member, one JSON object, one megabyte.
The route pattern is a whole-segment wildcard, so every POST under
/v0/beads/issues/ reaches this handler. A segment that does not end in ":claim"
now gets the catch-all's 404 rather than being read as an id — the obligation
the skeleton recorded on that row, and the reason POST on the GET-only detail
path is not a claim of the issue it names.
uow.RunTxResult's per-attempt close switches to the detached-context pattern.
Close sends ROLLBACK and the transaction layer poisons the pinned connection
when that send fails, so closing with an already-canceled context burned one
session per client disconnect. Fixed in the one implementation, so the proxied
CLI writes inherit it.
Hooks do not fire and the per-command auto-commit globals are never touched,
seam-consistent with every proxied write today. The actor is caller-asserted
provenance for the audit trail, not authenticated identity: the CAS is a
correctness fence against concurrent claims, not an authorization boundary, and
the loopback-only bind is what bounds the blast radius. Both are stated in the
handler, because adoption depends on knowing them.
The claim row leaves the 501 exemption list; the three read stubs keep theirs,
and the list still fails the test the moment it outlives the last stub.
Verified against real Dolt: 12 concurrent claimants produce exactly one 200 and
11 typed 409s all naming the winner the database agrees on, dolt_log carries one
entry per successful claim and none for the idempotent re-claim, and
ClaimResponse.issue compares equal field-for-field to `bd update --claim
--json`[0] under an EMPTY allowlist.
Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of CI Bot
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The wildcard-bind rule is the one place this deviates from the design's
letter, which enumerated "the configured bind address" without saying what a
wildcard means. A decision that survives only in a code comment is one the
next reader re-litigates, so it is stated where the package is introduced.
The first slice that runs a server. Proxied-server workspaces go live; the
read and claim operations are registered as transitional 501 stubs so route
and spec parity can be proved all at once instead of growing a hole per slice.
`bd serve --addr 127.0.0.1:0 [--allow-non-loopback]`, and no other flags in
v0. The bound address is stdout's first line, because under the ephemeral
default it is the only way to find the port. Shutdown rides the signal context
the root command already installs. No lock file, pid file or discovery file:
serve is operator-invoked and the TCP bind IS the mutual exclusion — dbproxy
needs that machinery only because clients race to auto-spawn it.
The mode gate says two different things, deliberately. Embedded is a PERMANENT
typed storage.ErrUnsupported: there is no unit-of-work provider for that
backend. Dolt server mode is STAGED — the provider construction exists and is
tested, it just is not wired in yet — so the text names what works today and
says this does not, rather than reading as an architectural limit that would
send an operator off to change their topology for nothing.
One unit of work per request, closed through a DETACHED context. The
transaction layer poisons the pinned connection when a ROLLBACK send fails
(doltserver_tx.go), so closing with the request's own canceled context would
burn a session on every client disconnect.
Front-tier hardening lands here, not later, because without it a hung Dolt
becomes a silently growing black hole: slots fill with immortal queries,
/healthz stays green because it never touches the database, and recovery
produces a thundering herd. So: a Host-header allowlist (DNS-rebinding defense
for an unauthenticated, browser-reachable loopback service), a
netutil.LimitListener connection cap (Go spawns a goroutine per connection, so
the database semaphore alone does not bound what is accepted), a database
semaphore with a BOUNDED 10s wait mapping to the already-documented 503 busy,
a 60s per-request deadline, and explicit pool limits on the provider's *sql.DB
via a new uow.PoolTuner knob — openDB set none, and database/sql's default is
unlimited.
/v0/beads/context serializes an explicit ten-field allowlist and nothing else.
SyncRemote is hard-excluded in this and every future version: it is populated
unconditionally from config sync.remote, and remote URLs routinely embed
credentials. The database bind endpoint and the remaining absolute host paths
are excluded too. `capabilities` is derived from IMPLEMENTED handlers only, so
a release cut between this slice and the endpoint slices advertises only what
actually works.
The observability floor is an acceptance criterion, not a convention: one
structured stderr line per request (method, path, status, problem code,
duration, semaphore wait, unit-of-work acquire), startup and shutdown lines, a
semaphore-saturation event, and a request_id on every problem response. That
last one required documenting request_id on the spec's Problem schema — the
only spec edit here, additive, with types regenerated.
Decisions implemented as given: hooks do not fire (a user-controlled
subprocess per mutation is an unbounded latency multiplier and an orphaned
child at shutdown); the per-command auto-commit globals are never touched
(nothing to exclude — proxied PersistentPostRunE only closes the provider);
and actor on an HTTP request stays caller-asserted provenance, which the
context and capabilities wording does not contradict.
Tests: TestSpecRouteParity asserts set equality between the route table and
the document's paths, and builds the real mux so a pattern ServeMux would
refuse fails here rather than on the first request.
TestSpecStatusCodesMatchHandlerTable carries a commented, enumerated 501
exemption that is self-deleting — it fails if the route table and the list
disagree, and fails again if the list outlives the last stub. The context
allowlist is enforced from the handler out, over a body built from a snapshot
with every field populated and a credential-bearing sync remote.
TestWithUOWClosesWithADetachedContext records the close context's state AT
close time, which is the only moment it says anything.
Verified: build, vet and golangci-lint clean (the two gosec findings in
cmd/bd/main.go pre-date this change); internal/httpapi green under -race;
protocol corpus byte-identical with BEADS_PROTOCOL_REQUIRE_DOLT=1; and a real
server started against a proxied workspace, answered both endpoints, refused
a foreign Host, an unknown query key and a second bind, and drained to exit 0
on SIGTERM.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Lands the bd serve wire contract and the machinery that keeps it honest. No
runtime behavior: nothing routes, nothing serves, and no CLI surface changes.
internal/httpapi/spec/openapi.v0.yaml is hand-written and is the source of
truth; internal/httpapi/apigen is generated from it with oapi-codegen
types-only (no server stubs, no router), via a go.mod tool directive so
contributors need no extra install.
The decisions this slice fixes, because they are one-way doors:
- No second wire struct. Issue, IssueWithCounts, IssueDetails and
IssueWithDependencyMetadata are pinned to the canonical Go types with
x-go-type, so the generator emits type aliases and the CLI's --json, the
JSONL interchange and the HTTP bodies all marshal one struct. A hand-written
Go-to-Go mapping layer would recreate the drift disease this epic exists to
cure. Guarded by a two-way JSON-tag bijection test, not a round-trip fixture:
a new omitempty field absent from a fixture round-trips cleanly in both
directions and proves nothing.
- limit=0 means unlimited, matching the CLI exactly, with defaults 50 (list)
and 100 (ready) documented as the shared constants. The only exception --
refusal under --allow-non-loopback -- is in the limit description.
- ready returns IssueWithCounts, not bare Issue.
- Unknown query parameters are rejected with 400 invalid_argument naming the
parameter in a machine-readable extension member: with types-only codegen the
decoders are hand-written, and Go's silent-ignore default would WIDEN a
filtered result set under version skew.
- /v0/beads/issues forces (created_at DESC, id ASC) on every request, and the
spec documents the deliberate divergence from bd list's priority ordering.
- One RFC 9457 problem+json envelope everywhere, with a frozen code vocabulary
mapped from the sentinels via errors.Is. 5xx bodies carry a static per-code
detail; the real error goes only to the log, because driver and dial errors
routinely embed the DSN.
- Only the status codes the six operations need are documented. Every
documented status+code pair is permanent wire surface.
Two traps found while building this, both now guarded:
- oapi-codegen v2.6.0 silently drops x-go-type from a component that also
carries allOf. An allOf-composed IssueWithCounts generated
"type IssueWithCounts = types.Issue" -- the ready endpoint would have shipped
with the count fields gone. The pinned schemas therefore repeat their
property lists, and internal/httpapi/pinning.go turns a regression into a
build failure.
- context.DeadlineExceeded satisfies net.Error, so a tripped request deadline
would have mapped to 503 db_unavailable instead of a generic 500.
make api-check is the three-part gate (regenerate, diff-or-fail, spec tests)
and runs from scripts/ci/pr-policy.sh, i.e. in a required PR job -- the Main
workflow is perpetually concurrency-cancelled, so a gate living only there
would be unenforced.
The go.mod diff is the tool directive and its closure. The protocol corpus is
untouched.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>