git:20261003.e164ceb to git:20261004.7a4079a

- description: Use when implementing a CRUD or business operation or exposing it over HTTP — Mutation, DomainAction, [Endpoint], validation and authorization on an action, with Pragmatic.Actions and Pragmatic.Endpoints.

- All code under the boundary's namespace flows into it; sub-folders (`Orders/`, `Customers/`) create inferred sub-boundaries — the SG generates separate action interfaces (`ISalesOrdersActions`) composed into `ISalesActions`.

- // Items is the sub-boundary — the composed interface exposes each one as a property.

- | `I{Boundary}Actions` | the composed one — sub-boundaries are **properties**, not flattened methods |

- `I{Boundary}InternalActions` only — reachable from its own assembly, invisible to other modules.

- | `Internal = false` | public anyway — **this is how an endpoint-less operation is offered** |

- ⚠️ **If the operation is in a group, inject the group's twin — `I{Boundary}{Group}InternalActions` —

- want the call to be. A `[MessageHandler]` or a `[Job]` — the two callers that arrive with no principal —

- ⚠️ **`[Boundary(Visibility = Internal)]` is a different thing** — it hides the *whole boundary*, and a

- // You read the row through the repository — the query filters have already had their say.

- over HTTP as well, and a tracked entity does not cross a process boundary — publishing it there would

- the twin's type — so `boundary.Group.Operation(mutation, entity, ct)` and the ordinary

- twin — and "nothing to add" is stricter than it sounds: an ordinary update mutation supplies a

- which instance answers, not by which interface you inject — so injecting the public group interface

- a contract that already exists, it does not survive the boundary being split out, and — the part that

- bites — a hand-written service has no invoker, so it loses the permission check, validation, the unit

- The generated facade carries `[BoundaryActions<TBoundary>]`. You never write it — it is the marker that

- #### Writing across boundaries — PRAG0424

- `PRAG0424` warns when one invocation commits into more than one store — not on any cross-boundary

- call, which alone is atomic — and asks for a decision. Two ways to record it:

- request runs the registered undos in reverse. `T` is an ordinary scoped service — the generator

- registers it — implementing `ICompensates<TReturn>` (or `ICompensatesVoid`), and `PRAG0425` is an

- starts — and note Messaging has its own `[CompensateWith<TAction>]` for saga steps, which is the

- compensating step without a saga's durability.** It does not ask for a change — the decision was made

- and recorded, and warning twice would be nagging — it makes sure whoever reads the call knows what they

- owns the action; the caller holds an HTTP proxy. Only the host can see this — the module compiles the

- same whether it is hosted or called — so the host reports it as `PRAG1689`. Publish an event or model

- `[CompensableStep]`, and PRAG0424 goes quiet for callers that invoke those steps — per method, so a

- Custom logic (cross-field rules, domain methods): override `ApplyAsync` — the auto-mapping has **already** been applied before it runs.

- A **state transition** is declared, not written: `[TransitionsTo<TState>(target)]` and the generated invoker moves the entity (a mutation's own, or the one `[LoadEntity]` row of an action whose `[StateMachine<TState>]` matches), answering 409 — documented — when the state machine refuses:

- - `When = TransitionTiming.BeforeBody` (default): moved before the body, which sees the new state; a refusal skips the body. The only one for an action — it builds its response in the body.

- - `When = TransitionTiming.ByBody`: the body moves it — typically a domain method writing state plus who/when/why — and the invoker throws if a successful body left another state; `IsConditional = true` drops that check for a move made only sometimes.

- | Three mutations invoked as independent roots | **3** — one each |

- | Mutations invoked from inside an action of the **same** boundary | **1** — the action's |

- | A step in **another** boundary | **its own** — nobody else can save its `DbContext` |

- however the chain is written — through a service, a helper, a loop.

- thing to do and costs one transaction — see `CancelReservationsForPropertyAction`.

- steps may be **mutations, actions or void actions**, in any mix — each is a property typed as the step

- whose logic is a *query* sees the store as it was before the composite began — and reports success

- internal calls and their permissions are deliberately **not** re-checked — the composite is the

- **`PRAG0440`** refuses it — `[AllowAnonymous]` is how a composite says it is deliberately public.

- whose type is not itself a mutation or an action — `List<TMutation>`, an array, anything wrapping

- them — is skipped with no diagnostic (`PRAG0427` fires only at *zero* steps). A variable number of

- `JsonSerializerContext` — the path is AOT-safe. ⚠️ It nests the *mutation type*, not the

- `{Mutation}Body` its own endpoint uses, so what that body would have excluded — the implicit `Id` of

- an `Update` step — is on the wire.

- #### Raising a domain event — `[Raises<TEvent>]`

- ⚠️ **A parameter that matches nothing is passed as `default`** — `Guid.Empty`, or `null` — and the

- the single commit — all of them, in order. Measured across a boundary: N cancellations in one pass

- #### Composing, and saying how it commits — PRAG0428

- implied by the code. `PRAG0428` asks which one, and only of an action that actually composes — one that

- | `[CommitStrategy(CommitMode.Once)]` | One commit at the end. Atomic, but the steps cannot see each other — a query in step 2 runs against the store as it was before step 1. |

- so — the nearer declaration wins. A boundary *is* a transaction boundary, so this is a sentence it can

- to a boundary. The boundary is inferred from the entity behind an `IRepository` field — which an action

- ⚠️ `BatchContext` defers the unit of work you name — `new BatchContext(unitOfWork)` — and **performs no

- **What does not go in `Execute`** — each has a declared home, and writing it by hand is the mistake the

- | a second query for a navigation of a preloaded entity (`FindMembersOfAsync(teamId)` beside `[LoadEntity<Team>]`) | `[LoadEntity<Team>(nameof(Id), Include = "Members")]` — dotted paths, comma-separated; the key may live inside the request — `[LoadEntity<RoomType>("Request.RoomTypeId")]`, every segment a property;

- without it `_team.Members` is **empty** (no lazy loading); a path that names no navigation is **PRAG0453** — as is an `[EagerLoad]` path of a mutation (**PRAG0736** on a query), checked at build time and not emitted |

- | `var x = await repo.FirstOrDefaultAsync(Specs.ActiveWithNumber(Number)); if (x is null) return NotFound…` / `var xs = await repo.FindAsync(Specs.PendingOf(Id))` | `[LoadEntity<T>(Specification = nameof(TSpecifications.ActiveWithNumber))]` / `[LoadEntities<T>(Specification = …)]` — the rule's parameters bind **by name** to the operation's properties (`PendingOf(Guid id)` ← `Id`); single: none is 404; list: none is `[]`, or 404 with `RequireAny = true`. Not a specification of the entity **PRAG0454**, unbound parameter **PRAG0455**, key and rule together **PRAG0456** |

- | `var x = await repo.GetByNumberAsync(Number, ct); if (x is null) return NotFoundError…` — a row named by its domain key (a number, a code, a slug) | `[LoadEntity<T>(nameof(Number), By = nameof(T.Number))]` — read through the generated logic-key lookup (`{Entity}Specifications.GetBy{Key}Async`), same filters and tracking as by id; 404 carries the value. `By` not the entity's single-part `[LogicKey]` (or beside a `Specification`) **PRAG0460**, property of another type **PRAG0461** |

- | two `[LoadEntity]` of one entity, or two round trips for one table | give each a distinct `FieldName` — `[LoadEntity<Employee>(nameof(ManagerId), FieldName = "_manager")]`, `[LoadEntity<Employee>(nameof(DeputyId), FieldName = "_deputy")]`: read in **one** `WHERE Id IN (…)`, each field from it, 404 per missing key; different entities stay separate queries |

- | the row only has to exist — a foreign key in the body of a create: `[LoadEntity<T>]` for a row nobody reads, or the database's FK violation answering | `[RequireExists<T>(nameof(TeamId))]` — `ExistsAsync` before the body (same filters, an `EXISTS`, nothing loaded, no field), 404 naming the key; a null nullable key is not checked; on a mutation the key is still written. Key of another type **PRAG0411**; beside a `[LoadEntity]` of the same key **PRAG0462** (only the load runs) |

- | `var r = await _boundary.Group.GetX(new GetXQuery { A = A }, ct); if (r.IsFailure) return …; var data = r.Value;` — a declared query's answer inside an operation | `[LoadFrom<GetXQuery>] private IReadOnlyList<XDto> Data { get; set; } = [];` — the query's inputs bind **by name** from the operation's properties (a private computed one is fine: `private int Year => From.Year;`); run by the **query's own invoker** (its permission asked of the caller — the internal facade skips it); its failure is the operation's; the property is no input. Not the answer type **PRAG0458**, unbound required input **PRAG0459** |

- | `if (ManagerId is { } id) { var m = await repo.GetByIdAsync(id); … }` — load it only if given | `[LoadEntity<T>(nameof(ManagerId))]` on a `Guid? ManagerId`: field `T?`, nothing read when null, 404 when it names no row |

- | `if (To < From) return ValidationError.For(…)` — the shape of the input | validation attributes on the property (`[GreaterThanOrEqualProperty(nameof(From))]`, `[Range]`, a custom `ValidationAttribute`), message via `MessageKey = TKeys.…` |

- | a rule on an entity the operation loads (`[LoadEntity]`, `[LoadCurrentUser]`) — "hours only on a kind counted in hours" | `private ValidationError ValidateLoaded()` (or `Task<ValidationError> ValidateLoadedAsync(CancellationToken)`) on the operation: the invoker calls it right after the preload, before `Execute`, and a failure is the 422 with its fields. Not a validator that reads the row a second time. Another signature with that name is **PRAG0452** |

- | `Ensure.ThrowIfNull(found)` for a missing row | nothing — `Ensure.ThrowIf*` is for a broken invariant (a bug → exception → 500), never for a 404 or a 422 |

- | `private IClock _clock = null!;` only to read `_clock.UtcNow` / today | `[FromClock] public DateTimeOffset Now { get; private set; }` (or `DateOnly Today` → `IClock.UtcToday`), written by the invoker before `Execute`/`ApplyAsync` — the registered `IClock`, so a test that pins it pins this too |

- What stays in `Execute`: what only the domain can answer — its typed errors (overlap, overdraft,

- state) — and the writes. The signed-in user's entity is `[LoadCurrentUser]`; one member of it, as a

- (body, route, OpenAPI, boundary overload), and the invoker writes it after validation and authorization

- — so a validation attribute on it sees `default`. On a mutation it is also written to the entity when the

- dependency rule as an action — uninitialised private fields, injected by the generator — and you

- ⚠️ The example shows the mechanics, not the case: one row by id, as a DTO, **is** a declared query —

- `[Query<Order, OrderDto>(Single = true)]` with `[Filter(MapTo = "PersistenceId")] public Guid Id` — which

- **Which of the four to reach for** — getting this wrong is easy and shows up only when somebody reads

- | `[Query]` (Persistence) | filtering, sorting, paging a list — and a get-by-id, which is a query with `Single = true` (404 when nothing matches); see `pragmatic-use-persistence`. |

- ⚠️ **"My …" reads are queries too.** A read filtered by the caller — `GET api/me`, `GET api/me/balances`

- — is not a `DomainAction` that looks the caller up by hand and passes the value to a query. Declare

- there is no JSON body, and every unmarked scalar is bound from the **form** under its property name —

- - `[FromClaim]` vs `[FromCurrentUser]`: `[FromClaim]` is binding — the endpoint reads one raw claim into

- host adds it — `AddOutputCache` and `OutputCacheStep`, after authorization — when a module declares one,

- | `ValidationError` | 422 — the request was read and the rules refuse it |

- otherwise read by name only — a property value is not metadata, an attribute argument is, which is why

- `[ExposeEndpoint<TLoginAction>(HttpVerb.Post, "login")]` goes on the `[Module]` (not on the action). Its usual source is an action folded in by `[UsePackage<T>]`, which carries no `[Endpoint]` of its own; nothing restricts it to those, and a module's own action is mapped on the host root instead of the package prefix — see `pragmatic-use-composition`. `[ExposeEndpoint<TAction, TGroup>]` maps it inside an endpoint group instead (prefix and `ConfigureGroup` options); a `TGroup` that is not an `[EndpointGroup("…")]` is PRAG1682.

- **`[Autocomplete]` — search-as-you-type, from one property.**

- Generates `GET {entity}/autocomplete/{property}` returning `AutocompleteItem<TKey>` — the typed id

- plus the display text, serialized as **`value`**, not `label` — capped at `DefaultLimit` (10).

- declared and cannot turn off — the attribute has no knob for it. So it needs a host where somebody can

- **`[Sse]` — a feed the server pushes.**

- connection. Use it when the client must learn about a change it did not ask for — a board that

- refreshes itself — rather than polling.

- **`[McpTool]` — the same operation, callable by a model.**

- A host that references `Pragmatic.Endpoints.OpenApi` publishes it at `/openapi/v1.json` in Development without being asked (with Scalar at `/scalar` when `Scalar.AspNetCore` is referenced); `app.UseApiDocumentation()` publishes it in every environment. Do not write a startup step for it. It is an OpenAPI 3.1 document built at compile time from the same attributes the endpoints come from — operation ids, tags, parameters, request and response schemas, the error codes each operation can actually answer, and `summary` taken from `[ApiSummary]` or, failing that, from the XML doc comment above the class.

- The three JWT entry points — `UseJwtAuthentication`, `UseKeycloakAuthentication`, `UseOidcAuthentication` — already do it, with `OpenApiSecurityScheme.Bearer()`, and so does `UseDevelopmentIdentity`. An application that installs an authentication of its own calls `DescribeSecurityScheme` once per way in; one that must compute the scheme registers an `IOpenApiSecuritySchemeContributor`.

- ASP.NET's own document (`AddOpenApi()` + `MapOpenApi()`) lists the generated endpoints too, beside the ones the application maps by hand: the generated registration adds the description provider, nothing to call. `EnableOpenApi = false` takes them out of both documents. ⚠️ That document cannot hold a schema nesting past 64 levels — an operation answering with an **entity** reaches it through the navigations — so such a response is published there as JSON without a schema, with a warning naming it. Answer with a DTO.

- ⚠️ `servers` is absent by design — a document without it means "relative to where you fetched it", which is the right answer behind a gateway or a CDN, where the application cannot see its own public address.

- **Endpoint returns 404** — Are `[Boundary]` and `[Module]` present in the library? Is the library referenced by the host? Does `[Endpoint]` have the correct route?

- **Dependency is `null` at runtime** — Was it declared as an uninitialised private field (`= null!`)? An initialised field is not injected. Is the type registered in DI?

- **Async validation does not fire** — Is the `[Validator]` class in the same assembly as the operation (**PRAG0215** says so when it is not)? Does the operation carry `[Validate(Async = false)]`? Is the validator's `T` the operation type itself, and not its entity or a DTO?

- **`Invoker` not resolved** — Is `Pragmatic.SourceGenerator` referenced as an analyzer with `<IncludeAssets>analyzers; build; buildtransitive</IncludeAssets>`?

- Complete files in [`examples/`](examples/README.md), copied from the Invoicing example application — code

- that compiles and that `Invoicing.IntegrationTests` exercises — and kept identical to it by the gate: a