beads/issueops/batchapplier.go
Julian Knutsen e9e2c49431
Add issueops.BatchApplier: one plan, one transaction (#5480)
* Add issueops.BatchApplier: one plan, one transaction

A heterogeneous, ORDERED list of creates, updates, closes and edges applied
as one durable act. Each of BatchCreator, BatchCloser and DependencyEditor is
one verb repeated, so a caller that needs two of them needs two transactions
with a window in between; this role's unit is a PLAN.

The role, the two bodies, both decorators and the accessors on every
implementer. The wire half and the conformance contract land beside this.

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

* Close the empty-commit-message hole a no-op batch could open

ApplyBatchCommitMessage now reads the write as well as the result. The counts
are ItemResult.Changed, which is what a CALLER observes; a request can still
write a durable row with every count at zero — a same-type edge re-add
rewrites that edge row's metadata, a re-close can settle blocked state. An
empty message for one of those is an unlabelled Dolt commit on the store legs
and a rollback of a real write on the unit-of-work leg.

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

* Give BatchApplier the contract its two bodies justify

Thirty-nine cases over three legs and TWO independent bodies — the store legs
share issueops.ApplyBatchInTx, the unit-of-work leg cannot reach it, and the
contract header says so rather than claiming three backends agree.

The end-gate case is the one that could not have been written before: every
edge in it is legal when it is written, and only a re-validation against the
closure the whole request produced refuses the pair.

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

* Publish batchApply on v0, and delete batchCreate's false promise

The spec first, the types from it, the handler against the types. The item
union is a TAGGED single-shape object rather than a oneOf, because the
document's x-go-type doctrine forbids composition keywords; the create item
publishes sender, metadata, status, ephemeral and no_history, none of which
batchCreateIssues has — which is why no measured caller could use that one.

The wire result stays lean: ids, changed and a revision. The hydrated
snapshot on the Go contract is what the completion hooks consume, and hooks
never fire on this surface.

OQ2: batchCreateIssues' description claimed a dependency target could name an
earlier item of the same batch. It never could — the server mints the ids and
a wire item has no name — so the paragraph is deleted rather than qualified.

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

* Partition the two new dependency probes on the recorder's surface

The gate halves BatchApplier re-runs are repository PROBES — an ancestry walk
and a reachability walk — so recordingDepUC declares neither and the parity
test has to say so out loud rather than let embedding answer for it.

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

* Teach the proxied topology's capability golden about batchApply

The one expectation stored as data outside the package whose gates would
otherwise have caught it — which is what its own header warns about.

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

* Restore the CAS hook case, mint 409 already_exists, and stop over-claiming

Three fixes from review.

The rebase that brought MetadataCAS in left `case *hookMetadataCAS:` with an
EMPTY BODY: a Go type switch does not fall through, so RoleFiresHooks answered
FALSE for it and #5473's Listen refusal was silently disarmed. The compiler,
vet, lint and CI all pass on that. The case is restored and — because it had no
precondition of its own, which is why nothing caught it — serve_source_test now
pins CAS the way it pins the other four, with its peel assertion.

An occupied explicit create id becomes 409 already_exists rather than 400. The
body is well-formed and stays well-formed; what refuses it is state the client
must READ, and recovery is to look at that state. A dead 409 retires for free
where a narrowed 400 breaks clients.

Two headers claimed all three legs share the store body — every clause false,
one citing the contract header as agreeing when it says the opposite — and the
plan file gave a placement reason that is MetadataCAS's, not this role's. The
end-gate claim in ADDING_AN_ISSUEOPS_ROLE.md is narrowed to the true thing: the
two LEAF checks are shared, the orchestration around them forks.

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

* Give the scheduling-edge set one definition, in types

Four packages walked {blocks, conditional-blocks, parent-child} under four
names — isSchedulingEdge, isSchedulingDep, isSchedulingDependency, and the
isApplySchedulingEdge this branch added as the fourth. Adding a fifth
scheduling type was four edits with nothing to catch a missed one.

It goes in internal/types rather than the issueops leaf the review named,
because internal/storage/issueops imports internal/storage/domain, so domain
cannot import back and two of the four copies would have survived there. Beside
the Dep* constants themselves, every walker reaches it: nine call sites, one
definition, one edit for a fifth type.

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 06:59:34 -07:00

512 lines
26 KiB
Go

package issueops
import (
"context"
"fmt"
)
// Ref names ONE issue, either by an id that already exists or by the Key a
// create item earlier in the same request gave itself.
//
// EXACTLY ONE OF THE TWO IS SET. Both set is a caller that cannot say which it
// meant, neither set is a reference to nothing, and both are ErrValidation
// before anything is written.
//
// A KEY REACHES BACKWARD ONLY. A ref used as a TARGET — the row an update or a
// close acts on, or either endpoint of an edge — may name a key only if the
// create item that declares it appears EARLIER in Items. That is forced by
// what the items do rather than chosen for tidiness: an update has to see the
// row it patches, so the row must already exist when the update runs, and
// items run in declaration order. A key declared later is *RefError with
// DeclaredLater true, which is a different diagnosis from a key nothing in the
// request declares at all, and the two are distinguished so a caller can fix
// an ORDERING mistake without hunting for a typo.
//
// CreateItem.MetadataRefs is the one exception and states its own rule.
type Ref struct {
// Key names a create item in THIS request by its CreateItem.Key.
Key string
// ID names a row that already exists, exactly. There is no fuzzy, prefix or
// cross-repo resolution here, for the reason GetRequest.ID gives.
ID string
}
// ItemKind names what one item of a batch does. It is a CLOSED set, unlike
// DependencyType: every value here is a verb this role implements, and an
// unknown one is a request the role cannot execute rather than a workspace's
// own vocabulary.
type ItemKind string
// The item vocabulary. Four verbs, and the exclusions are as deliberate as the
// inclusions — see BatchApplier for why reopen, dep_remove and a metadata
// compare-and-set are not here.
const (
// ItemCreate creates one issue.
ItemCreate ItemKind = "create"
// ItemUpdate patches one existing issue.
ItemUpdate ItemKind = "update"
// ItemClose closes one existing issue.
ItemClose ItemKind = "close"
// ItemDepAdd asserts one dependency edge.
ItemDepAdd ItemKind = "dep_add"
)
// CreateItem creates one issue and optionally NAMES it, so later items can
// reach the row without knowing the id the request has not minted yet.
type CreateItem struct {
// Key is this item's name inside the request. It is OPTIONAL: an item
// nothing refers to needs no name. When present it must be unique across
// the request's create items, and it is what a later Ref.Key resolves to.
//
// It is not stored anywhere and it is not an id. ApplyBatchResult.Keys is
// where the caller reads the id the key was bound to.
Key string
// Issue is the issue to create and must not be nil. It is read under
// CreateRequest.Issue's rules WITHOUT EXCEPTION — the same fields accepted,
// the same derived ones ignored, Labels authoritative, Issue.Comments and
// Issue.Dependencies empty — because edges in this role are ITEMS and an
// item is the only place an edge is spelled.
//
// AN EXPLICIT ID IS CREATE-ONLY, as it is for Lifecycle.Create: an id that
// already names a row is ErrAlreadyExists and the WHOLE request is refused,
// because this role is all or nothing.
//
// Ephemeral and NoHistory are read PER ITEM, so one request may create
// durable issues and ephemeral ones together. The two planes hold their
// edges in different tables, so a dep_add item BETWEEN two rows this
// request creates on opposite planes is refused with everything else the
// request asked for.
Issue *Issue
// MetadataRefs splices resolved ids into this issue's metadata: each entry
// writes the id its Ref resolves to as the WHOLE VALUE of one top-level
// metadata key.
//
// IT IS THE ONE PLACE A KEY MAY REACH FORWARD, or name this item's own Key.
// A plan whose first step records the id of the last one it will spawn is
// the measured shape (a retry that re-mints a bead and stamps the original's
// id onto it), and the backward-only rule exists to make a TARGET row
// exist before an item touches it — which a metadata VALUE does not need.
// Every id is minted before any splice is applied, so the direction cannot
// matter here.
//
// IT IS A TYPED MAP, NOT TEMPLATING. A "${key}" placeholder inside a JSON
// string has no escape for a literal dollar-brace, collides with every
// other templating language a caller's own values might carry, and cannot
// be type-checked at all. This is one key, one whole value, one level deep.
//
// THE SPLICE IS A SECOND WRITE and it says so: the row is created first
// with the metadata the item spelled, and the resolved keys are written
// after every id exists, which records an update event on the spliced row.
// A caller reading the event stream sees a create and then an update, not
// one create carrying values nothing could have known yet.
MetadataRefs map[string]Ref
}
// UpdateItem patches one existing issue, under UpdateRequest's rules.
type UpdateItem struct {
// Target names the issue to patch and must resolve BACKWARD — see Ref.
Target Ref
// Patch is the edit, read exactly as UpdateRequest.Patch is — including
// that Patch.Labels is the whole LabelPatch, so a label REMOVAL is
// expressible here and not only an addition, and that Patch.Metadata keeps
// MetadataPatch's own distinction between a value stored as JSON null and
// one stored as the empty string. Neither is converted to the other on the
// way through.
Patch IssuePatch
// ExpectedVersion, ExpectedStatus and ExpectedAssignee are
// UpdateRequest's guards, and they are evaluated AS-MODIFIED: against the
// row as THIS REQUEST has already changed it at this item's position, not
// against the row as it was when the request began. An item that guards on
// what an earlier item of the same request just wrote is asking a coherent
// question and gets a coherent answer.
//
// A MISS REFUSES THE WHOLE REQUEST — the opposite of MetadataCAS, and
// deliberately. A compare-and-set is a retry loop's ordinary path, so a
// miss there is an answer; here it is one item of a graph the caller
// intended to land as a unit, and committing the rest would leave a shape
// nobody asked for. The refusal is ErrVersionMismatch, ErrStatusMismatch or
// ErrAssigneeMismatch, wrapped in an *ItemError naming the item.
//
// EXPECTEDVERSION ON A ROW THIS REQUEST HAS ALREADY TOUCHED IS
// ErrValidation, checked before anything is written. The token is
// server-minted and rewritten by the write, so a caller cannot know what it
// would be mid-request; any value it could send is either the pre-request
// token (which the guard would refuse) or a guess. Guarding on a row an
// earlier item created is the same case: the row did not exist when the
// caller composed the request. ExpectedStatus and ExpectedAssignee carry no
// such rule — a caller CAN know it wants the status its own earlier item
// set, and as-modified evaluation gives it exactly that.
//
// EVERY Expected* MEMBER IS AN EQUALITY, and that bounds what a caller can
// express with one. "Only if this issue is not closed" is a NEGATIVE
// predicate and none of these can spell it; the nearest thing is
// ExpectedStatus with the one status the row could otherwise hold, which is
// only equivalent where the row is PROVABLY binary — a bead whose status is
// open or closed and nothing else. Where a row can carry a third status
// that guard silently means something narrower than it reads, so check the
// claim before leaning on it rather than generalizing from the case that
// worked.
ExpectedVersion *int64
ExpectedStatus *Status
ExpectedAssignee *string
// ForceClosePolicy and ForceAssigneeTransfer are UpdateRequest's, per item,
// with UpdateRequest's rules — including that ForceAssigneeTransfer without
// a Patch.Assignee is invalid.
ForceClosePolicy bool
ForceAssigneeTransfer bool
}
// CloseItem closes one existing issue, under CloseRequest's rules.
type CloseItem struct {
// Target names the issue to close and must resolve BACKWARD — see Ref.
Target Ref
// Reason and Session are CloseRequest's, under its first-close-wins rule.
Reason string
Session string
// Force bypasses blocker and open-child close policy, and nothing else.
//
// CLOSE POLICY EVALUATES AT THIS ITEM, against the row as this request has
// already changed it — the same as-modified rule the update guards take. A
// LATER item that gives a closed parent an open child is NOT refused,
// because beads has no global invariant that a closed issue has no open
// children; the policy is a gate on the closing act, not a constraint the
// store maintains.
Force bool
// ExpectedVersion is CloseRequest's guard, evaluated as-modified and
// refusing the whole request on a miss. UpdateItem.ExpectedVersion's
// already-touched rule applies here identically.
//
// THERE IS NO ExpectedStatus HERE and its absence is a decision. A close is
// idempotent — re-closing a closed issue is Changed false — so a guard
// spelled to refuse an already-closed row is asking for a REFUSAL where
// this verb answers with a no-op, and that belongs on an update item whose
// Patch.Status crosses into the done category.
ExpectedVersion *int64
}
// DepAddItem asserts ONE dependency edge, under DependencyEditor's rules.
type DepAddItem struct {
// Source and Target are the edge's endpoints. Both must resolve BACKWARD —
// see Ref — and an edge from a row to itself is ErrSelfDependency.
//
// A TARGET MAY BE A ROW THIS DATABASE DOES NOT HOLD: an "external:"
// reference, or an id whose prefix names another repository. Both are
// stored as external references exactly as DependencyEditor stores them,
// so a plan naming work in a sibling rig lands its edge.
Source Ref
Target Ref
// Type is required and must be a usable value, checked for BEING a value —
// non-empty, within the column's length — and never for membership of the
// Dep* constants, which name an open set.
Type DependencyType
// Metadata is the edge's type-specific JSON blob, empty for the edge types
// that carry none.
//
// A WAITS-FOR EDGE IS NORMALIZED RATHER THAN STORED AS ASKED. An absent,
// blank or `{}` Metadata on a DepWaitsFor edge is written as
// {"gate":"all-children"}, because a stored waits-for row must be
// self-describing: readers predating the gate column's introduction do not
// default a missing gate, so an empty one is a row those readers get wrong.
// A Metadata that names a gate keeps it, and a gate that is neither
// "all-children" nor "any-children" is ErrValidation. Nothing else about
// this member is interpreted.
//
// THERE IS NO TYPED WaitsFor MEMBER, and that is the shape rather than an
// omission: every measured caller already carries the gate as metadata, the
// typed spelling lowers to these same bytes, and WaitsForMeta carries
// members — a spawner, an also-blocks flag — a two-field typed member could
// not express. One spelling, and it is this one.
Metadata string
}
// ApplyItem is ONE item of a batch: a kind plus exactly one member matching it.
//
// IT IS A TAGGED UNION RATHER THAN FOUR PARALLEL SLICES, because the request's
// ORDER is load-bearing and four slices cannot express one. It is a tagged
// union rather than an interface because the wire has to publish it, and a
// polymorphic wire member is a schema clients cannot generate a type from.
type ApplyItem struct {
// Kind selects which member below is read. It must be one of the four
// constants; an unknown kind is ErrValidation.
Kind ItemKind
// Create, Update, Close and DepAdd are the per-kind payloads. EXACTLY ONE
// must be non-nil and it must be the one Kind names: a kind with no payload
// is an item that does nothing, and a payload the kind does not name is an
// item whose two halves disagree. Both are ErrValidation.
Create *CreateItem
Update *UpdateItem
Close *CloseItem
DepAdd *DepAddItem
}
// ApplyBatchRequest describes one heterogeneous mutation of the graph.
//
// THE REQUEST IS THE TRANSACTION BOUNDARY, for the reason CreateBatchRequest
// gives, and here it is the whole point rather than an efficiency: a plan that
// creates three issues, wires them and closes the step that spawned them is ONE
// intent, and applying it as five calls leaves four intermediate states a
// crashing caller can strand.
type ApplyBatchRequest struct {
// Actor is the author of every item and must not be empty. It is
// attributed to the ONE history entry the request records, because a batch
// is one act by one caller.
Actor string
// Items are the items to apply, in the order they are to be applied. It
// must not be empty and must not exceed 100 entries.
//
// ORDER IS NEVER CHANGED. This role does not reorder parent-child edges
// ahead of blocking ones the way DependencyEditor does, and the reason is
// that the items are not all edges: a caller writing "clear the old
// blockers, then set the new ones" has expressed a sequence, and a role
// that reordered it would apply the clear after the set. What DependencyEditor
// buys with reordering, this role buys with the end gate below.
Items []ApplyItem
// Provenance labels the version-control history entry, under
// UpdateRequest.Provenance's rules: it changes how the entry READS, never
// whether one is recorded. Empty composes a default naming how many items
// of each kind landed and no ids — a batch can carry a hundred, and an
// entry naming them all is the diff written twice.
Provenance string
// ForceIDPrefix permits an explicit ID outside the configured prefix, for
// every create item, exactly as CreateBatchRequest.ForceIDPrefix does.
ForceIDPrefix bool
// SkipPerEdgeCycleCheck drops the PER-EDGE cycle probe for a caller wiring
// a large graph, exactly as AddDependenciesRequest.SkipPerEdgeCycleCheck
// does. It NEVER drops the whole-graph gate that runs once at the end, and
// it never drops the self-dependency refusal.
SkipPerEdgeCycleCheck bool
}
// ItemResult reports what ONE item did, at the index the item occupied.
type ItemResult struct {
// Kind echoes the item's kind, so a caller walking the results does not
// have to walk the request alongside them.
Kind ItemKind
// IssueID is the row the item acted on: the minted or explicit id for a
// create, the resolved target for an update or a close, and the edge's
// SOURCE for a dep_add.
IssueID string
// DependsOnID is the edge's target, and it is set for ItemDepAdd only.
DependsOnID string
// Changed reports whether this item persisted a semantic mutation. A
// create is always true. An update follows UpdateResult.Changed, a close
// follows CloseResult.Changed, and a dep_add is false for an idempotent
// re-add of an edge that already existed with the same type.
Changed bool
// RowVersion is the row's optimistic-concurrency token AFTER the item, and
// it is EQUALITY-ONLY: compare it, never order or interpret it. It is 0 for
// ItemDepAdd, which acts on no single row's version.
//
// ITS COVERAGE IS PARTIAL and the partiality is inherited rather than
// introduced: the token is rewritten by claim, close, unclaim and the
// generic update path, and NOT by the direct-update paths that rewrite text
// without touching it. A caller needing complete change detection combines
// it with updated_at, status and the label set. See types.Issue.RowVersion.
RowVersion int64
// Issue is a detached post-item snapshot with labels and dependency
// records, hydrated inside the transaction that applied the item — the
// snapshot CreateResult.Issue and UpdateResult.Issue describe. It is nil
// for ItemDepAdd, which acts on a graph rather than on a row.
//
// IT IS NOT ON THE WIRE, and the split is deliberate rather than an
// oversight. The Go contract carries it because every decorator over this
// role is written against result snapshots — the completion hooks hand a
// script the row it is being told about, and a wrapper that had to re-read
// each one would be N reads outside the transaction that wrote them. An
// HTTP client gets ids and a revision and reads what it wants back, and
// hooks never fire on that surface at all.
Issue *Issue
}
// ApplyBatchResult reports what the batch applied.
type ApplyBatchResult struct {
// Keys maps each create item's Key to the id it was bound to. It is the one
// fact the request cannot carry and every caller needs, and it carries only
// the keys the request NAMED — an unnamed create item is in Items and not
// here.
Keys map[string]string
// Items has exactly one entry per requested item, in REQUEST ORDER. No
// entry is ever missing for a successful call: a batch that could not apply
// every item applied none, so there is no index with nothing to put at it.
Items []ItemResult
}
// ItemError names the item a batch refusal came from and wraps the refusal.
//
// IT IS A TYPED ERROR WHERE BatchCreator PUT PROSE, and the divergence is
// justified rather than a preference. A create batch's items are homogeneous
// and positional, so an index in a message is enough to find one. These items
// are heterogeneous and may be NAMED, the wire has to publish which item
// refused as members a client can dispatch on, and a client cannot parse an
// index out of prose the implementations do not spell identically.
//
// It never appears WITH per-item outcomes, because there are none: an item that
// refused took the batch down with it, and every other item's outcome would be
// a statement about a transaction that rolled back.
type ItemError struct {
// Index is the item's position in ApplyBatchRequest.Items.
Index int
// Kind is that item's kind.
Kind ItemKind
// Key is the create item's own Key, or the Key the refused item's target
// ref named. It is empty when the item named nothing symbolically.
Key string
// IssueID is the id the item was acting on, when one was resolved before
// the refusal. It is empty when the refusal happened before resolution — a
// create whose id was never minted, or a ref that resolved to nothing.
IssueID string
// Err is the refusal itself, matchable with errors.Is through Unwrap.
Err error
}
// Error renders the item's position and the refusal.
func (e *ItemError) Error() string {
where := fmt.Sprintf("item %d (%s)", e.Index, e.Kind)
switch {
case e.Key != "" && e.IssueID != "":
where = fmt.Sprintf("%s key %q -> %s", where, e.Key, e.IssueID)
case e.Key != "":
where = fmt.Sprintf("%s key %q", where, e.Key)
case e.IssueID != "":
where = fmt.Sprintf("%s %s", where, e.IssueID)
}
return fmt.Sprintf("apply batch %s: %v", where, e.Err)
}
// Unwrap exposes the refusal, so errors.Is and errors.As reach the sentinel and
// the typed errors the underlying verbs raise.
func (e *ItemError) Unwrap() error { return e.Err }
// RefError reports a Ref this request cannot resolve, and it is a validation
// refusal: it is raised before anything is written.
type RefError struct {
// Index is the position of the item holding the bad ref.
Index int
// Member names WHICH ref of that item it was — "target", "source" or the
// metadata key whose ref failed — because an item may hold two.
Member string
// Key is the unresolvable key.
Key string
// DeclaredLater distinguishes the two diagnoses. True means the key IS
// declared in this request, but by an item at a LATER index, which is an
// ordering mistake; false means nothing in the request declares it, which
// is a typo or a missing item. A caller acts differently on each, and on
// the wire the two are told apart by whether the member is present.
DeclaredLater bool
}
// Error renders which ref failed and why.
func (e *RefError) Error() string {
if e.DeclaredLater {
return fmt.Sprintf("apply batch item %d: %s references key %q, which is declared later in the request; a key reaches backward only",
e.Index, e.Member, e.Key)
}
return fmt.Sprintf("apply batch item %d: %s references key %q, which no item in the request declares",
e.Index, e.Member, e.Key)
}
// Unwrap makes every unresolvable ref match ErrValidation, so a front door
// classifies it without knowing this type exists.
func (e *RefError) Unwrap() error { return ErrValidation }
// MaxApplyBatchItems is the largest request this role accepts. It is a FLAT
// bound rather than a cost model, and it is the bound the sibling batch roles
// already run under: a hundred creates and a hundred edges both land inside the
// server's ordinary request deadline today, so a per-item deadline extension
// would be new machinery answering a question nothing has asked.
const MaxApplyBatchItems = 100
// BatchApplier describes applying a HETEROGENEOUS list of graph mutations as
// ONE durable act, and — like Lifecycle, BatchCreator, BatchCloser and
// DependencyEditor — 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. BatchCreator creates N issues,
// BatchCloser closes N issues, DependencyEditor asserts N edges: each is one
// verb repeated, and a caller that needs two of them needs two transactions
// with a window between them. This role's unit is a PLAN — create these, wire
// them, close the step that spawned them — and the only way to express that
// today is a hand-composed transaction the caller opens itself, which is the
// composition every front door had to get right.
//
// IT IS ALL OR NOTHING, and unlike BatchCloser that is not a policy choice.
// Per-item outcomes are UNREPRESENTABLE here: an item whose target is a key an
// earlier item failed to create has no outcome to report, because the row it
// would have named does not exist. So there is one outcome and it is the
// request's.
//
// ORDER IS THE CONTRACT. Items apply in declaration order and are never
// reordered. What that costs is what DependencyEditor's parent-child-first pass
// buys: a blocking edge validated before the parent-child edge that makes it a
// hierarchy conflict. So this role runs a REAL END GATE instead — after every
// item has landed, it re-validates every scheduling edge the request added
// against the parent-child closure the whole request produced, and raises
// *DependencyHierarchyConflictError or ErrDependencyCycle from there.
// SkipPerEdgeCycleCheck never drops it.
//
// WHAT IS NOT AN ITEM, and why:
//
// - REOPEN. Nothing batches reopens, and an update item whose Patch.Status
// moves a row out of the done category covers the measured need.
// - DEP_REMOVE. A single removal is already idempotent, so composing it needs
// no transaction, and adding it would mean deciding what a remove-then-add
// of the same pair inside one request means.
// - A METADATA COMPARE-AND-SET. Its contract is that a mismatch is an ANSWER
// (MetadataCAS.CompareAndSetKey), and this role's contract is that a
// precondition miss refuses everything. One of the two would have to lie.
// The guard enters here as UpdateItem's Expected* members instead.
// - PARENT-ON-CREATE. One edge, one spelling: a parent is a dep_add item of
// type parent-child, so the ORDER of every edge in the request is total.
// - INLINE CREATE DEPENDENCIES, for the same reason.
//
// IT IS NOT IDEMPOTENT AND CARRIES NO IDEMPOTENCY KEY. Replaying a request
// applies it again — the creates mint new ids, the edges are idempotent, the
// closes are no-ops. That is deliberate: an idempotency RECORD is itself a
// write, so a caller that needs one makes it an ITEM of the batch, and the
// record then lands or rolls back with the work it describes. A key on the
// request would be a second, weaker mechanism for the same thing.
//
// EPHEMERALITY IS PER ITEM, exactly as it is for BatchCreator: one request may
// create durable issues and wisps together, and an edge BETWEEN the two planes
// whose ends this request creates cannot be written by it. HISTORY IS ONE ENTRY
// FOR THE REQUEST, attributed to Actor, and none at all when nothing durable
// landed — an all-wisp batch writes only to the dolt-ignored wisp tables, so an
// entry naming one would be the sync artifact ignoring them exists to prevent.
//
// THERE IS NO `bd` COMMAND BEHIND THIS ROLE, and that is a decision rather than
// an unfinished half. A plan is composed by a program — the thing that knows
// which step spawned which — and the shell spelling of one would be a file
// format: a second request grammar to version, to validate and to keep in step
// with the wire's. The measured callers already speak HTTP or hold the role
// directly. `bd create --file` and `bd dep add --file` remain the file-shaped
// front doors for the two homogeneous cases they already serve.
//
// 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 BatchApplier interface {
// ApplyBatch applies every item in order and commits them together.
// Items mirrors the request's items index for index, and Keys carries the
// id each named create was bound to.
//
// EVERY REFUSAL IS THE REQUEST'S. A refusal raised by an item arrives as an
// *ItemError naming that item's index, kind, key and resolved id, wrapping
// the verb's own typed refusal — so ErrAlreadyExists for an occupied id,
// ErrVersionMismatch, ErrStatusMismatch and ErrAssigneeMismatch for a
// precondition, *DependencyTypeConflictError, ErrDependencyCycle,
// *DependencyHierarchyConflictError and the endpoint-not-found errors for
// an edge, all still match errors.Is and errors.As through it.
//
// REFUSALS RAISED BEFORE ANY ITEM RUNS are the request's own and carry no
// item wrapper unless they name one: an empty Actor, an empty or
// over-length Items, an item whose Kind and payload disagree, a Ref with
// neither or both members set, an ExpectedVersion on a row an earlier item
// already touched. An unresolvable Ref is a *RefError, which names the item
// itself and matches ErrValidation.
//
// The END GATE runs after every item and refuses the whole request, so an
// edge that is legal on its own and illegal in the graph this request built
// is caught here and nowhere else.
ApplyBatch(ctx context.Context, req ApplyBatchRequest) (ApplyBatchResult, error)
}