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>
183 lines
9.2 KiB
Go
183 lines
9.2 KiB
Go
package issueops
|
|
|
|
import (
|
|
"context"
|
|
|
|
"github.com/steveyegge/beads/internal/types"
|
|
)
|
|
|
|
// DependencyType names one kind of edge between two issues.
|
|
type DependencyType = types.DependencyType
|
|
|
|
// Dependency types in COMMON USE.
|
|
//
|
|
// This is an OPEN SET, and these constants are a documented sample of it — not
|
|
// a closed enum, not exhaustive, and not a whitelist. A workspace configures
|
|
// its own vocabulary, so nothing in this package validates a DependencyType
|
|
// against this list, and an implementation that refused a type absent from it
|
|
// would break every workspace that spelled one of its own. Adding a value here
|
|
// documents a value; it never authorizes one.
|
|
//
|
|
// They exist at all because internal/types is unimportable outside this
|
|
// module. Every request and result below CARRIES a DependencyType, so without
|
|
// these an external embedder can hold one but has no spell-checked way to name
|
|
// one — the same reason the error sentinels are re-exported in errors.go.
|
|
const (
|
|
DepBlocks = types.DepBlocks
|
|
DepParentChild = types.DepParentChild
|
|
DepRelated = types.DepRelated
|
|
DepDiscoveredFrom = types.DepDiscoveredFrom
|
|
DepRepliesTo = types.DepRepliesTo
|
|
DepWaitsFor = types.DepWaitsFor
|
|
)
|
|
|
|
// DependencyEdge is one directed edge: IssueID depends on DependsOnID, with
|
|
// the given Type. Both endpoints are exact canonical ids — there is no fuzzy,
|
|
// prefix or cross-repo resolution on this contract, for the reason
|
|
// GetRequest.ID gives.
|
|
type DependencyEdge struct {
|
|
IssueID string
|
|
DependsOnID string
|
|
// Type is required and must be a usable value. It is checked for being a
|
|
// value at all — non-empty, within the column's length — and NEVER for
|
|
// membership of the constants above, which name an open set.
|
|
Type DependencyType
|
|
}
|
|
|
|
// AddDependenciesRequest describes one set of edges asserted together.
|
|
//
|
|
// IT IS ALL-OR-NOTHING, and unlike the batch close that is not a policy choice
|
|
// but the shape of the question. A close acts on issues that are independent
|
|
// of one another, so skipping one and committing the rest loses nothing; edges
|
|
// asserted in one request describe a GRAPH, and half a graph is a graph nobody
|
|
// asked for — the cycle a caller was refused for is exactly the state a
|
|
// partial commit would leave behind.
|
|
type AddDependenciesRequest struct {
|
|
// Actor is the author of the edges and must not be empty. It is what the
|
|
// dependency_added entry each genuinely new edge records is attributed to,
|
|
// which is the only place a reader finds who wired an edge: the result
|
|
// does not carry it.
|
|
Actor string
|
|
// Edges are the edges to assert, in the caller's order. It must not be
|
|
// empty. Edges are applied parent-child first regardless of this order, so
|
|
// the complete planned hierarchy is visible before any blocking edge is
|
|
// validated against it.
|
|
Edges []DependencyEdge
|
|
// SkipPerEdgeCycleCheck drops the per-edge cycle probe for a caller wiring
|
|
// a large graph, trading validation cost for speed. It NEVER drops the
|
|
// whole-graph gate that runs once at the end, and it never drops the
|
|
// self-dependency refusal: an edge that points an issue at itself is
|
|
// refused with or without it.
|
|
SkipPerEdgeCycleCheck bool
|
|
}
|
|
|
|
// AddDependenciesResult reports the edges that landed.
|
|
type AddDependenciesResult struct {
|
|
// Added is the edges this request wrote, in request order. All-or-nothing
|
|
// means it is either every requested edge or the call failed, so it echoes
|
|
// the request — deliberately, the way CloseOutcome echoes its IssueID: a
|
|
// caller reporting what landed reads the RESULT, and never has to know
|
|
// which of the two it is safe to read.
|
|
Added []DependencyEdge
|
|
}
|
|
|
|
// RemoveDependencyRequest describes the removal of one edge.
|
|
type RemoveDependencyRequest struct {
|
|
// Actor is the remover and must not be empty. It is what the
|
|
// dependency_removed entry a successful removal records is attributed to,
|
|
// the mirror of AddDependenciesRequest.Actor.
|
|
Actor string
|
|
// IssueID and DependsOnID name the edge exactly. Neither may be empty.
|
|
IssueID string
|
|
DependsOnID string
|
|
}
|
|
|
|
// RemoveDependencyResult reports what the removal found.
|
|
type RemoveDependencyResult struct {
|
|
// Removed is false when no such edge existed. That is a SUCCESS, not a
|
|
// refusal: removing an edge twice leaves the same graph as removing it
|
|
// once, and an agent replaying its own teardown should not have to
|
|
// classify an error to discover it already ran. Nothing is written for it
|
|
// and no history entry is recorded.
|
|
Removed bool
|
|
}
|
|
|
|
// DependencyEditor describes guarded edits to the dependency graph: the write
|
|
// side of `bd dep add` and `bd dep remove`, and — like Lifecycle, Reader,
|
|
// ReadyClaimer and BatchCloser — 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 two more Lifecycle verbs because an edge is
|
|
// not a field of an issue. It has two endpoints, and every refusal it can
|
|
// raise — a cycle, a hierarchy deadlock, a type conflict — is a statement
|
|
// about the GRAPH the two endpoints sit in rather than about either row. A
|
|
// patch has nowhere to put that.
|
|
//
|
|
// An edge FOLLOWS ITS SOURCE. Both methods edit the durable graph `bd dep`
|
|
// shows and `bd dolt log` versions when the source is a durable issue, and the
|
|
// ephemeral graph when it is an ephemeral one — a wisp has no durable row for
|
|
// an edge to hang off, so there is no third answer. One request may mix the
|
|
// two; it is still one transaction, and still all-or-nothing across both.
|
|
// Only the durable half is versioned, so a request made entirely of ephemeral
|
|
// edges records no history entry.
|
|
//
|
|
// A TARGET's plane is independent of its source's: either class may depend on
|
|
// the other.
|
|
//
|
|
// EACH METHOD LEAVES A TRAIL IN THE SOURCE'S EVENT STREAM, attributed to the
|
|
// request's Actor: a genuinely new edge records a dependency_added entry, and
|
|
// a removal that found its edge a dependency_removed one. Work that wrote
|
|
// nothing records nothing — an idempotent same-type re-add and a removal that
|
|
// found no edge both leave the stream as they found it. The trail follows the
|
|
// source's plane exactly as the edge does, which is what makes it readable on
|
|
// an ephemeral edge at all: the wisp plane is not versioned, so for a
|
|
// wisp-sourced edge this is the only record the operation leaves.
|
|
//
|
|
// Implementations never mutate caller-owned request values, snapshot the
|
|
// request at method entry, and apply validation and normalization only to
|
|
// attempt-local clones. Deterministic request-validation failures match
|
|
// ErrValidation and leave persistent state unchanged.
|
|
type DependencyEditor interface {
|
|
// AddDependencies asserts every edge in the request as ONE durable act:
|
|
// one transaction, one history entry. Any refused edge refuses the whole
|
|
// request and writes nothing — a self-dependency (ErrSelfDependency), a
|
|
// scheduling cycle (ErrDependencyCycle), a conflicting type on a pair that
|
|
// already has an edge (*DependencyTypeConflictError), a blocking edge that
|
|
// would gate an issue on its own ancestor or descendant
|
|
// (*DependencyHierarchyConflictError), or a SOURCE that does not exist.
|
|
//
|
|
// A target's existence is checked only where the backend can see it. A
|
|
// target may legitimately be an "external:" reference or an issue in
|
|
// another repository, neither of which this database holds, so there is no
|
|
// blanket unknown-target refusal to promise. Where the backend CAN see the
|
|
// absence — an id in this database's own namespace, carrying no
|
|
// "external:" marker and matching no row — the edge is refused, and the
|
|
// request writes nothing like any other refusal.
|
|
//
|
|
// NEITHER EXISTENCE REFUSAL NAMES AN IDENTITY YET. The four refusals above
|
|
// hand a caller a sentinel or a typed value to branch on; a ghost source
|
|
// and a missing local target are only "an error", and not even the same
|
|
// error text on every implementation. So a caller cannot today tell a
|
|
// ghost endpoint from an infrastructure failure. That is a known gap
|
|
// (bd-yby99.9) rather than a promise the refusal will stay anonymous, and
|
|
// nothing should be written that string-matches it.
|
|
//
|
|
// An edge that already exists with the SAME type is idempotent and refuses
|
|
// nothing, and REPETITION WITHIN ONE REQUEST answers the same way: the
|
|
// second occurrence of a pair finds the first already written, so the pair
|
|
// is applied once, and the result still echoes every edge as requested.
|
|
// Two DIFFERENT types for one pair in one request is the same
|
|
// *DependencyTypeConflictError a pre-existing edge of the other type
|
|
// raises, and writes nothing.
|
|
//
|
|
// A request that wrote no durable edge — because every one of them already
|
|
// existed with the requested type — records NO history entry, the same way
|
|
// RemoveDependencyResult states it for a removal that found nothing. The
|
|
// one entry is recorded when at least one durable edge was genuinely
|
|
// written, and one is all that is recorded however many were.
|
|
AddDependencies(ctx context.Context, req AddDependenciesRequest) (AddDependenciesResult, error)
|
|
// RemoveDependency removes exactly the named edge. It is idempotent: a
|
|
// missing edge is Removed false with a nil error, not ErrNotFound.
|
|
RemoveDependency(ctx context.Context, req RemoveDependencyRequest) (RemoveDependencyResult, error)
|
|
}
|