* fix(issueops): enforce the dotted-child dependency rule on every leg The refusal of an explicit edge from a dotted-id child to its own ancestor (bd-abc.1 -> bd-abc; only the parent-child edge to the immediate dotted parent is allowed) lived only in cmd/bd (isDisallowedHierarchicalDependency). HTTP dependencies:add, batch:apply dep_add items and `bd create --graph`'s own edges skipped it. It is now one library rule, issueops.CheckDottedChildDependency, returning *issueops.DottedChildDependencyError (unwraps to ErrValidation, same message the CLI printed): - ValidateAddDependenciesRequest applies it, so DependencyEditor refuses on dolt, embedded, uow and the server behind httpapi (400 invalid_argument); - both BatchApplier bodies (issueops and uow) apply it to each dep_add item on the resolved ids, so a key bound to a minted dotted child is refused too; - the HTTP client checks it before the dial, as it does self-dependency, so the typed error survives the wire. cmd/bd keeps no copy: single-edge dep add / dep --blocks rely on the role; bd link (still on the store verb) and the --file bulk reporter call the library rule. CLI output is byte-identical (checked against origin/main). Conformance: RunDependencyEditorRefusesADottedChildGatedOnItsOwnParent and RunBatchApplyRefusesADottedChildGatedOnItsOwnParent wired on dolt, embedded, uow and http, plus a raw-wire served test past the client check and handler mapping cases. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(batch): refuse a dotted child gated on its own ancestor in bd batch Review fixup for PR #7424 (iterations 1 and 2). Major: a bd batch script line `dep add bd-abc.1 bd-abc` still wrote the edge this PR refuses everywhere else, on both backends. Neither batch dispatch writes through the DependencyEditor role that enforces the dotted-child rule: the classic arm calls storage.Transaction.AddDependency and the proxied arm the unit of work's AddDependencies verb. Both arms now build the edge with one helper, batchDepAddEdge, which keeps the default type and the arity and type errors, and asks publicops.CheckDottedChildDependency the way bd link does. A refused line rolls the whole batch back. Tests: TestBatchDepAddEdge (default and explicit types, arity and type errors, three refusals typed *DottedChildDependencyError matching ErrValidation, and the immediate parent-child edge allowed), and TestProxiedServerBatchDepAddRefusesADottedChildGatedOnItsParent (classic and proxied: the refusal names line 2, rolls back an earlier update line and writes no edge, and `dep add C P parent-child` still lands exactly one), registered in the proxied shard manifest. A mutant that drops the rule from the shared helper fails both; one that bypasses the helper in the proxied arm alone fails the proxied leg. Minors: - For a child whose parent-child edge is already stored (a `bd create --parent` child) the rule answers ahead of the hierarchy and type conflicts, so an HTTP caller now gets 400 invalid_argument where it got 409 dependency_cycle (blocking types) or dependency_exists (any other type). Documented in the DependencyEditor role doc, the CHANGELOG entry and the httpapi batch-apply test comment, and pinned by a stored-hierarchy phase in the DependencyEditor and BatchApplier dotted-child conformance contracts on every leg; a mutant that drops the rule gets the hierarchy conflict instead (409 dependency_cycle on the wire). - The bd create --graph dry-run note now says the live create may also refuse an edge that gates a dotted-id child on its own ancestor. - The DottedChildDependencyError comment says the message is kept verbatim and says "deadlock" whatever the type. Not changed: bd relate (relates-to does not schedule) and the edges a create writes with its issue (bd create --deps/--waits-for, and over HTTP an explicit dotted id with a non-immediate ParentID) still write through paths that skip the rule. The scheduling shapes need an explicit dotted id or a grandparent target. Follow-up bd-25s1wh tracks moving the rule down to the domain/store add verbs, with a structural bypass for reparent and template edges. Iteration 2 (minor): the CheckDottedChildDependency doc no longer implies bd link and bd batch are the only writers outside the roles. It names bd relate and the create edges as not applying the rule yet and cites bd-25s1wh. Complexity (cyclomatic/cognitive): runBatchOp 23/35 -> 21/31, runBatchOpUOW 28/48 -> 26/44, batchDepAddEdge 5/4. Touching them brings both pre-existing dispatch switches into the measured set; splitting them is out of scope here. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(issueops,httpapi): document the dotted-child 400 and widen its gap list Review fixup for PR #7424 (relaunch, iteration 1, minors). - The OpenAPI spec now describes the wire change this PR makes. The dependencies:add and issues:batchApply 400 vocabularies name an edge from a dotted-id child to its own ancestor (anything but the parent-child edge to its immediate parent; param `edges` and `items`). dependencies:add says why that is request-intrinsic, and both 409s say it is never dependency_cycle or dependency_exists, even for a child whose parent-child edge is stored. Response descriptions only: the generated types and the wireshape digest are unchanged (make api-check). - The CheckDottedChildDependency doc no longer reads as a complete list of the writers that skip the rule. Besides bd relate and the create edges it names bd duplicate, bd supersede, bd duplicates --auto-merge (its related link and its reparenting) and the tracker engine's createDependencies, and says the molecule, template and swarm writers are unaudited. bd-25s1wh's notes carry the widened scope, including `bd duplicate bd-a.1 --of bd-a`. Declined (nit): unifying the root issueops import alias across the PR's cmd/bd files. batch.go is the one file that imports both issueops packages, so one of them needs an alias there; it uses publicops, the repo's usual alias for the root package, and aliasing the other side instead would rewrite base-owned lines. Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Gas City Adopt-PR Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
269 lines
14 KiB
Go
269 lines
14 KiB
Go
package issueops
|
|
|
|
import (
|
|
"context"
|
|
"fmt"
|
|
"strings"
|
|
|
|
"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
|
|
DepTracks = types.DepTracks
|
|
)
|
|
|
|
// 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), an
|
|
// explicit edge from a dotted-id child to its own ancestor
|
|
// (*DottedChildDependencyError), 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).
|
|
//
|
|
// The dotted-child refusal is decided from the request alone, before any
|
|
// read, so it takes precedence over every refusal that reads stored rows:
|
|
// a child whose parent-child edge to that parent is already stored (the
|
|
// `bd create --parent` shape) is refused with *DottedChildDependencyError,
|
|
// which matches ErrValidation, not with the hierarchy or type conflict the
|
|
// stored edge would otherwise raise.
|
|
//
|
|
// 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)
|
|
}
|
|
|
|
// DottedChildDependencyError refuses an explicit edge from a dotted-id child to
|
|
// its own ancestor. The id already says "bd-abc.1 is under bd-abc": a child
|
|
// inherits its parent's completion through the hierarchy, so a blocking (or any
|
|
// other) explicit edge back up the tree either duplicates that structure or, for
|
|
// a blocking type, deadlocks it — the parent cannot close before the child, and
|
|
// the child would wait on the parent.
|
|
//
|
|
// The one edge it allows is the hierarchy itself: a parent-child edge to the
|
|
// IMMEDIATE dotted parent. A parent-child edge to a higher ancestor is refused
|
|
// too, because it would contradict the parent the id names.
|
|
//
|
|
// It unwraps to ErrValidation: the refusal is decidable from the two ids and
|
|
// the type alone, with no read, so it is a property of the request.
|
|
//
|
|
// The message is the sentence `bd dep add` already printed, kept verbatim, so
|
|
// it says "deadlock" whatever the type; Type is carried for callers that
|
|
// inspect the refusal and is not rendered.
|
|
type DottedChildDependencyError struct {
|
|
IssueID string
|
|
DependsOnID string
|
|
Type DependencyType
|
|
}
|
|
|
|
func (e *DottedChildDependencyError) Error() string {
|
|
return fmt.Sprintf("cannot add dependency: %s is already a child of %s. Children inherit dependency on parent completion via hierarchy. Adding an explicit dependency would create a deadlock",
|
|
e.IssueID, e.DependsOnID)
|
|
}
|
|
|
|
// Unwrap classifies the refusal as request validation.
|
|
func (e *DottedChildDependencyError) Unwrap() error { return ErrValidation }
|
|
|
|
// IsDottedChildDependency reports whether an edge from issueID to dependsOnID
|
|
// of type depType is the dotted-id hierarchy conflict CheckDottedChildDependency
|
|
// refuses. It is exported for callers that phrase the refusal themselves (a
|
|
// bulk report naming the offending line); every role enforces it through
|
|
// CheckDottedChildDependency.
|
|
func IsDottedChildDependency(issueID, dependsOnID string, depType DependencyType) bool {
|
|
_, immediateParent, depth := types.ParseHierarchicalID(issueID)
|
|
if depth == 0 || dependsOnID == "" {
|
|
return false
|
|
}
|
|
if dependsOnID != immediateParent && !strings.HasPrefix(issueID, dependsOnID+".") {
|
|
return false
|
|
}
|
|
return depType != DepParentChild || dependsOnID != immediateParent
|
|
}
|
|
|
|
// CheckDottedChildDependency is the ONE enforcement of the dotted-id hierarchy
|
|
// rule. Every DependencyEditor implementation applies it to each requested edge
|
|
// and every BatchApplier applies it to each dep_add item once its refs resolve,
|
|
// so `bd dep add`, an HTTP dependencies:add, and a batch apply (including
|
|
// `bd create --graph`'s own edges) refuse the same edge the same way. Two CLI
|
|
// paths that write an edge through a store verb instead of a role call it
|
|
// themselves: `bd link` and `bd batch`'s `dep add`.
|
|
//
|
|
// Other edge writers do not apply it yet, so they can still store an edge the
|
|
// roles refuse. The known ones are `bd relate`; the edges a create writes with
|
|
// its issue (`bd create --deps`/`--waits-for`, and Lifecycle.Create's ParentID,
|
|
// Dependencies and WaitsFor); `bd duplicate`, `bd supersede` and
|
|
// `bd duplicates --auto-merge`'s link and reparenting; and the tracker engine's
|
|
// createDependencies. The molecule, template and swarm writers have not been
|
|
// audited against it. bd-25s1wh tracks the gap.
|
|
func CheckDottedChildDependency(issueID, dependsOnID string, depType DependencyType) error {
|
|
if IsDottedChildDependency(issueID, dependsOnID, depType) {
|
|
return &DottedChildDependencyError{IssueID: issueID, DependsOnID: dependsOnID, Type: depType}
|
|
}
|
|
return nil
|
|
}
|