beads/internal/httpapi
Julian Knutsen 294af94be2
Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507)
* Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv)

The claim has had a wire since v0 and its inverse has had none. `bd unclaim`
is a subprocess for every client of this surface, and a release-if-current has
no route at all — so the one verb that frees stranded work is the one verb an
automation client cannot reach.

`releaseIssue` publishes issueops.Releaser whole: `actor`, the
`expected_assignee` compare-and-set, and `force`. The response carries the
issue, `changed`, and `revision` — the last for `updateIssue`'s reason, and
one of its own: a release REMINTS the row's token by design, so a caller that
guarded its next write on a version read before the release would miss, and
this member is the only place the new one exists.

THE REFUSAL CODES ARE THREE, AND ONLY ONE IS NEW.

`already_claimed` is the ownership fence — an unforced, unguarded release by
an actor that is not the holder. That is `updateIssue`'s assignee-fence
situation exactly, down to having two bypasses, so it takes that operation's
code rather than a fourth spelling of "a live foreign owner refused your
write". Like there, no `assignee` member: the fence refuses without naming the
holder, so absence means re-read the row.

`precondition_failed` is the guard, inherited from the same operation and
carrying the same members for the same reason — `expected_assignee` is the
REQUEST's value, and there is no `actual_assignee` beside it, because the
refusal rolled its transaction back and ErrAssigneeMismatch is a bare sentinel
that formats the holder it saw into prose. There is no ClaimConflictError
equivalent to read, and this surface does not scrape its own messages.

`not_releasable` is minted, covering ErrNotReleasable and ErrNotClaimed.
`not_claimable` is the nearest existing code and covers a superset of the same
statuses today, but the coincidence is not a contract — the release transition
is pinned to {open, in_progress} by releasableStatus and the claim's
eligibility is a separate predicate — and for the unheld half the reuse would
be an outright lie: an open, unassigned row is the most claimable row a
workspace has. The two conditions share ONE code with no discriminating
member, which is the narrow choice rather than the convenient one: neither
sentinel carries a typed observation, and splitting later is an ADDITION the
document already tells clients to tolerate, while merging two published codes
is the removal that breaks the wire.

IT IS NOT IDEMPOTENT, and the wire says so rather than inventing an answer the
role refused to give. An unheld row is 409, never a 200 carrying
`changed: false` — that value is one no role produces (ReleaseResult.Changed
is true on every non-error answer), and it would report one answer for "I
released this twice", "a reaper beat me to it" and "nothing ever claimed it",
because the post-state is anonymous and nothing is left on the row to tell
them apart. A client for which "already released" is the ordinary path maps
the code to success in one line it writes knowingly.

`expected_assignee` disagrees with `updateIssue`'s same-named member in
exactly one place, and the schema says so: the empty string is a 400 here
rather than a guard meaning "expected unassigned". It also documents what the
comparison ACTUALLY does — separator-insensitive over runs of `.`/`_`/`-`,
per actorMatches, and nothing else forgiven — rather than repeating the role
doc's "byte for byte", which the implementation stopped being at ga-5ksp5.

failRelease matches all four sentinels TYPED and BEFORE its ErrValidation and
ErrNotFound arms. None of them is wrapped in ErrValidation on any leg, so
below a generic arm every one would have been a 500 on every leg.

The real-Dolt leg asserts the property a fake cannot: after every refusal it
reads the row back through the CLI, so "nothing was written" — and above all
the CLAIM SURVIVING a wrong-holder refusal — is a fact about the stored row.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

* Fix the release document's three review findings (ga-lzcuv)

The mint stands; what the review caught is that the document was written as
though `not_releasable` meant one thing, and it means two.

THE SAFETY ONE. "A caller for which 'already released' is the ordinary path
treats that code as success" was true of the sentinel it was written against
and is FALSE of the code it shipped as. `not_releasable` also covers the
status refusal, and a row parked in a status this workspace configured is
refused WHILE STILL ASSIGNED — so a reaper following that sentence books a
claim as dropped while it stands, held by an agent that is already gone, with
nothing left to free it. That is the stranding this operation resolves ids
across both planes to prevent, reintroduced through the refusal vocabulary
instead of through the id.

It now says the opposite, in the operation description and again on the 409:
on `not_releasable`, READ THE ROW. The row carries the one fact that separates
the two — an assignee, or none. One extra request on an uncommon path is the
honest price of one code rather than two, and the handler's `detail` says so
too, since that is the string an operator actually reads.

THE ACCURACY ONE. CodeNotReleasable claimed "neither refusal is typed", which
is wrong and misleads the person who eventually splits it: ErrNotClaimed and
ErrNotReleasable are two distinct typed sentinels and failRelease holds both
in one case arm, so a split is a mapping change in that arm — no archaeology
and no prose-scraping. What is genuinely unavailable typed is the OBSERVATION
each refusal made, the status seen and the emptiness of the assignee, which is
why the code carries no extension member. That is a narrower claim than the
one the comment made, and it is the true one. The merge is recorded as what it
is: a deliberate start-narrow choice, kept because adding a code later is the
reversible direction.

THE WIDENING. The 200 now states it: the transition is defined over `open` AND
`in_progress`, so a row already open that STILL HOLDS AN ASSIGNEE is released
here — the state a partial write or an out-of-band status edit leaves behind,
and one a release-if-current guarding on `in_progress` did nothing for and
reported no error about. A client porting such a guard has to know that before
it ports one.

Beside it, the code-to-outcome mapping a release-if-current client wants, so
that mapping is written against a documented fact: `not_releasable`,
`precondition_failed`, `already_claimed` and `404` all mean "no release
happened, and that is not an error" — `(false, nil)` to a client spelling it
as a pair. With the reading that pair does NOT license, stated beside it,
because it is the same reading the safety finding is about: it means no
release happened, never that the claim is gone.

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 14:41:28 -07:00
..
apigen Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -07:00
spec Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -07:00
batch_apply.go Add issueops.BatchApplier: one plan, one transaction (#5480) 2026-08-09 06:59:34 -07:00
batch_apply_test.go Add issueops.BatchApplier: one plan, one transaction (#5480) 2026-08-09 06:59:34 -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 POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -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 feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00:00
close_test.go feat(httpapi): serve updateIssue over v0 2026-08-07 22:25:47 +00: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
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 Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00:00
delete_test.go feat(httpapi): serve closeIssue over v0 2026-08-07 22:25:38 +00: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
edges.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00: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 test(httpapi): assert what the getIssue include legs actually carry 2026-08-08 01:29:45 +00: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 POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -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
query.go feat(httpapi): publish the events journal on the v0 surface (bd-opisf) 2026-08-09 06:01:23 +00:00
reads.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
reads_test.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
ready_count_test.go Trim this series' comments toward the repo's own density 2026-08-06 08:06:59 +00: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 feat(httpapi): serve reopenIssue over v0 2026-08-07 22:25:42 +00:00
reopen_test.go feat(httpapi): serve reopenIssue over v0 2026-08-07 22:25:42 +00:00
roles.go Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -07:00
roles_test.go Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -07:00
routes.go Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -07:00
server.go Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -07:00
server_test.go Publish POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -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 POST /v0/beads/issues/{id}:release: give a claim back (ga-lzcuv) (#5507) 2026-08-09 14:41:28 -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 updateIssue's guarded members: status, assignee, parent_id, metadata (#5484) 2026-08-09 10:24:36 -07:00
update_test.go Publish updateIssue's guarded members: status, assignee, parent_id, metadata (#5484) 2026-08-09 10:24:36 -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