beads/internal/workapi/delete.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

92 lines
3.3 KiB
Go

package workapi
import (
"fmt"
"sort"
"strings"
"github.com/steveyegge/beads/issueops"
)
// The shared, DATABASE-FREE half of issueops.Deleter: what a delete request
// means before anything is read, and how the two answers that name rows —
// the orphan list and the dependents refusal — are ordered.
//
// Every implementation runs these, so `bd delete` has one definition of a
// malformed request rather than one per backend.
//
// What is NOT here is the deletion. The existence probe, the guard and the
// erasure need one transaction (issueops.Deleter.Delete); the bodies live in
// internal/storage/issueops/delete.go and in the unit-of-work provider.
// ValidateDeleteRequest applies the request rules every Deleter implementation
// shares, before anything is read.
//
// There is deliberately no require-a-filter analog of the sweep gate here: a
// delete request carries no predicate at all, so a caller cannot spell
// "everything" without typing every id. The guard that does matter — dependents
// outside the request — needs the graph and therefore lives in the bodies.
//
// The ExpectedVersion arity rule is here rather than in the bodies for the
// reason the rest of this file exists: it needs no database, and a rule the
// bodies each spelled themselves is a rule that can differ per backend.
func ValidateDeleteRequest(in issueops.DeleteRequest) error {
if len(in.IDs) == 0 {
return fmt.Errorf("%w: delete requires at least one issue id", issueops.ErrValidation)
}
for i, id := range in.IDs {
if strings.TrimSpace(id) == "" {
return fmt.Errorf("%w: delete id at position %d is blank", issueops.ErrValidation, i)
}
}
// DISTINCT ids, not mentions: DeleteRequest.IDs promises duplicates
// collapse, so an IDs of {"a", "a"} carrying a version names ONE row and is
// legal. Counting the raw slice here would refuse the request the role's own
// normalization rule says is fine.
if in.ExpectedVersion != nil {
if distinct := len(NormalizeDeleteIDs(in.IDs)); distinct > 1 {
return fmt.Errorf("%w: expected-version delete names %d issues; one row version cannot describe more than one row",
issueops.ErrValidation, distinct)
}
}
return nil
}
// NormalizeDeleteIDs collapses duplicates, keeping the caller's FIRST mention
// of each id, and trims surrounding whitespace.
//
// First-mention order rather than sorted, because it is the order the front
// doors echo back in their "issues not found" line and in the confirmation
// hint they print.
//
// It assumes a request already accepted by ValidateDeleteRequest, so no entry
// trims to empty.
func NormalizeDeleteIDs(ids []string) []string {
seen := make(map[string]bool, len(ids))
out := make([]string, 0, len(ids))
for _, id := range ids {
trimmed := strings.TrimSpace(id)
if seen[trimmed] {
continue
}
seen[trimmed] = true
out = append(out, trimmed)
}
return out
}
// SortedDeleteIDs copies and sorts a set of ids ascending. It is what puts
// DeleteResult.Orphaned and DependentsOutsideRequestError.Dependents in the
// order issueops.DeleteResult promises, from bodies that collect them out of
// maps and would otherwise publish Go's map order.
func SortedDeleteIDs(ids map[string]bool) []string {
if len(ids) == 0 {
return nil
}
out := make([]string, 0, len(ids))
for id := range ids {
out = append(out, id)
}
sort.Strings(out)
return out
}