Why can a GraphQL mutation document leave a write half-applied?

## What "atomic" would have to mean here Atomicity means a group of writes either all take effect or none do. In a relational store that unit is a transaction; the boundary is explicit and the store enforces it. The question this leaf answers is which GraphQL construct, if any, carries that boundary. The answer is: **the root field, and only if its resolver opens one.** No larger unit exists. Not the document, not the operation, not the HTTP request. ## The unit of execution is the field A `mutation` operation's selection set is a list of **root fields** — fields declared on the mutation root type. The executor runs them one at a time, in the order the client wrote them, finishing each before starting the next. Each root field is served by an ordinary resolver function. Whatever transaction that function opens belongs to that function. Nothing outside opens one around the group, and nothing outside knows how to close one. Take a restaurant ordering graph and a document that closes out a table: ```graphql mutation CloseOutTable { applyDiscount(orderId: "ord_48213", code: "STAFF15") { totalCents } voidLine(orderLineId: "line_9127") { orderId } capturePayment(orderId: "ord_48213", amountCents: 4183) { receiptId } } ``` Three root fields, three resolvers, three separate transactions at best — and three separate commits. ## The failure `voidLine` loads the order line and only then checks whether this caller is allowed to void a line the kitchen has already fired: a permission check that ran too late, inside the resolver, after the discount write had committed. It raises. The executor records the error, produces `null` for that field, and carries on with the next root field. The response comes back looking like this: ```json { "data": { "applyDiscount": { "totalCents": 4183 }, "voidLine": null, "capturePayment": { "receiptId": "rcp_20714" } }, "errors": [ { "message": "Not permitted to void a fired line" } ] } ``` The discount applied. The void did not. The payment went through anyway. The guest is charged for a line that should have been removed, and the response that says so is a normal, successful GraphQL response. ## Why no server can fix this generically Three reasons, and they compound: * **The resolvers may not share a store.** One may write to a relational database, one may call a payments provider over the network, one may publish to an event backbone. There is no transaction that spans those. * **The executor does not know what an undo is.** It sees functions returning values. It has no inverse for "money captured". * **An "abort the rest" hook would not help.** By the time the second field fails, the first has already committed. Stopping the third does not restore the first. Some server implementations do offer a request-scoped transaction handed to every resolver through the execution context. That only works when every write in the document goes to the same store, and it converts the whole document into one long-running transaction, which is its own operational problem. It is a server implementation choice, not something the specification provides. ## Specified versus conventional Worth separating carefully, because interviewers probe it. **Specified:** the root fields of a mutation execute serially, in document order. **Not specified, and not mentioned anywhere:** transactions, rollback, compensation, or any notion of a document succeeding or failing as a whole. That is not an oversight to be patched. GraphQL describes how a request is resolved into a response; durability is the resolver's business, exactly as it is behind any other API style. ## The working rule Because the field is the only atomic unit on offer, put the atomic action inside one field. Name the field for the business action rather than for its steps: ```graphql type Mutation { closeOutTable(input: CloseOutTableInput!): CloseOutTablePayload! } ``` One field, one resolver, one transaction, one outcome. The client can no longer half-apply it by accident, because it can no longer split it. ## What a client must do in the meantime * Never read a successful HTTP exchange as proof that every write applied — half-applied documents come back looking healthy. * On a mutation, treat any entry in `errors` as "some part of this may not have happened", and inspect `data` to see which parts returned payloads. * Repair forward, not backward. There is no rollback to ask for; the only recovery is a compensating write — refund the capture, re-add the voided line — and compensating writes can themselves fail. * Prefer sending one root mutation field per request, so the unit the client retries is the same as the unit the server made atomic.