beads/issueops/deleter.go
Julian Knutsen 2c3a75d78c
Add DeleteRequest.ExpectedVersion: a compare-and-delete on the named row (#5481)
* Add DeleteRequest.ExpectedVersion: a compare-and-delete on the named row

`bd delete` is the one irreversible verb with no way to say "only if this
is still the row I looked at". Every other guarded write has one —
Lifecycle's Update, Close and Reopen all take an ExpectedVersion over the
same row_lock token — and the operation that most needs it is the one
where being wrong cannot be undone. A caller that reads a row, decides it
is finished with it, and deletes it has a window in which somebody else
reopened, reassigned or restarted the work; today the delete lands anyway.

The token is the ordinary one: server-minted, opaque, equality-only, nil
to disable, and read inside the deleting transaction so the pair is a
compare-and-delete rather than a read followed by a hopeful write.

TWO DECISIONS ARE WORTH THE REVIEW.

It requires a SINGLE-ID request, and a non-nil version beside more than
one distinct id is ErrValidation before anything is read. A row version
is per-row and the space is not shared, so one number checked against a
batch would pass a whole list of never-written rows by coincidence —
every one of them holds 0 — and fail forever for any list whose rows have
diverged. A guard that passes by coincidence and a guard nobody can
satisfy are the same defect from two sides. The shape a batch would need
is a token per ITEM, which BatchCloser.Items is, and this role is a list
of ids rather than a list of items; BatchCloseItem carries no version for
the same reason. Duplicates collapse first, so `bd delete a a` with a
token is one row and is legal.

It OUTRANKS the dependents guard and neither Force nor Cascade bypasses
it. A mismatch says the caller's whole view is stale, so reporting the
dependents refusal first would ask it to choose --cascade or --force over
information that has already moved; and force bypasses policy, never a
precondition, exactly as CloseRequest.Force does. It still ranks below
the existence probe: a request that named no row has nothing to be stale
about.

Two bodies, as ever. The store legs call the same CheckVersionInTx the
update and close guards use, on the transaction they delete in. The
unit-of-work leg compares the row its own existence probe already
loaded — the probe now keeps rows rather than a set of ids — which is
what updatePreconditionsHold does for the same token on the update path,
and avoids a second read of the same rows in the same unit of work.

Four contract cases on all three legs, written as a falsifiable pair: the
satisfied case takes the row's REAL token straight out of row_lock, on
both planes, so a body that refused every versioned delete reddens; the
stale case is the refusal, under DryRun too, with the rows counted raw
and the token asserted unmoved. The ranking case keeps a live outside
dependent on every arm, so "force did not bypass" is distinguishable from
"force was not needed", and ends on a matching-token force release so the
three refusals cannot be satisfied by a body that refuses unconditionally.
The arity case uses a token that MATCHES the first id, which is the only
arrangement that catches a body checking the first row and deleting the
list, and pairs it with the repeated-mention collapse so the rule cannot
be read as "expected-version deletes take one element".

FACADE ONLY. No wire, spec or httpapi change: the delete handler reads an
explicit member allowlist, so a new leaf field is invisible to clients
until the wire half follows in the conditional-update / release wire slice
per the program's council gating.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Review: pin existence-outranks-version, and say what the second SELECT buys

Three review items, one of which was a real hole.

THE HOLE: the leaf promises the version precondition ranks BELOW the
existence probe — "a request that named no row has nothing to be stale
about" — and nothing watched it. A second block on RefusesAnAbsentID does,
with a single absent id carrying a version.

It asserts the TYPE and not the sentinel, which is the whole point.
errors.Is(err, ErrNotFound) is satisfied by the WRONG order too: the store
legs run the guard through CheckVersionInTx, which answers a bare wrapped
ErrNotFound of its own for a row that is not there, so a flipped order
looks identical to a reader of the sentinel. Only *NotFoundError — which
nothing but the existence probe mints, and which carries the id — tells
them apart. The unit-of-work leg cannot answer at all: its comparison reads
the row the probe loaded, so a flipped order is a nil dereference.

Watched: moving the guard above the probe in the store body reddens it.

The other two are prose. workapi/delete.go cited `--expect-version`, a flag
that does not exist — the wire half is deferred — and now states the request
shape instead. And delete_role.go now says that CheckVersionInTx re-reads a
row the existence probe already returned, that what the second SELECT buys
is ONE definition of the guard shared with the update and close paths, and
that the unit-of-work leg answers the same trade the other way because the
shared function is not reachable from it — so the difference reads as a
consequence of where each leg sits rather than as drift.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Review Sim <ci@beads.test>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-09 07:17:54 -07:00

369 lines
19 KiB
Go

package issueops
import (
"context"
"errors"
"fmt"
"strings"
)
// DeleteRequest names the rows to erase and says what to do about the rows
// that point at them.
//
// IT IS NOT A SELECTION. Sweeper describes a SET and lets the implementation
// resolve it; this one is handed ids and deletes those. That difference is why
// this request carries no predicate at all — no status, no cutoff, no glob —
// and why it needs no require-a-filter gate: a caller cannot spell "everything"
// here without typing every id.
//
// Implementations never mutate caller-owned request values: IDs is read, never
// written through, and never sorted in place.
type DeleteRequest struct {
// Actor attributes the deletion wherever the backend records attribution.
// It is not an authorization boundary, and an empty Actor is accepted for
// the reason SweepRequest.Actor is: the deletion of a row leaves no row to
// attribute it on. It DOES reach the rewritten neighbors, which survive,
// so a workspace that cares who rewrote a description passes one.
Actor string
// IDs names the rows to delete, in either plane. It is REQUIRED: an empty
// or all-blank slice is ErrValidation rather than a no-op, because "delete
// nothing" is never what a caller meant to ask and a silent zero is how a
// broken id list looks from the outside.
//
// DUPLICATES COLLAPSE and the surviving order is the caller's first
// mention of each id. An id repeated in a `--from-file` list is one row,
// not a row deleted twice.
//
// EVERY ID MUST NAME A STORED ROW. An id that names none is ErrNotFound
// and NOTHING IS DELETED — not even the ids beside it that did resolve.
// That is the all-or-nothing this operation needs most: a batch that
// deleted eight of ten and then reported a typo has already done the part
// that cannot be undone.
//
// IDs ARE EXACT. Prefix resolution, cross-repository routing and `bd`'s
// other id conveniences happen at the front door, above this role, because
// resolving an ambiguous prefix to a row and then deleting it is the one
// place a convenience is not one.
IDs []string
// ExpectedVersion is an optimistic-concurrency precondition on the row this
// request NAMES: the deletion proceeds only if that row's current
// RowVersion — the opaque server-minted row_lock token carried on
// types.Issue.RowVersion — still equals *ExpectedVersion, and otherwise the
// request is refused with ErrVersionMismatch and NOTHING IS DELETED.
//
// THE TOKEN IS OPAQUE AND COMPARED FOR EQUALITY ONLY. It is minted afresh
// on every lifecycle write rather than incremented, so it does not order:
// "newer" and "older" are not questions this precondition can answer. The
// only question it answers is whether the row is still the one the caller
// looked at, which is the only question a caller about to erase something
// irreversibly needs answered.
//
// nil DISABLES THE CHECK. It is a pointer for the reason
// UpdateRequest.ExpectedVersion is one: nil, meaning "do not check", has to
// be distinct from a caller that requires the never-written version 0.
//
// IT REQUIRES A SINGLE-ID REQUEST. A non-nil ExpectedVersion beside more
// than one DISTINCT id is ErrValidation, refused before anything is read.
// One token cannot describe two rows: the version space is per-row and not
// shared, so checking one number against a batch would pass a whole list of
// never-written rows by coincidence — every one of them holds 0 — and fail
// forever for any list whose rows have since diverged. A guard that passes
// by coincidence and a guard a caller can never satisfy are the same defect
// seen from two sides. The per-id shape a batch would actually need is a
// token PER id, which is a list of ITEMS rather than a list of ids, and
// this role is not born with one; BatchCloser.Items is where that shape
// lives, and BatchCloseItem deliberately carries no version for the same
// reason its own doc gives.
//
// DUPLICATES COLLAPSE FIRST, so `bd delete a a` with a token names one row
// and is legal. The refusal counts DISTINCT ids, not mentions.
//
// NEITHER Cascade NOR Force BYPASSES IT. Force bypasses POLICY — the
// dependents guard — and never a precondition, exactly as
// CloseRequest.Force bypasses close policy and never the version it is
// paired with. A caller that could orphan its way past a stale token would
// be doing the irreversible half of the operation on a row it no longer
// recognizes.
//
// IT GUARDS THE NAMED ROW'S LIFECYCLE STATE, NOT ITS GRAPH AND NOT ITS
// CLOSURE. RowVersion is reminted by status, assignee and started_at
// writes and deliberately not by label, dependency, rename or is_blocked
// writes, so a matching token does NOT promise that the row's edges are the
// ones the caller saw. Under Cascade that has a consequence worth saying
// out loud: the closure is resolved inside the deleting transaction, so a
// caller whose named row is unchanged deletes the closure the graph has
// NOW, which an edge added since its read may have grown. A caller that
// needs the closure itself pinned wants DryRun's preview and not this.
ExpectedVersion *int64
// Cascade also deletes the TRANSITIVE CLOSURE of everything that depends
// on the named rows, in both planes. It is what `bd delete --cascade`
// asks for.
//
// WITH CASCADE THERE IS NOTHING LEFT TO ORPHAN, by construction: the
// closure contains every dependent of every row it deletes. So Cascade
// makes Force moot rather than conflicting with it — a request carrying
// both is legal and behaves as Cascade, and DeleteResult.Orphaned comes
// back empty.
//
// The traversal is BOUNDED. A closure that grows past the backend's
// runaway limit aborts the whole request and deletes nothing rather than
// deleting as far as it got.
Cascade bool
// Force deletes the named rows and leaves rows that depended on them
// ORPHANED — their edges into the deleted rows go, they themselves stay,
// and DeleteResult.Orphaned names them.
//
// WITHOUT Cascade AND WITHOUT Force, a named row that some row OUTSIDE the
// request depends on is refused: the request fails with a
// DependentsOutsideRequestError and nothing is deleted. That guard is the
// role's, not a front door's, for the reason Sweeper's require-a-filter
// gate is: a second front door that inherited the capability without the
// guard would orphan a workspace's graph by omission.
//
// THE GUARD READS BOTH PLANES ON BOTH ENDS OF THE EDGE, and there is no
// wisp exemption at either end. A named WISP with a durable dependent is
// refused exactly as a named issue is, and a durable row's wisp dependent
// counts too. Half of that was an implementation gap for one release: the
// store-backed body asked the guard about the durable half of the request
// only, so `bd delete <wisp>` orphaned a durable dependent without saying
// so and without being refused.
//
// A dependent INSIDE the request is not a dependent for this purpose — a
// batch that names both ends of an edge is deleting the edge too, and
// refusing it would make `bd delete a b` fail on exactly the pair a caller
// took care to list together.
//
// IT BYPASSES POLICY, NEVER A PRECONDITION. It does not bypass
// ExpectedVersion and it does not bypass the existence probe: the guard it
// answers is the one about OTHER rows, and a caller saying "orphan them" has
// said nothing about whether the row it named is still the row it read.
Force bool
// DryRun reports what the deletion WOULD do and changes nothing, including
// history.
//
// IT REFUSES WHERE THE REAL RUN WOULD REFUSE, and that is the whole value
// of it on this operation: an unforced preview over a row with outside
// dependents fails with the same DependentsOutsideRequestError, and a
// preview naming an absent id fails with the same ErrNotFound, so a caller
// that got a clean preview has learned the real run will not stop
// half-explained. It is computed against the same snapshot the real
// deletion would have used.
DryRun bool
}
// DeleteResult reports one deletion.
//
// EVERY NUMBER DESCRIBES THE SAME SNAPSHOT, because the guard, the cascade
// expansion, the deletion and the reference rewrite all run in ONE
// transaction. See Deleter.Delete.
type DeleteResult struct {
// DryRun echoes the request, so a result value carries whether its numbers
// describe rows that are gone or rows that would go without the caller
// having to keep the request beside it.
DryRun bool
// Deleted is how many rows were deleted, or — under DryRun — would be.
// Under Cascade it counts the whole closure, so it is normally larger than
// len(IDs) and is the number a caller should show rather than the request
// length.
Deleted int
// Dependencies, Labels and Events count the ROWS OF ASSOCIATED DATA that
// went with them: edges touching a deleted row in either direction, its
// labels, and its recorded events. A deletion's visible effect is much
// larger than its row count, and these are the numbers that explain it.
Dependencies int
Labels int
Events int
// ReferencesUpdated counts the SURVIVING rows whose text was rewritten —
// rows, not occurrences: a neighbor citing two deleted ids in three
// fields counts once. It is 0 under DryRun, because a preview rewrites
// nothing and reporting a number there would describe an edit that did not
// happen.
ReferencesUpdated int
// Orphaned names the surviving rows that depended on something this
// request deleted, in ascending id order.
//
// It is populated exactly when the request carried Force without Cascade —
// the only mode in which orphaning is possible — and is empty otherwise.
// It is also carried on the DependentsOutsideRequestError the unforced
// mode returns, so the same fact reaches a caller whichever answer it got.
//
// It is DIRECT dependents only. A row two edges away loses no edge and is
// not orphaned by this deletion; it is merely blocked by something that is
// now blocked by nothing.
Orphaned []string
}
// ErrDependentsOutsideRequest classifies the unforced refusal: a named row has
// a dependent the request did not name, and neither Cascade nor Force said
// what to do about it.
//
// It lives beside the role rather than in errors.go because it is meaningless
// without DeleteRequest.Cascade and DeleteRequest.Force to explain it, and
// errors.go is the file every parallel role slice touches.
var ErrDependentsOutsideRequest = errors.New("dependents outside deletion set")
// DependentsOutsideRequestError reports WHICH row was blocked and by WHAT, so
// a caller can name them without parsing the message. It wraps the sentinel
// rather than replacing it.
//
// It names ONE blocked row — the first the implementation reached — rather
// than every blocked row in the request. That is deliberate and matches the
// only answer a caller can act on: the request is refused whole, so the second
// blocked row changes nothing about what to do next, and enumerating all of
// them would cost a full scan on the path that deletes nothing.
type DependentsOutsideRequestError struct {
// IssueID is the named row that has dependents outside the request.
IssueID string
// Dependents are that row's direct dependents that the request did not
// name, in ascending id order.
Dependents []string
}
func (e *DependentsOutsideRequestError) Error() string {
return fmt.Sprintf("issue %s has dependents not in deletion set; use --cascade to delete them or --force to orphan them", e.IssueID)
}
// Unwrap makes DependentsOutsideRequestError match ErrDependentsOutsideRequest.
func (e *DependentsOutsideRequestError) Unwrap() error { return ErrDependentsOutsideRequest }
// NotFoundError reports which of a request's ids named no stored row. It wraps
// ErrNotFound, so a caller that only wants to classify the failure still can.
//
// It names EVERY missing id rather than the first, unlike the dependents
// refusal above, because this one is a typo report: a caller handed a list and
// wants the whole list of what did not resolve, and the ids are already in
// hand from the probe that found them missing.
type NotFoundError struct {
// IDs are the requested ids that named no row in either plane, in the
// order the request spelled them.
IDs []string
}
func (e *NotFoundError) Error() string {
return "issues not found: " + strings.Join(e.IDs, ", ")
}
// Unwrap makes NotFoundError match ErrNotFound.
func (e *NotFoundError) Unwrap() error { return ErrNotFound }
// Deleter describes erasure of NAMED rows — the capability behind
// `bd delete` — and, like every other capability here, 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 A DIFFERENT QUESTION FROM ITS NEIGHBORS.
//
// - Sweeper erases a SET the caller described: closed rows of one tier,
// narrowed by a cutoff and a glob. This erases rows the caller NAMED. The
// difference decides where the safety lives — a description can be
// accidentally too wide, so Sweeper carries a require-a-filter gate; a
// list of ids cannot, so this one's guard is about the graph instead.
// - Lifecycle closes ONE issue and leaves the row. A closed row is still
// readable, still cited, still in a report. This one leaves nothing, which
// is why its unforced mode refuses rather than warns.
// - DependencyEditor removes EDGES. This removes edges as a consequence of
// removing their endpoints, and the two must not be composed by a caller
// to imitate it: unlink-then-delete is two transactions, and the window
// between them is a graph that has already lost its edges and still has
// the row.
//
// WRITES, AND THE SECOND DESTRUCTIVE ROLE IN THIS PACKAGE. Nothing it deletes
// comes back. Its completion fires no hook, for the reason Sweeper's does not:
// internal/hooks publishes on_create, on_update and on_close and none of them
// names a deletion.
//
// A DELETION MAINTAINS BLOCKED STATE under BlockedStateInvariant. The rows it
// erases are gone, so the promise is about the SURVIVORS: a row whose only
// blocker was deleted is left unblocked, and so is everything that inherited
// that block from it, inside the deleting transaction. This is the same
// obligation the reference rewrite has and for the same reason — a survivor
// left pointing at an absent row, or left blocked by one, is the state the
// unforced guard exists to prevent a caller from creating by hand.
//
// Deterministic request-validation failures match ErrValidation. Result values
// are unspecified when error is non-nil.
type Deleter interface {
// Delete erases req.IDs and, under Cascade, everything that depends on
// them, and reports what it did.
//
// IT IS ONE TRANSACTION, and on this role that covers one thing it did not
// cover before: THE TEXT-REFERENCE REWRITE. The direct CLI route deleted
// the rows in a transaction and then rewrote the neighbors' text in
// separate statements afterwards, so a failure between the two left a
// workspace whose rows were gone and whose descriptions still pointed at
// them by id. Here the existence probe, the guard, the cascade expansion,
// the deletion and the rewrite all see one snapshot and land or fail
// together.
//
// WHAT THAT COSTS, said out loud because it is a real trade: the
// transaction is now as large as the deletion PLUS its neighborhood. A
// request whose neighbors are numerous enough to exceed a backend's write
// timeout fails whole and deletes nothing, where the split version would
// have deleted the rows and left the text stale. That is the better of the
// two failures, but it is a ceiling: a caller deleting a very large set
// splits the request rather than expecting progress.
//
// WHICH ROWS GET REWRITTEN is the deletion set's GRAPH NEIGHBORS — the
// surviving rows joined to a deleted row by a dependency edge in either
// direction — and not the workspace. Each occurrence of a deleted id in a
// neighbor's description, notes, design or acceptance criteria becomes
// `[deleted:<id>]`, matched at ASCII word boundaries the way
// SweepRequest.ProtectReferenced matches: `be-1` rewrites in "see (be-1)."
// and not inside `xbe-1` or `be-12`. A row that cites a deleted id in
// prose WITHOUT an edge to it is left alone, because a workspace-wide text
// scan on every delete is a cost this operation does not take.
//
// THE ORDER THE REFUSALS HAPPEN IN IS PART OF THE ANSWER, because a
// request can fail several ways at once: request validation, then the
// existence probe, then the version precondition, then the dependents
// guard. `bd delete typo real-with-dependents` reports the TYPO, which is
// the one the caller can fix without deciding anything.
//
// THE VERSION PRECONDITION OUTRANKS THE DEPENDENTS GUARD, and that
// placement is the answer to "which refusal helps the caller more". A
// mismatch says the row has changed since the caller read it, so the whole
// plan — including whether to delete at all — is built on a stale view;
// reporting the dependents refusal first would be asking a caller to choose
// --cascade or --force over information that has already moved. It ranks
// BELOW the existence probe for the opposite reason: a version is a fact
// about a row, and a request that named no row has nothing to be stale
// about.
//
// REFUSALS:
//
// - an empty or all-blank IDs, and an IDs containing a blank entry:
// ErrValidation, before anything is read;
// - a non-nil ExpectedVersion beside more than one distinct id:
// ErrValidation, also before anything is read;
// - an id naming no row in either plane: *NotFoundError, matching
// ErrNotFound;
// - an ExpectedVersion that no longer matches the named row's current
// RowVersion: ErrVersionMismatch, which neither Force nor Cascade
// bypasses;
// - without Cascade and without Force, a named row with a dependent the
// request did not name: *DependentsOutsideRequestError, matching
// ErrDependentsOutsideRequest.
//
// EVERY ONE OF THEM DELETES NOTHING, under DryRun and otherwise.
//
// THE VERSION READ SHARES THE DELETING TRANSACTION, so the pair is a true
// compare-and-delete rather than a read followed by a hopeful write: a
// writer that committed before the transaction opened is caught by the read
// itself, and one that commits during it collides on the same row_lock cell
// and is replayed against the new value. That is the same two-limbed
// invariant Lifecycle's ExpectedVersion has, over the same token.
//
// A DRY RUN CHANGES NOTHING, including history: an implementation that
// records a version-control entry for a deletion records none for a dry
// run. Where an implementation versions at all, a call that deleted
// durable rows records EXACTLY ONE entry — a deletion is one act, not one
// per row, and not none. A deletion confined to tables the version-control
// plane ignores records none, because there is nothing to version.
//
// EXACTLY ONE IS A STEADY-STATE PROMISE, NOT A CRASH-ATOMIC ONE. An
// implementation may write the entry after the transaction that deleted
// the rows — the embedded store has no way to mint one inside its own —
// so a crash between the two leaves the rows gone and the entry unwritten
// until the next flush.
Delete(ctx context.Context, req DeleteRequest) (DeleteResult, error)
}