beads/issueops/releaser.go
Jim Wordelman f6a191fd64
fix: canonicalActor collapses the --/__ axes correctly; claim-verify uses ActorMatches (be-p7dzx, bundled be-vc51) (#5856)
* test(feat): red — canonicalActor collapses the --/__ axes: misses gascity slash identities and widens ActorMatches (bundled with be-vc51 authorize/verify split) (refs be-fh0g)

* feat: green — canonicalActor collapses the --/__ axes: misses gascity slash identities and widens ActorMatches (bundled with be-vc51 authorize/verify split) (refs be-fh0g)

* docs(identity): correct the five contract surfaces that still document the pre---- collapse rule

canonicalActor stopped collapsing an exact "--" run when it started decoding
that run to "/", but five places still tell a reader the old rule: a run of
".", "_" or "-" matches any other such run. That is now false for "--", and
two of the five are public contract surfaces rather than internal comments --
the OpenAPI description a client reads, and the conformance text a backend
implementor is expected to satisfy.

Corrected in place, all saying the same thing: an exact "--" run decodes to
"/" because that is gascity's session-name encoding of a rig-qualified
agent's slash, so "a--b" matches "a/b" and no longer matches "a__b" or "a-b";
longer and mixed runs, "__" included, still collapse.

  issueops/releaser.go                      ExpectedAssignee's contract
  issueops/issueops.go                      the update-side cross-reference
  internal/httpapi/spec/openapi.v0.yaml     wire contract (source of truth)
  internal/httpapi/apigen/types.gen.go      regenerated via make api-gen
  backend/conformance/releaser_contract.go  cross-backend contract text

The conformance limb is annotated rather than re-pinned: the respelling it
exercises is "-" -> "_", which this change does not affect, so it stays green
either way -- which is exactly why CI could not catch the stale text. Adding a
"--" limb there would pin new cross-backend behavior and is a wider change
than correcting a contract description.

This is the keep-in-sync obligation identity.go records under ga-5ksp5,
applied to the documentation half.

* docs(changelog): record the --/__ equivalence-class change under [Unreleased]

The actor-matching change is user-visible and silent: it moves which stored
spellings compare equal for ExpectedAssignee on release and update, and for
claim/close/unclaim authorization. "gastown--mayor" starts matching
"gastown/mayor" and stops matching "gastown__mayor" and "gastown-mayor".

The entry says the widening is the intended fix -- "gastown--mayor" is the
agent "mayor" on rig "gastown" while "gastown__mayor" is the dotted alias
"gastown.mayor", and matching them was wrong -- and then states the part a
reader actually needs to act on: any stored "--" spelling that is NOT a
gascity slash encoding changes equivalence class with no error to notice.

---------

Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
2026-08-19 13:23:35 -07:00

267 lines
15 KiB
Go

package issueops
import (
"context"
"errors"
)
// ReleaseRequest describes one release of a claim — the inverse of
// ClaimRequest, and the shape behind `bd unclaim`.
//
// Implementations never mutate caller-owned request values: ExpectedAssignee is
// read, never written through.
type ReleaseRequest struct {
// Actor attributes the release on the row's event history. It is REQUIRED —
// an empty Actor is ErrValidation — because a release is the moment work
// stops being owned, and the one question asked of its history entry
// afterwards is who let it go.
//
// IT IS ALSO THE OWNERSHIP FENCE'S SUBJECT, on the unconditional path: a
// release with neither ExpectedAssignee nor Force succeeds only while Actor
// is the current holder. That is not authentication — Actor is
// caller-asserted provenance here as it is everywhere else in this package
// — it is the same anti-yank guard ClaimRequest gets from refusing a
// foreign holder, pointed the other way. "Is the current holder" is the
// same separator-insensitive comparison ExpectedAssignee documents below,
// not exact equality.
Actor string
// IssueID is the exact canonical id and must not be empty.
//
// IT RESOLVES ACROSS BOTH PLANES, unlike Claimer.Claim, which answers
// ErrNotFound for a wisp id. The asymmetry is deliberate and it is about
// which direction strands work: a wisp can hold a claim — the ephemeral
// plane has its own claim path — so a role that refused to release one
// would leave an ephemeral row owned by an agent that is gone, with no verb
// able to free it. Refusing to MINT a claim on that plane through this
// family strands nothing.
//
// There is no fuzzy or prefix resolution: that is a front-door convenience,
// for the reason GetRequest.ID gives.
IssueID string
// ExpectedAssignee is a compare-and-set precondition on the holder: the
// release proceeds only while the issue is still assigned to
// *ExpectedAssignee, and otherwise refuses with ErrAssigneeMismatch naming
// the actual holder, leaving the row untouched.
//
// A MATCH REPLACES THE OWNERSHIP FENCE, exactly as
// UpdateRequest.ExpectedAssignee replaces the anti-steal fence for a
// transfer: a caller that can name the current holder has demonstrated the
// view the fence exists to protect, so Actor need not be that holder. This
// is the shape a supervisor releasing a specific agent's abandoned claim
// wants, and it is safer than Force for the purpose because it cannot
// release a claim that has since moved.
//
// THE COMPARISON IS SEPARATOR-INSENSITIVE AND NOTHING ELSE. A run of ".",
// "_" or "-" matches any other such run, so "agent-a", "agent_a" and
// "agent.a" are one holder — that is deliberate, so a caller naming the
// holder under a different layer's spelling is a match rather than a
// mismatch (ga-5ksp5). THE ONE EXCEPTION IS AN EXACT "--" RUN: that is
// gascity's session-name encoding of a rig-qualified agent's "/", so it
// decodes to "/" rather than collapsing. "a--b" matches "a/b" and no
// longer matches "a__b" or "a-b" — "a--b" is the agent "b" on rig "a"
// while "a__b" is the dotted alias "a.b", so treating them as one holder
// was a widening, and removing it is the point of the exception
// (ga-2vy9p2). Longer or mixed runs, "__" included, still collapse.
// NOTHING ELSE IS FORGIVEN: the value is not trimmed
// and not case-folded, so " agent-a" and "Agent-a" are both refusals. The
// validation below trims only far enough to tell a blank expectation from a
// real one, and never writes the trimmed form back — the no-mutation
// promise above makes that permanent, so a caller that pads its expectation
// loses every time rather than intermittently. Compose it from a holder a
// read gave you.
//
// nil DISABLES THE CHECK and selects the unconditional path. It is a
// pointer so that "do not check" is distinct from a value — but unlike
// UpdateRequest.ExpectedAssignee, a non-nil pointer to "" is NOT a guard
// meaning "expected unassigned": it is ErrValidation. "Release a row nobody
// holds" describes no release at all, and the raw seam beneath this role
// refuses the empty expectation in as many words. A caller that wants to
// assert a row is unheld is asking a READER a question, not asking this
// role to do nothing.
//
// FORCE MUST BE FALSE WHEN IT IS NON-NIL — a request setting both is
// ErrValidation. The two are answers to the same question, and they
// disagree: this one says "only if X still holds it", Force says "whoever
// holds it". That is the same rule UpdateRequest states for
// ForceAssigneeTransfer beside its own ExpectedAssignee.
ExpectedAssignee *string
// Force bypasses the ownership fence, so an actor that is not the holder
// may release the claim. It is the escape hatch `bd unclaim --force` spells,
// for an abandoned claim whose holder crashed.
//
// IT BYPASSES THE FENCE AND NOTHING ELSE. It does not make an unheld row
// releasable (that is ErrNotClaimed with or without it), it does not make a
// closed one releasable (ErrNotReleasable), and it never bypasses a
// precondition — see ExpectedAssignee, which it may not accompany. Force
// answers "may I release someone else's claim"; every other refusal below
// answers "is there a claim here to release", which force has no opinion
// about.
Force bool
}
// ReleaseResult reports one release as a detached post-state snapshot.
//
// It is shaped after ClaimResult rather than after UpdateResult, and for the
// same reason: this family answers with the issue ROW, without labels,
// dependency records or comments.
type ReleaseResult struct {
// Issue is a detached post-release snapshot of the issue row and its
// labels, without dependency records or comments. It is read from the row
// INSIDE the releasing transaction, so it is what a subsequent read sees
// rather than a value composed from the request and the pre-state.
//
// THE LABELS ARE THE ONE PLACE THIS DIFFERS FROM ClaimResult.Issue, which
// is the bare row. That difference is not a preference: Claimer answers an
// already-published wire shape and cannot enrich its snapshot without
// changing what a shipped body returns, and this role has no published
// shape to preserve. The read the release needs anyway hydrates labels, so
// stripping them would be inventing a difference rather than keeping one.
//
// THE POST-RELEASE RowVersion RIDES ON Issue.RowVersion and is deliberately
// not copied onto a second result field. It is the token a caller feeds to
// a following ExpectedVersion, and two spellings of one token is how they
// come to disagree.
Issue *Issue
// Changed reports whether the release WROTE the row.
//
// IT IS TRUE ON EVERY ANSWER THIS ROLE RETURNS WITHOUT AN ERROR, because
// every shape that would not write is refused above it: an unheld row is
// ErrNotClaimed rather than an idempotent no-op.
//
// THE ASYMMETRY WITH ClaimResult.Changed IS NOT AN INCONSISTENCY, and the
// reason is a fact about the two POST-STATES rather than a preference.
// Claimer can afford an idempotent answer because the state a claim leaves
// behind IDENTIFIES THE CLAIMANT: a re-claim finds assignee == Actor and
// StatusInProgress, which is the claim's own signature surviving on the row,
// so the role can tell "you already did this" from "somebody else holds it"
// and reports Changed false for exactly the first. A release leaves an
// ANONYMOUS post-state — assignee cleared, status open, started_at gone —
// which is the same row no matter who emptied it, or whether it was ever
// full. An idempotent release would therefore answer Changed false
// identically for "I already released this", "a reaper beat me to it" and
// "nothing ever claimed it", with NOTHING LEFT ON THE ROW to tell them
// apart. Those three want different things from a caller, so the role
// refuses instead and lets the caller decide which of them it can live
// with — see Releaser.Release's non-idempotence paragraph.
//
// So the field is here because ClaimResult.Changed is, and a caller holding
// both roles should not have to read the pair two ways. Nothing returns it
// false today, and the conformance contract says so in its coverage
// paragraph rather than carrying a case that could not fail.
Changed bool
}
// ErrNotClaimed classifies the refusal of a release over a row that holds no
// claim: there is nothing to let go of.
//
// It lives beside the role rather than in errors.go because it is meaningless
// without ReleaseRequest to explain it, and errors.go is the file every
// parallel role slice touches. Its neighbor ErrNotOwner is in errors.go
// instead, because that one is the shared ownership vocabulary the claim family
// already speaks.
//
// IT IS A REFUSAL AND NOT A NO-OP, which is the raw seam's rule. A caller whose
// release found nothing to release did not do what it believed it was doing —
// most often because a reaper got there first — and the two facts are worth
// telling apart. Callers for which "already released" is the ordinary path
// errors.Is this and carry on; that is one line, and it is a line the caller
// writes knowingly rather than one the role writes on its behalf.
var ErrNotClaimed = errors.New("issue holds no claim")
// ErrNotReleasable classifies the refusal of a release over a row whose STATUS
// will not accept one: a closed issue, or an issue in any status other than the
// two the release transition is defined over.
//
// IT IS WIDER THAN "CLOSED", and that is worth knowing before it surprises
// someone. The release is an UPDATE pinned to status open or in_progress, so an
// issue parked in a workspace's own configured status — an active or wip status
// a `bd update` put it in — is refused here even though it plainly holds a
// claim. That is a limitation of the transition rather than a policy, and it is
// named rather than papered over: before this role, the same request failed
// with an untyped "no matching row" that no caller could classify and no
// message explained.
var ErrNotReleasable = errors.New("issue status does not accept a release")
// Releaser describes the release of a claim — the capability behind
// `bd unclaim` — and, like every other capability here, a role with its own
// accessor. A new capability gets a new role interface and its own accessor;
// never append a method here.
//
// IT IS A DIFFERENT QUESTION FROM ITS NEIGHBORS.
//
// - Claimer takes ownership. This gives it back, and the two are not one
// role with a flag: a caller entitled to release its own work is very
// often not entitled to take new work, and a surface carrying both hands
// it a capability it should not be able to reach. That is the same test
// Bootstrapper and InitVerifier were split by.
// - Lifecycle.Update can clear an assignee as one field among many, and
// that is exactly why this is separate. An update spells the release as a
// patch — assignee to empty, status to open, started_at to null — which
// puts the transition's definition in the CALLER, three fields at a time,
// and leaves the lease row behind. A release is one act with a known
// post-state, and the lease it drops is the part a patch cannot express at
// all.
// - Lifecycle.Close ends the work. This ends the OWNERSHIP and leaves the
// work open for the next taker, which is why its post-state is status open
// rather than anything in the done category.
//
// WHAT A RELEASE DOES TO THE ROW, stated once so no caller has to reconstruct
// it: assignee is cleared, status becomes the literal StatusOpen, started_at is
// cleared, the row's lease is deleted, and RowVersion is reminted so a
// concurrent reclaim or close on the same row conflicts rather than silently
// merging. An "unclaimed" event is recorded against Actor, and the row's
// version-control history sees the release as an update.
//
// WRITES, AND ITS HOOK IS on_update. internal/hooks publishes on_create,
// on_update and on_close; a release changes assignee and status, which is an
// update and is already how the journal classifies it. There is no on_unclaim
// to fire and inventing one is not this role's job.
//
// Deterministic request-validation failures match ErrValidation. Result values
// are unspecified when error is non-nil, and every refusal below leaves
// persistent state unchanged.
type Releaser interface {
// Release gives up the claim on one issue and reports the row it left
// behind.
//
// IT IS ONE TRANSACTION. The read that classifies the refusals, the release
// itself and the post-state snapshot all see one snapshot, so the Issue it
// answers with is the row the release produced rather than a row some other
// writer produced afterwards.
//
// THE ORDER THE REFUSALS HAPPEN IN IS PART OF THE ANSWER, because a request
// can fail several ways at once. Request validation runs before anything is
// read; then existence; then the row's STATUS, because a closed issue is
// not a claim question at all; then whether a claim exists; then the
// precondition or the fence, whichever the request selected.
//
// REFUSALS:
//
// - an empty Actor or IssueID, an ExpectedAssignee that is non-nil and
// blank, or Force beside a non-nil ExpectedAssignee: ErrValidation,
// before anything is read;
// - an id naming no row in either plane: ErrNotFound;
// - a closed issue, or one whose status is neither StatusOpen nor
// StatusInProgress: ErrNotReleasable;
// - a row that holds no claim, on the unconditional path with or without
// Force: ErrNotClaimed;
// - a non-nil ExpectedAssignee that does not match the current holder —
// INCLUDING a row that holds no claim, which is a mismatch rather than
// ErrNotClaimed, because the caller asked about a specific holder and
// the answer is that it is not the holder: ErrAssigneeMismatch;
// - an unforced, unconditional release by an actor that is not the
// holder: ErrNotOwner.
//
// A RELEASE IS NOT IDEMPOTENT, and the ErrNotClaimed entry above is where
// that shows. A caller that retries after a crash and cannot tell whether
// its first release landed matches that sentinel and treats it as success;
// the role will not make that decision on its behalf, because "somebody
// else released this" and "I released this twice" are the same answer from
// here and only the caller knows which one it can live with.
//
// Implementations own transaction retry: a release that loses a
// commit-time merge is retried, never surfaced. Other operational or
// commit-finalization errors can have an indeterminate durable outcome;
// callers must reread state before retrying.
Release(context.Context, ReleaseRequest) (ReleaseResult, error)
}