gastownhall__beads/issueops/dependencyeditor.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.
//
// EITHER METHOD MAINTAINS BLOCKED STATE under BlockedStateInvariant: an edge
// that lands or is removed leaves the column settled — for the source, for
// everything that inherits from it, and for any waiter whose gate the edge
// changed — inside the same transaction that wrote the edge.
//
// 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)
}