DependencyEditor.AddDependencies refuses an edge whose SOURCE names no row, and one whose TARGET names no row this database can see the absence of. Every other refusal the role can raise hands a caller something to branch on — ErrSelfDependency, ErrDependencyCycle, *DependencyTypeConflictError, *DependencyHierarchyConflictError — and these two handed back "an error", with different text on each backend. A programmatic consumer could not tell a ghost endpoint from an infrastructure failure, and the role's own doc said so rather than promising the anonymity would last. Both now carry an identity: ErrDependencySourceNotFound and ErrDependencyTargetNotFound, wrapped by a *DependencyEndpointNotFoundError that names the refused edge and which of its endpoints was absent. Two sentinels rather than one because the two are separate answers — a ghost source is always a bad id, while a target is refused only where this database would have held it. What is NOT refused is unchanged: an "external:" reference and another repository's id are still stored as external targets. The store-backed body and the cross-tier target precheck mint the refusal where they already read the row. The domain repository has no such read: it learns of the absence from a foreign-key violation, so it reads both endpoints back on the transaction that refused, only on the refusal path, and never downgrades the refusal to a probe's failure. Taking the identity out of the driver's constraint name would have been the thing a typed refusal exists to avoid. One user-visible consequence: the proxied-server path now renders "issue <id> not found" where it used to render a raw foreign-key violation, which is what the embedded path has always said. The guarded create classifies the new type where it classified the raw foreign-key signal, so a missing dependency, parent or waits-for target is still ErrValidation wrapping ErrNotFound on every backend. RemoveDependency is deliberately untouched. A removal that finds no edge is Removed false with a nil error, so there is no refusal there to name. The shared contract asserts the sentinel and the typed fields for each endpoint in TWO POSITIONS: alone in a request, and mid-batch where the refusal competes with the rollback of an edge already written, the half that also reads the graph back at zero edges. Both cases were verified red on all three backends before the production change — "issue <id> not found" untyped on the two store paths, "Error 1452 ... Foreign key violation" on the unit-of-work path. Agent-Signature: claude-code-claude-opus-5-unknown-reasoning on behalf of CI Bot Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
184 lines
9.2 KiB
Go
184 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
|
|
// (ErrDependencySourceNotFound).
|
|
//
|
|
// 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 with
|
|
// ErrDependencyTargetNotFound, and the request writes nothing like any
|
|
// other refusal.
|
|
//
|
|
// BOTH EXISTENCE REFUSALS CARRY THEIR IDENTITY. Each is a
|
|
// *DependencyEndpointNotFoundError naming the refused edge and the
|
|
// endpoint that was absent, wrapping its own sentinel, so a caller tells a
|
|
// ghost endpoint from an infrastructure failure — and the source case from
|
|
// the target case — with errors.Is and errors.As rather than by reading
|
|
// the message. The message itself remains prose and is not a promise.
|
|
//
|
|
// 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)
|
|
}
|