beads/issueops/dependencyeditor.go
Julian Knutsen 7c2568c323 feat(purge): live-dependent protection, --wisps-plane selector, hour-precision --older-than, --limit (#6883)
* feat(purge): live-dependent protection, --wisps-plane selector, hour-precision --older-than

An orchestrator's wisp retention step deletes every closed row in the
wisps table older than N hours, except a closed wisp that an
open/hooked/in_progress wisp depends on through parent-child, tracks or
blocks. `bd purge` could not express that: it selected the ephemeral
TIER (so closed --no-history beads, which live in the wisps table, were
left behind), it deleted a closed molecule root whose step was still
open, and it floored --older-than hours to whole days (36h swept rows
24h old). All three land together so `bd purge --wisps-plane
--older-than 168h --force` covers that step.

Live-dependent protection (issueops.SweepRequest.ProtectLiveDependents,
SweepSkips.LiveDependent): a candidate is held back when a live row
depends on it through a SweepLiveDependentEdgeTypes edge (parent-child,
tracks, blocks), read from both dependency tables. "Live" is the same
not-done set the reference scan uses, custom statuses included, so it
is a superset of open/hooked/in_progress. `bd purge` always asks for it
(no opt-out: removing live work's root is `bd delete`'s job); `bd prune`
does not. Reported as live_dependent_skipped in --json.

Wisps-plane selector (issueops.SweepWispsPlane, `--wisps-plane`): the
candidates are every closed row in the wisps TABLE, whatever its
ephemeral/no_history/wisp_type values, via a new single-plane search
(issueops.SearchWispsPlaneInTx) that the store backends call directly
and the unit-of-work provider reaches through
IssueUseCase.SearchWispsPlane, so embedded, server and proxied share one
body. It reaches durable-tier (no-history) rows, so it carries the
durable tier's require-a-filter gate.

--older-than (purge and prune): day values keep their meaning (7, 7d,
2w); anything else is a Go duration taken exactly (36h, 168h, 90m).

Tests: three new Sweeper contract cases (wisps plane clears the whole
table, wisps plane requires a filter, protects live dependents) run on
dolt, embeddeddolt and the uow provider; workapi unit tests; a CLI
retention scenario run in embedded, shared proxied and managed-local
proxied modes (fails against origin/main); TestParseOlderThan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(uow): classify IssueUseCase.SearchWispsPlane as a read in the notifying parity partition

TestRecordingIssueUseCaseCoversItsSurface requires every IssueUseCase
method to be either wrapped by the notifying decorator or exempted with
the reason it fires no hook. SearchWispsPlane reads state and changes
none, like SearchIssues beside it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(purge): refuse out-of-range --older-than; add --limit for bounded drains; cross-plane protection test

Review follow-ups on #6883.

--older-than: a day count past what a time.Duration holds (213504d,
30501w) used to wrap silently — 213504d became 25m26s, which on a
destructive command selected almost every closed row. It is now refused
as out of range; ParseDuration already refused oversized h/m/s values.

--limit N (issueops.SweepRequest.Limit, SweepResult.Remaining): one
purge deletes at most N rows, oldest closed_at first (then id), after
every protection, and reports the rest. --json adds remaining and
has_more when --limit is given. At ~15ms/row on the proxied path a
single unbounded sweep of a large backlog can outlive a caller's
deadline, roll back, and never clear; a bounded loop cannot. Negative
limits are ErrValidation at the role and refused at the CLI.

Tests: TestParseOlderThan out-of-range rows; contract cases
LimitTakesTheOldestClosedFirst and ProtectsLiveDependentsAcrossPlanes
(a live issues-table bead depending on a closed wisp via parent-child,
tracks and blocks keeps it) on dolt, embeddeddolt and uow; workapi
units for the ordering and the negative-limit refusal; the CLI
retention scenario now drains with --limit 1 and checks the overflow
refusal. CHANGELOG notes that sub-day Nh values used to round UP to a
day (12h is now taken exactly) and lists the protection under Changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 2ec0b2f072)
2026-09-28 15:54:56 +00:00

190 lines
9.6 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
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), 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)
}