beads/claim.go
Julian Knutsen d801ec43dc
feat(issueops): put every issue capability behind one library surface
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>
2026-08-04 12:27:56 -07:00

88 lines
4.1 KiB
Go

package beads
import (
"errors"
"strings"
"github.com/steveyegge/beads/internal/storage"
)
// ClaimConflict describes why a claim failed, recovered from the claim error.
//
// The engine's claim path embeds the conflicting state in the message: on
// ErrAlreadyClaimed the current assignee ("issue already claimed by
// <assignee>"), on ErrNotClaimable the current status ("issue not claimable:
// status <status>"). ClaimConflict carries whichever of those was recoverable;
// the other stays empty. This is a deliberately string-coupled shim.
//
// A CALLER ON THE LIBRARY CONTRACT DOES NOT NEED IT. The claim path now returns
// issueops.ClaimConflictError, which carries the assignee and status as typed
// fields read inside the attempt that lost, so errors.As recovers them without
// parsing anything. This shim stays for callers holding a claim error from
// somewhere else, and because it is public API.
type ClaimConflict struct {
// CurrentAssignee is the actor currently holding the issue. Set when the
// error wraps ErrAlreadyClaimed and the assignee was parseable.
CurrentAssignee string
// CurrentStatus is the issue's status that made it unclaimable. Set when
// the error wraps ErrNotClaimable and the status was parseable.
CurrentStatus string
}
// alreadyClaimedMarker and notClaimableMarker are derived at package-init time
// from the storage layer's sentinel + format fragment, NOT hardcoded literals,
// so the producer (issueops/claim.go) and this parser cannot drift: both spell
// the conflict message as "<sentinel><fragment><token>". A change to either the
// sentinel text or the fragment moves both ends in lockstep, and the producer-
// tied round-trip test (claim_roundtrip_test.go / the dolt suite) is the
// tripwire if the producer stops using the fragment at all.
var (
alreadyClaimedMarker = storage.ErrAlreadyClaimed.Error() + storage.ClaimedByFragment
notClaimableMarker = storage.ErrNotClaimable.Error() + storage.NotClaimableStatusFragment
)
// ParseClaimConflict inspects a claim error and, when it wraps ErrAlreadyClaimed
// or ErrNotClaimable, returns the recovered conflict detail and true. For any
// other error (including nil) it returns the zero ClaimConflict and false.
//
// Parsing keys on the message fragment the engine appends after the sentinel,
// located with LastIndex so that outer "context: %w" wrapping (which prepends)
// does not defeat it. Fields are best-effort: an Is-match with an unparseable
// message still returns true with the corresponding field empty.
func ParseClaimConflict(err error) (ClaimConflict, bool) {
switch {
case errors.Is(err, ErrAlreadyClaimed):
return ClaimConflict{CurrentAssignee: tailAfter(err.Error(), alreadyClaimedMarker)}, true
case errors.Is(err, ErrNotClaimable):
return ClaimConflict{CurrentStatus: tailAfter(err.Error(), notClaimableMarker)}, true
default:
return ClaimConflict{}, false
}
}
// tailAfter returns the bounded token following the last occurrence of marker in
// s, or "" when marker is absent or the token cannot be recovered unambiguously.
//
// The recovered token (assignee/status) is a single whitespace-free run by the
// producer's construction: the fragment is the last thing before the bare token,
// and claim-error wraps PREPEND context ("caller ctx: %w"), never append it, so
// in the well-formed case the tail is exactly the token. If the tail carries
// trailing content — whitespace, an appended "(...)" wrap, or a further embedded
// marker (all of which contain a space or a paren) — we cannot separate the
// token from the wrap, so we return "". A recovered-empty field is the
// documented best-effort failure mode (ParseClaimConflict still reports ok=true
// on the errors.Is match); a status never contains whitespace and an assignee is
// an actor id that by convention does not either, so a clean conflict is
// unaffected. This bound also stops a plain appended suffix — which the old
// "contains another full marker" guard missed — from leaking a garbage token.
func tailAfter(s, marker string) string {
i := strings.LastIndex(s, marker)
if i < 0 {
return ""
}
tail := s[i+len(marker):]
if strings.ContainsAny(tail, " \t\r\n(") {
return ""
}
return tail
}