The transaction demarcation difference between @mutation and @service is undocumented

Bulk DML (INSERT/DELETE record carriers and payload-returning bulk UPDATE) goes through TypeFetcherGenerator.buildBulkRecordTwoStepFetcher (TypeFetcherGenerator.java:5329), which emits one dsl.transactionResult(tx -> { ... }) with the per-row loop inside it. Its comment states the rollback contract: "on any per-row throw …​ the transaction rolls back", so a batch is all-or-nothing.

Single-row two-step DML and the mutation @routine write path emit the same boundary through emitKeysTransaction (TypeFetcherGenerator.java:4569).

The empty-input short-circuit is the one arm that opens no transaction, because it runs no DML (TypeFetcherGenerator.java:5359).

All four service-backed root fetchers (query table, query record, mutation table, mutation record) share TypeFetcherGenerator.buildServiceFetcherCommon (TypeFetcherGenerator.java:1647). The body is a try, an optional dsl local, the invocation, and a catch (Exception e) routing into the error channel. No transaction appears, and the method’s own javadoc already states the contract in words: "the developer-supplied method owns the transaction scope" (TypeFetcherGenerator.java:1627).

The child service arms match. ServiceRowsFragments.delegateBody and ServiceRowsFragments.liftBody declare dsl only when the borrowed call shape needs one and then delegate.

docs/manual/reference/directives/mutation.adoc:5 states the generated write "runs inside a transaction". The @mutation half of the contract is published.

docs/manual/reference/directives/service.adoc:5 mentions transactions only as a reason to reach for @service ("multi-statement transactions"), which reads as if the framework provides one. The Constraints list (service.adoc:121-128) covers className, method, argMapping, mutual exclusion with @mutation, the @splitQuery requirement on non-root fields, and that DB-customisation directives are ignored. It says nothing about transactions.

docs/manual/how-to/error-channel.adoc Pitfalls (error-channel.adoc:134-142) is where an author reading about partial failure lands. It covers source order, description:, path:, pre-execution VALIDATION, cause-chain unwrap, redaction and carrier requirements. It does not say that an error payload from a @service field carries no rollback promise, while one from a DML @mutation carrier does.

docs/manual/how-to/handle-services.adoc has no transaction mention at all.

The single place the asymmetry is stated is docs/manual/how-to/mcp-agent-context.adoc:105, and it states it for the query path, as a caveat on the MCP execute rollback guarantee: "a query-path @service or @routine that writes runs outside it, exactly as it runs outside graphitron’s transaction demarcation in production." Right fact, wrong page, and scoped to the half the reporter did not hit.

docs/manual/reference/directives/service.adoc. A Constraints bullet, in the voice of the existing bullets: graphitron opens no transaction around a @service invocation, so the method owns its own boundaries, and a service whose contract is all-or-nothing must open one (ctx.transactionResult(...) on the injected DSLContext). Name the contrast explicitly, because the contrast is the footgun: a generated @mutation write, batch included, runs inside a transaction graphitron opens. Amend the page’s opening sentence too (service.adoc:5), whose "multi-statement transactions" currently reads as a promise that the framework supplies one; it should read as the reason you need the escape hatch. Add an xref to the error-channel pitfall.

docs/manual/how-to/error-channel.adoc. A Pitfalls bullet, since Pitfalls is where the partial-failure question is asked: an error payload from a @service field says the call failed, not that nothing was written, because graphitron opened no transaction around it. A DML @mutation carrier’s error payload does carry the rollback promise (buildBulkRecordTwoStepFetcher’s boundary), and a mutation `@routine write carries it for statement 1 only, the caveat routine.adoc:172 already publishes. State that a service that needs the promise must open the transaction itself.

docs/manual/reference/directives/mutation.adoc. One clause where the transaction is already claimed (mutation.adoc:5), pointing at the @service statement, so the two pages are reciprocal rather than one-directional.

Re-derive the wrap census from TypeFetcherGenerator before writing: dsl.transactionResult occurrences in main sources, and confirm no service arm has acquired one.

Confirm buildServiceFetcherCommon still carries the "developer-supplied method owns the transaction scope" sentence, and align the docs wording with it so the two do not drift. This is the one place a contributor-facing and an author-facing statement of the same contract will sit side by side.

mvn install -Plocal-db for the AsciiDoc render, since .adoc breakage fails CI. No test tier is in play: this item adds no behaviour and therefore no enforcer.

Any change to what is emitted, including the opt-in wrap (roadmap/service-opt-in-transaction-wrap.md).

Auto-wrapping a @service invocation, which the reporter argues against and we agree with; the reasoning is recorded in R722’s Position so it survives if this item ships alone.

The read-only enforcement question for delegated paths, owned by roadmap/query-read-only-enforcement.md.

Changing mcp-agent-context.adoc, whose statement of the fact is correct for the guarantee it is qualifying.

roadmap/service-opt-in-transaction-wrap.md (R722), the opt-in directive half of the same report. Independent: either can ship first.

roadmap/query-read-only-enforcement.md, which reasons about what graphitron may assume about a path it does not control (@routine, @service). Nearest neighbour for the framing, no overlap in the edits.

roadmap/upsert-docs-match-dispatch-refusal.md and roadmap/lookupkey-per-input-field-doc-claim.md, the two live instances of the same class: a manual page whose claim and the generator’s behaviour disagree. This one is an omission rather than a false claim, which is why it is a bullet rather than a rewrite.