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 } // 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) }