dynamic-consistency-boundaries

# Dynamic Consistency Boundaries (DCB) A reference skill for explaining DCB and mapping the concept onto Axon Framework 5 and the Axon Server DCB event store. Use it to answer "what / why / how" questions and to ground explanations in the real framework types and the public Axon Server gRPC API. ## What DCB is, in one paragraph Classic event sourcing fixes the consistency boundary to the aggregate: one aggregate maps to one event stream, and that stream is the unit of optimistic locking. DCB (introduced by Sara Pellegrini, "Killing the Aggregate") moves the boundary from the *stream* to a *set of events selected by a query*. Instead of "load aggregate X, append to stream X", you "source exactly the events that matter for this decision (selected by tags and event types), decide, then append on the condition that no new matching event appeared since you read." The boundary is defined per decision, dynamically, rather than baked into the storage layout. ## When to use this skill - The user asks what DCB is, why it exists, or how it differs from aggregates/streams/sagas. - The user is modeling an invariant that spans more than one entity (e.g. "a course holds at most N students" AND "a student joins at most M courses") and is unsure where the boundary goes. - The user asks how a specific Axon Framework 5 type or annotation relates to DCB. - The user asks what the Axon Server DCB event store can and cannot do. This skill is for **explaining and designing**. It is not a code generator; when a question is about concepts, prefer a clear explanation grounded in the references below over writing files. ## The mental model: source -> decide -> append DCB is optimistic concurrency control with a query-shaped lock: 1. **Source** the events matching a `criteria` (tags + event types). The store also returns a **consistency marker** -- the position of the head at read time. 2. **Decide**: fold those events into a decision model (current state) and run the business rule to produce new events. 3. **Append** the new events together with the *same criteria* and the marker. The store accepts the append only if no event matching the criteria was stored after the marker; otherwise it rejects and the command is retried. The criteria is both the *read filter* and the *write conflict definition*. Keep it as narrow as the invariant allows: too broad means false conflicts and contention; too narrow means a missed invariant. ## Terminology map: DCB <-> Axon Framework 5 <-> Axon Server | DCB concept | Axon Framework 5 | Axon Server (dcb.proto) | |---|---|---| | Tag (key/value classifier on an event) | `Tag.of(key, value)` (`org.axonframework.messaging.eventstreaming.Tag`); declaratively via `@EventTag` on event fields | `Tag { bytes key; bytes value; }` | | Criterion (AND of tags, restricted to event types) | `EventCriteria.havingTags(...).andBeingOneOfTypes(...)` | `TagsAndNamesCriterion { repeated string name; repeated Tag tag; }` | | Criteria (OR of criterions) | `EventCriteria.either(...)` / `.or(...)` | `repeated Criterion` | | The DCB query for a decision model | `@EventCriteriaBuilder` method on an `@EventSourcedEntity` | `criterion` list in `SourceEventsRequest` | | Decision model / current state | `@EventSourcedEntity` + `@EventSourcingHandler` evolve methods | (client-side fold; not a server concept) | | Read phase | `SourcingCondition` -> `EventStoreTransaction.source(...)` | `Source(SourceEventsRequest)` | | Consistency marker / head | `ConsistencyMarker` (e.g. `GlobalIndexConsistencyMarker`) | `consistency_marker` / `GetHead` | | Append phase with conflict check | `AppendCondition` (marker + criteria) -> `EventAppender.append(...)` | `Append(stream AppendEventsRequest)` with `ConsistencyCondition` | | Conflict rejected | append transaction rejected -> command retried | append fails the consistency condition | ## How to answer a DCB question 1. **Classify** the question: theory (why/what), Axon Framework usage (which type/annotation), Axon Server capability (what the API allows), or modeling ("where does the boundary go?"). 2. **Load the matching reference** (see below) and ground the answer in real types and method names -- do not invent API. When citing framework behavior, point at the real example files in `examples/university-java/`. 3. **For modeling questions**, work through the source -> decide -> append loop explicitly: what events does the rule depend on, what tags select them, what is the narrowest criteria, and what is the resulting conflict surface. 4. **Verify before asserting**: package names and signatures in the references reflect AF5 at write time; if a question hinges on an exact signature, open the file and confirm it still matches before stating it as fact. ## References Load the one that fits the question; do not read all of them up front. - `references/concepts.md` -- DCB theory: the problem with aggregate=stream, the three-phase optimistic-locking model, the full glossary (global sequence, head, tag, criterion, criteria, consistency marker), and the benefits/caveats. Sources: dcb.events and the "Dynamic Consistency Boundaries" article. - `references/axon-framework-api.md` -- the AF5 type map with fully-qualified names, the annotation-based flow (`@EventSourcedEntity`, `@EventCriteriaBuilder`, `@EventTag`, `@InjectEntity`, `EventAppender`), the lower-level contracts (`EventCriteria`, `Tag`, `SourcingCondition`, `AppendCondition`, `ConsistencyMarker`, `EventStoreTransaction`, `EventStorageEngine`), and how they compose. - `references/axon-server-api.md` -- the verbatim Axon Server DCB gRPC surface (services, RPCs, messages) and an explicit "what is possible / what is not" derived from it. - `references/examples.md` -- worked patterns: the course-subscription invariant (full code from the university example), plus canonical DCB.events patterns (unique username, sequential invoice number) modeled with Axon Framework criteria. ## Common misconceptions to correct - **"DCB removes consistency / is eventual consistency."** No. DCB gives *strong* consistency for the boundary you select per decision; it just stops forcing that boundary to equal an aggregate stream. - **"A tag is a stream."** No. Events are stored in one global log; tags are classifiers used to *select* events at query time. One event can carry several tags and thus participate in several boundaries. - **"The criteria filters on payload/metadata content."** No. Axon Server matches only on event **name** (type) and **tags**. Anything finer (counting, ranges, content predicates) is done by folding the sourced events client-side in the decision model. - **"Criteria semantics are all AND."** Within one criterion, tags are ANDed and types are an OR-set; across criterions the criteria is ORed. See the API references for the exact rule.