beads/issueops/batchcreator.go
Julian Knutsen 1f1e82ab08
fix(issueops): one default priority for every create path (#7426)
* fix(issueops): one create priority default; HTTP absent priority is P2

The CLI defaulted `bd create` to P2, but issues:create, issues:batchCreate
and batch:apply create items left Issue.Priority at 0 when `priority` was
absent, so a gc/curl create stored P0 (critical) against the spec's "absent
means the default".

The default now lives in one place, the shared create preparation
(PreparePublicCreateRequest), behind a presence flag because Issue.Priority's
zero value is P0:
- issueops.CreateRequest.DefaultPriority, BatchCreateItem.DefaultPriority and
  CreateItem.DefaultPriority ask for issueops.DefaultCreatePriority (2);
  setting it with a non-zero priority is ErrValidation
  (ValidateCreatePriority, shared with the HTTP client);
- every Lifecycle.Create, BatchCreator and BatchApplier leg (dolt, embedded,
  uow) reaches it; CloneCreateBatchRequest now keeps scalar item members;
- the three handlers set the flag for an absent member and never make up 0;
  the HTTP client omits `priority` for it (wirePriority) only when the
  server advertises the new additive issues.create.defaultPriority token,
  read from the cached handshake before the dial; an older server reads an
  absent priority as P0, so the client sends DefaultCreatePriority (2)
  explicitly to it (pinCreateDefaultPriority). An explicit 0 is still sent;
- `bd create` without --priority, `bd create --graph` nodes without priority
  and `bd create --file` templates without ### Priority rely on the flag; the
  flag's displayed default and the dry-run previews read the library
  constant. CLI output is byte-identical (checked against origin/main).

Spec: the three priority descriptions now say the create default is P2 on
a server advertising issues.create.defaultPriority (apigen regenerated); the
wireshape golden already had priority optional, so no wire-shape change.

Conformance: RunLifecycleCreateAppliesTheDefaultPriority,
RunBatchCreatorAppliesTheDefaultPriority and
RunBatchApplyAppliesTheDefaultPriority on dolt, embedded, uow and http, plus
handler and client encoding tests, and
TestCreateSendsTheDefaultPriorityToAServerThatPredatesIt (new client,
handshake without the token: all three create roles send 2).

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

* fix(issueops): apply review fixups for the default create priority (bd-kb61wg)

Apply the minor and nit findings from the review of #7426:

- CHANGELOG: tell out-of-tree storage backends they must honor
  DefaultPriority (store issueops.DefaultCreatePriority, refuse it with a
  non-zero priority as ErrValidation) and which conformance cases check
  it; scope "CLI output is unchanged" to the in-tree backends.
- bd create --file: pin the default-priority path. The e2e test asserts
  the printed priorities, and a buildMarkdownBatchRequest unit test pins
  the flag and priority for an absent, a 0 and a 1 `### Priority`.
  Deleting `DefaultPriority: !template.PrioritySet` now fails both.
- bd create --file: warn on stderr about a `### Priority` that does not
  parse, as the `### Type` case already does, instead of dropping it
  silently.
- httpclient: document pinCreateDefaultPriority's same-build assumption
  (the handshake is cached per Store, so a stale one is silent here), and
  test its no-context and failed-handshake branches on all three roles.
- Formula steps, `bd q` and `bd todo add` spell
  issueops.DefaultCreatePriority instead of the literal 2.
- Conformance: the batch-creator and batch-apply default-priority cases
  also pin DefaultPriority with a non-zero priority as ErrValidation with
  nothing written.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(issueops): mark the out-of-tree DefaultPriority change BREAKING (bd-0tcn1o)

Apply the minor findings from the relaunch review of #7426:

- CHANGELOG: move the obligation on out-of-tree storage backends out of
  the `### Fixed` entry into its own `### Changed` entry, led by
  "BREAKING (out-of-tree storage backends)" as the close-guard change
  and the earlier out-of-tree contract changes are; RELEASING.md asks
  breaking changes to carry their migration. The entry says what such a
  backend used to receive from `bd create`, `--graph` and `--file`
  (priority 2), what it receives now (priority 0 with DefaultPriority
  set), the migration, and the conformance cases that check it. The
  `### Fixed` entry keeps the HTTP P2 fix, points at the new entry, and
  names the stale-handshake residual that only a code comment named: a
  create that lands on an older build behind the same URL still stores
  P0.
- bd cook: the proto root, the gate issue and the cooked formula root
  spell issueops.DefaultCreatePriority instead of the literal 2, as the
  formula steps in the same file already do. No behavior change.

Not taken:
- The literal 2s in create_form.go, gate.go and linear.go, and the
  "default 2" in todo.go's --priority help: explicit P2s outside the
  migrated paths (the help string also feeds the generated CLI
  reference). Left for a follow-up sweep.
- Reusing in.priorityDefault in the direct bd create route: that route
  builds no createInput (gatherCreateInput runs only on the proxied and
  --file routes, and each returns), so there is nothing to reuse.
- A member-level range check in the single-create HTTP decode, as the
  batch shapes have: the asymmetry predates this PR, and the role still
  refuses an out-of-range priority on all three shapes.

Agent-Signature: claude-code-claude-opus-5-5-max on behalf of Julian Knutsen
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 01:37:27 +00:00

171 lines
9.4 KiB
Go

package issueops
import "context"
// BatchCreateItem is one issue a batch create asks for, with the edges that
// issue is created carrying.
//
// It is the per-item HALF of CreateRequest: the fields that describe ONE issue
// live here and the ones that describe the whole act — the actor, the history
// label, the prefix override — live on the request, exactly as BatchCloseItem
// splits away from CloseRequest. Nothing here is a second spelling of a
// CreateRequest field; an item field means what the CreateRequest field of the
// same name means, and where this doc says nothing that is where to read.
type BatchCreateItem struct {
// Issue is the issue to create and must not be nil. It is read under
// CreateRequest.Issue's rules WITHOUT EXCEPTION: the same fields are
// accepted, the same derived ones ignored, Labels are authoritative, and
// Issue.Comments and Issue.Dependencies must be empty because edges are
// supplied through the item's own Dependencies below.
//
// AN EXPLICIT ID IS CREATE-ONLY, as it is for Lifecycle.Create: an id that
// already names a row is ErrAlreadyExists and never a silent full-row
// upsert. It refuses the WHOLE BATCH rather than that item, because this
// role is all or nothing (see BatchCreator). The documented upsert surface
// is `bd import`.
//
// 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 an edge BETWEEN the two buckets cannot be
// written by the batch that creates both of its ends; a request that asks
// for one is refused with everything else it asked for.
Issue *Issue
// Dependencies is the authoritative set of explicit edges created with this
// item, under CreateDependency's rules.
//
// A TARGET MAY BE AN EARLIER ITEM OF THE SAME BATCH, named by an id that
// earlier item spelled for itself. That is a capability the batch has and a
// loop over Lifecycle.Create does not, and it is EARLIER rather than any
// item on purpose: one implementation writes every row before any edge and
// could resolve a forward reference too, the other creates item by item and
// cannot, so a forward reference is left unpromised rather than promised
// where only some backends keep it. An item whose id is generated cannot be
// referred to at all, because nothing can name an id that does not exist
// yet.
Dependencies []CreateDependency
// DefaultPriority is CreateRequest.DefaultPriority for this item.
DefaultPriority bool
}
// CreateBatchRequest describes one creation of many issues.
//
// THE REQUEST IS THE TRANSACTION BOUNDARY, for the reason CloseBatchRequest
// gives: creating N issues one call at a time is N transactions and N history
// entries, and the caller that wants them to land together has no way to say
// so. Nothing here exposes begin or commit and there is no handle to hold open,
// so the boundary cannot be got wrong — it is wherever the request ends.
type CreateBatchRequest struct {
// Actor is the creator and must not be empty. It is attributed to every
// item, because a batch is one act by one caller: an item carrying its own
// actor would be a second creator inside a history entry that names one.
Actor string
// Items are the issues to create, in the order the caller asked for them.
// It must not be empty, as CloseBatchRequest.Items must not: a write batch
// that writes nothing is a caller bug rather than a degenerate answer,
// which is where it differs from the read batches that answer nothing for
// no anchors.
//
// Every item appears in CreateBatchResult.Issues at the same index.
Items []BatchCreateItem
// Provenance labels the version-control history entry this batch records,
// naming the surface the create came from. Empty selects the
// implementation's default label.
//
// It NEVER changes WHETHER history is recorded — only how the entry reads —
// which is UpdateRequest.Provenance's rule, inherited whole. It is HERE
// rather than absent, unlike on CreateRequest, because the surface this
// role serves has always named its source file in the entry
// (`bd: create 3 issue(s) from plan.md`) and a label composed from the
// result could not spell a file the result does not carry.
Provenance string
// ForceIDPrefix permits an explicit ID outside the configured prefix, for
// every item. It is request-wide because the flag that spells it is, and
// because writing outside the workspace's prefix is one decision a caller
// makes about a whole file rather than a property of one row in it.
ForceIDPrefix bool
}
// CreateBatchResult reports what the batch created.
type CreateBatchResult struct {
// Issues has exactly one entry per requested item, in REQUEST ORDER, each a
// detached post-create snapshot with labels and dependency records — the
// snapshot CreateResult.Issue describes, minus comments, which a create
// batch has no way to supply and therefore never has any.
//
// No entry is ever nil for a successful call: a batch that could not create
// every item created none, so there is no index with nothing to put at it.
//
// It is where a caller reads the GENERATED IDS, which is the one fact the
// request cannot carry and every front door needs.
Issues []*Issue
}
// BatchCreator describes creating many issues as ONE durable act: the write
// side of `bd create --file`, and — like Lifecycle, 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 ALL OR NOTHING, and that is the OPPOSITE of BatchCloser on purpose. A
// batch close skips the id it cannot close and commits the survivors, because
// the work was already done and the batch is only recording it: an agent that
// finished four of five steps and mistyped the fifth keeps the four. Nothing
// has happened yet when a create batch refuses an item, so there are no
// survivors to keep, and half a file is an outcome with no good next move — the
// caller cannot re-run the file without duplicating what landed, and cannot
// learn which half landed without reading the store. The two batch roles
// therefore make opposite promises about partial failure, and each states its
// own so neither is read as the other's default.
//
// WHAT ATOMIC MEANS HERE is everything a caller can observe: one transaction,
// every item or none, at most one history entry, and NO history entry when
// nothing durable landed. An all-ephemeral batch writes only to the
// dolt-ignored wisp tables — ignored precisely so ephemeral work never ships —
// so a durable entry naming one would be the sync artifact ignoring them exists
// to prevent. That is BatchCloser's rule for wisps and it is the same rule
// here.
//
// EVERY REQUESTED EDGE IS WRITTEN OR THE BATCH REFUSES. There is no per-edge
// report and no partial graph, for the reason Lifecycle.Create gives for
// refusing the same case: a create that reported success having silently
// dropped an edge is data loss, because the caller has no way to learn the
// relationship is missing. A target that names no row in this database is
// ErrValidation wrapping ErrNotFound and nothing is created.
//
// WHAT IS NOT "NAMING NO ROW" is a target this database was never going to
// hold: an `external:` reference, or an id whose prefix belongs to ANOTHER
// repository. DependencyEditor accepts both and stores them as external
// references, and so does this role — a plan naming work in a sibling rig
// creates its issues and its edges, exactly as it does one at a time.
//
// `bd create --graph` IS NOT THIS ROLE. A graph plan is an UPSERT over a
// declared shape and may adopt rows that already exist, where every item here
// is a create that refuses an occupied id. Two contracts, so two roles, and the
// second one is not written yet.
//
// Implementations never mutate caller-owned request values, snapshot the
// request at method entry, and apply validation and normalization only to
// attempt-local clones. CreateBatchRequest travels by value, so Items and the
// issues it points at are what a body could otherwise write through to the
// caller — in particular the ID an implementation assigns, which must land on
// the result and not on the caller's issue. Deterministic request-validation
// failures match ErrValidation and leave persistent state unchanged.
type BatchCreator interface {
// CreateBatch creates every item and commits them together. Issues mirrors
// Items index for index.
//
// EVERY REFUSAL IS THE REQUEST'S, never an item's: there is no per-item
// outcome to put one in, because an item that refused took the batch down
// with it. The refusals are the ones Lifecycle.Create raises, in the same
// typed vocabulary — ErrValidation for a request or content rule,
// ErrAlreadyExists for an occupied explicit id, ErrValidation wrapping
// ErrNotFound for an edge whose target is not there — so a caller
// classifies them with errors.Is rather than by reading prose.
//
// WHICH item caused it is in the MESSAGE and nowhere else, deliberately: a
// structured per-item error would be result shape for an outcome that does
// not exist. The message is prose and is not a promise — it names the
// offending item's position, or the value that was refused, or both, and
// the implementations do not spell it identically. A caller that needs to
// act per item sends one request per item.
CreateBatch(ctx context.Context, req CreateBatchRequest) (CreateBatchResult, error)
}