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>
99 lines
4.9 KiB
Go
99 lines
4.9 KiB
Go
package issueops
|
|
|
|
import (
|
|
"context"
|
|
|
|
"github.com/steveyegge/beads/internal/types"
|
|
)
|
|
|
|
// RelatedIssue is one issue on the far end of an edge, carrying the edge's
|
|
// type alongside the issue's own fields.
|
|
//
|
|
// It is an ISSUE and can be nothing else, which settles what an edge whose
|
|
// target is neither issue nor wisp answers with. A dependency target may be an
|
|
// "external:" reference or an issue belonging to ANOTHER repository — see
|
|
// DependencyEditor, which accepts both — and this database holds no row for
|
|
// either. Such an edge has no far end to describe here, so it is not a neighbor:
|
|
// Related leaves it out, with no placeholder row and no error.
|
|
//
|
|
// The consequence is worth stating because it is not visible in the answer: the
|
|
// length of a result is the anchor's neighbor count and NOT its edge count, and
|
|
// the two differ by however many of its edges point outside this database. A
|
|
// caller that needs the edges themselves needs a role that answers with edges.
|
|
type RelatedIssue = types.IssueWithDependencyMetadata
|
|
|
|
// RelationDirection selects which way the anchor's edges are walked.
|
|
//
|
|
// Its ZERO VALUE is invalid, and that is the point. A silent default direction
|
|
// is how a caller asks for "what blocks this" and is handed "what this blocks"
|
|
// — the exact inverse of the graph it wanted, with the same shape, the same
|
|
// field names and no error to notice.
|
|
type RelationDirection string
|
|
|
|
const (
|
|
// RelationOut walks OUTGOING edges: the issues the anchor depends on.
|
|
RelationOut RelationDirection = "out"
|
|
// RelationIn walks INCOMING edges: the issues that depend on the anchor.
|
|
RelationIn RelationDirection = "in"
|
|
)
|
|
|
|
// RelatedRequest describes one neighbor query.
|
|
type RelatedRequest struct {
|
|
// ID is the anchor's exact canonical id, and EXACT is a promise the role
|
|
// keeps rather than an obligation it puts on the caller: a spelling that is
|
|
// not the stored one resolves to nothing. A case variant, an id carrying
|
|
// surrounding whitespace, a prefix of a real id and a real id with a suffix
|
|
// are all misses, for the same reason GetRequest.ID has no fuzzy resolution
|
|
// — an affordance that can answer ABOUT A DIFFERENT ISSUE than the caller
|
|
// named has no place on a contract an unattended client calls.
|
|
//
|
|
// Both planes are searched, and a miss on both is ErrNotFound rather than an
|
|
// empty answer: "this issue has no dependencies" and "there is no such
|
|
// issue" are different facts, and a caller that cannot tell them apart
|
|
// reports a typo as a clean graph.
|
|
ID string
|
|
// Direction is required. The zero value is ErrValidation; there is no
|
|
// implicit "both", and no direction is the default.
|
|
Direction RelationDirection
|
|
// Types restricts the answer to these edge types. Empty means every type.
|
|
//
|
|
// An entry is checked for being a value at all — non-empty, within the
|
|
// column's length — and NEVER for membership of a known-types list: the
|
|
// vocabulary is OPEN (see the Dep* constants), so a workspace's own type
|
|
// has to be able to filter. An unusable entry is ErrValidation rather than
|
|
// a filter that quietly matches nothing.
|
|
Types []DependencyType
|
|
}
|
|
|
|
// Relations describes reading an issue's neighbors: the read side of `bd dep
|
|
// list`, and — like Reader — 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 its own role rather than a fourth Reader method because it answers a
|
|
// question about EDGES. Reader's three methods all answer with pages of
|
|
// issues, selected by the issues' own fields; this one is anchored on a
|
|
// specific issue and its answer is shaped by the edges reaching it, which is
|
|
// why its result carries the edge type and its request carries a direction.
|
|
//
|
|
// The dependency TREE is deliberately not here. A recursive walk has a depth,
|
|
// a cycle policy and a node shape of its own, and it answers with a forest
|
|
// rather than a list — a different question, so a different role when
|
|
// something needs it.
|
|
//
|
|
// Implementations never mutate caller-owned request values, snapshot the
|
|
// request at method entry, and apply validation and normalization only to
|
|
// attempt-local clones. RelatedRequest travels by value, so Types is the one
|
|
// member a body could write through to the caller at all: reading it into a
|
|
// set is fine, sorting or de-duplicating it in place is not.
|
|
type Relations interface {
|
|
// Related returns the anchor's neighbors in the requested direction.
|
|
//
|
|
// THE ORDER IS PINNED: ascending by the neighbor's id, with the edge type
|
|
// breaking a tie. It is pinned rather than left to the query because the
|
|
// rows come from two dependency tables read in sequence, so the natural
|
|
// order is an artifact of which plane a neighbor happens to live on —
|
|
// stable enough to look deliberate and not stable enough to rely on.
|
|
//
|
|
// The result is never nil for a successful call.
|
|
Related(ctx context.Context, req RelatedRequest) ([]*RelatedIssue, error)
|
|
}
|