Cratis Blog

Questions and a decision guide · Decisions that hold, Part 11

Tue, 17 Nov 2026 09:00:00 GMT

This series started from a bug most applications have and few tests find: a rule reads state, decides, and writes, and two requests can both pass the check before either writes. Parts 2 to 6 made one tool dependable for that, Arc’s read protection, which turns a read model in a command into a guard on the command’s append. Parts 7 to 10 covered the rules that need something else, the same guard without Arc, how to test it, and how a guard is built. This last part is the page to come back to: a decision guide by the shape of the rule, short answers to the questions the series raised, and where each one is explained.

The answers assume read protection is On, as in new Cratis applications (Part 2), unless they say otherwise. Read protection, command scenarios and the Arc analyzers are part of Arc for .NET.

The decision guide

Start from the rule, not from the tool. Ask these questions in order, and the first yes picks the mechanism:

Ask in order. A guarded read is what is left when none of the other shapes fits.

The table has more rows than the questions, because some rules have a shape the questions don’t separate. “Never rely on” is a choice that can fail silently: the command succeeds and the rule is broken. “Too much” is a choice that works and costs more than the rule needs.

Rule shape	Use	Never rely on	Too much	Part
A unique value (email, user name)	A constraint: `[Unique]` on the event property	A validator that asks “does it exist?”	Read protection only for uniqueness	7
Created once (one library card per member)	`[Unique]` on the event type	An “exists” check in a validator	A read over the whole history	7
State on one key (stock, a count, a status)	A read-model parameter under `On`, the rule in a `CommandValidator<T>`	The same validator under `Off` or `Measure`	A constraint: it can’t count	2
A rule over two keys (loans and stock)	Two read-model parameters with `[LookUpBy]`, one event per key in one append	Two aggregates, each guarding only its own source	One model that folds both keys: it is refused	3
One stream of an entity (a month, a period)	A per-stream read model, or a stream decision for “has it happened?”	An injected read of the stream under `Off`	A whole-source read when one period matters	4
An editing conflict	An explicit scope with the revision the client saw	`concurrency: true` alone	A read model that folds what a revision tells you	7
Rich behaviour on one entity	An aggregate root that returns `Commit()`	Ignoring the result of `Commit()`	A read model for each invariant	7
A rare, repairable violation	The default append and a reactor that repairs	The repair running before the harm	Any guard	7
A hint on screen (“no copies left”)	A query, or `[Unprotected("why")]` on the read	The hint as the rule	A guarded read	5, 7
External data (a price, a tax rate)	Fetch it in `Provide()`; the guard covers your own state	Assuming the external value is guarded	Guarding state you don’t decide from	7
A hot key with a long history	A key per period, order or booking, or a constraint	A guarded read on a key that never stops growing	A flat model over years of events	2
Code without Arc (an endpoint, a worker)	A decision read passed to the append, or enrolled in the request’s unit of work	A plain `Append` beside it, or an unchecked result	Read protection on a unit of work for one guarded append	8

Arc’s Choosing how a command’s rule holds has the same matrix, the flowchart and what each mechanism guards. Chronicle’s Choosing how a rule holds makes the same choice from the client’s side, without Arc.

Questions about read protection

Does a validator that reads a read model make my rule hold?

Under Off, the default, no. The validator gets a snapshot, a materialized model can lag behind the log as well, and nothing ties the commit to what the validator saw. Under On, yes, within the guard: the read is folded fresh from the event log, and the commit is refused if an event of the model’s types arrives for that key after the position Chronicle noted before the fold. It can’t make a value unique across keys, and it doesn’t see what’s listed under what a guard doesn’t cover. See Part 2 and Arc’s Getting started.

How do I turn it on, and why isn’t it on by default?

One property in the project that contains the commands, or in a Directory.Build.props that covers several:

<PropertyGroup>
    <CratisReadProtection>On</CratisReadProtection>
</PropertyGroup>

It’s compiled into the assembly, and any value other than Off, Measure or On fails the build. [ReadProtection(ReadProtectionMode.On)] turns on one command. New applications from the Cratis templates have On already. Arc’s own default is Off, because a protected command fails closed: commands that read through IReadModels or append as a side effect would start failing. The next major version of Arc makes On the default (Cratis/Arc#3255). You can then turn it off for one command with [ReadProtection(ReadProtectionMode.Off)] or [Unprotected("why")], for one read with [Unprotected("why")], and for a project with <CratisReadProtection>Off</CratisReadProtection>. See Part 2 and Part 6.

Do I still need `[ProtectedDecision]` and `DecisionRead<T>`?

Under On you don’t need [ProtectedDecision] or DecisionRead<T>; they keep working. A plain read-model parameter is guarded, and so are a validator’s constructor parameters. Outside On, [ProtectedDecision] is how one command opts in on its own, and Arc runs such a command’s validator only if it has no constructor parameters. See Part 2 and Arc’s FAQ.

Does a guard lock anything, and what does it cost?

Nothing is locked and nothing waits. Two commands on the same key both run to the commit, and the commit is where one of them may be refused. The cost is in the read: a fresh fold of the key’s history of the model’s event types on every guarded read, two tail reads per attempt, and up to three attempts if events arrive while it folds. Nothing caches the result between commands, and the kernel serves the folds through one projection per model type, shared by every key and tenant, so heavy use of one model type queues across keys. No benchmark of Arc’s read protection is published; Chronicle’s costs and limits page has one decision-read measurement with its environment. Keep guarded models flat and keys short-lived. See Part 2.

What does a guard not cover?

A guard covers one key’s history, for the event types the model folds, after the position noted before the read. Outside it:

Revise and Redact between the read and the commit. They don’t move the tail, so they aren’t detected, and Chronicle refuses them inside a protected invocation.
Other event sequences, services, HTTP calls and other databases.
A projection definition changed by another process.
Reads marked [Unprotected("why")], and every read under Off or Measure.
New keys a rule counts over. Put such a count on one key that receives every fact.
A writer that decides without a guard. Your guard detects its event if it lands in your window, but its own decision is unguarded.

See Part 2, Part 3 and Arc’s How it works.

Can a caller skip my validator?

Under Off and Measure, yes. A model-bound command honours the caller’s X-Allowed-Severity, and a caller that sends 3 (Error) removes the Error results of your validators and Provide(), unless the command declares [BlockOnValidationSeverity]. From Arc 22.108.0, a command declared On, in the project or on the command, has an Error floor: Error and Unknown results block whatever the caller sends, and the caller can still let warnings through. The floor follows the declared mode, so a runtime cap doesn’t remove it, and a command’s own [BlockOnValidationSeverity] takes precedence. No threshold turns a ReadChanged from the commit into a success. See Part 5 and Arc’s severity filtering.

Is Measure a safe place to stay?

No. Measure returns what Off returns, with the same status codes, and reports what On would guard, refuse or reject through the counter cratis.arc.read_protection.events on the meter Cratis.Arc.ReadProtection, a span event and log warnings. An application in Measure is exactly as unguarded as one in Off. The measurement is best effort and the race scan is sampled, so a quiet report is not evidence that nothing would change. Use it to find what to fix, then switch a project to On. To back out after a deployment, ReadProtection:MaximumMode lowers the mode at run time and never raises it. See Part 6.

Questions about refusals

Does Arc retry a command that conflicted?

No. Arc and Chronicle do not re-run the command. A lost race returns a 400 with the reason concurrencyViolation, the detail ReadChanged and a state of { readModel, key }, and nothing from the command is written. The fold makes up to three attempts while it reads, before your code decides; after that, a conflict ends the command. The caller reads again and decides again. Resubmitting the same decision in a loop would undo the point of the guard. The message doesn’t name the event that conflicted. See Part 2 and Part 5.

What should a UI do with `ReadChanged` and `ReadIncomplete`?

Both are 400s with the reason concurrencyViolation, and both mean nothing was written. ReadChanged means something the command read changed before the commit: reload what the user decided from and let them decide again. ReadIncomplete means the fold didn’t reach that key’s latest events in three attempts: submitting again is safe. Branch on reason; reasonDetail is a plain string with no TypeScript constant, the message is developer text, and neither result names a field. See Part 5 and Arc’s command result page.

Why does my command return a `500` under On?

Usually the command reads or appends something Arc can’t put under a guard. The common causes are a read model with joins, children or a key taken from an event property, a filtered reducer or one with dependencies, a read through IReadModels or the event log inside the command, an immediate IEventLog.Append, an aggregate and a read of the same source, or a validator registered by hand as scoped, as a singleton, or through a factory or an instance (a plain transient registration is fine). Part 5 lists the rest. Nothing is written, and submitting again fails the same way, so the code has to change. Outside Development, the message is replaced by a generic one unless ArcOptions.ExposeExceptionDetails is set; find the full text in the server log by the result’s correlationId. ARCCHR0024, ARCCHR0028 and ARCCHR0033 report most of these at build time. See Part 5 and Arc’s refusals.

Why was my reducer refused?

Chronicle can’t replay a reducer exactly when it filters its events or depends on a service. A reducer is admitted when it has no event filter and no constructor dependencies other than ILogger<T>. Remove the filter or the dependencies, read a projection of the same events, or mark the read [Unprotected("why")] if it’s only context. See Part 5 and Chronicle’s decision reads.

What if my read model is keyed by an event property?

It can’t be guarded. Its events live on other event sources, one per book for example, and a guard watches one source. ARCCHR0024 warns at build time, and under On the command is refused with a 500. Append a fact to the entity the model is keyed by, so the command writes one event to each entity in one append, or use a constraint. [Unprotected("why")] only turns the read back into a snapshot. See Part 3.

Questions about choosing a mechanism

How do I make a value unique?

With a constraint on the event: [Unique] on a property for a value, on the event type for “once per entity”. The kernel checks it inside every append, from every writer and every client. A validator can’t do it, and neither can read protection: two members registering the same email are two different keys, and no read of one key sees the other. A constraint is checked per event sequence and per namespace, and it can’t count. See Part 7 and Chronicle’s constraints.

How do I enforce a rule over two entities?

Take one read model per entity in the validator, each with [LookUpBy(nameof(...))] naming the command property that holds its key, and return one EventForEventSourceId per entity from Handle(). Each read guards its own key, both guards are checked with the one atomic append, and if either was violated, neither event is written. Use a separate event type for each entity: a model folds every event of its types, wherever it was appended. See Part 3.

What’s the difference between a per-stream read model and a stream decision?

A per-stream read model folds state, a total or a status, from one stream of an entity, such as one account’s Transactions for 2026-10. Declare [EventStream<TSource>("Transactions")] on the model, route the command with [EventSource<TSource>("Transactions")] and [EventStreamId("{Month}")], and the guard covers the model’s event types in that stream. A stream decision reads the raw events of the command’s stream and answers “has this happened?”. Any event in that stream after the read conflicts, and the whole stream crosses the wire, so it suits short streams. Use one of them in a command, not both. See Part 4 and Arc’s stream decisions.

Does an event source definition, or `concurrency: true`, make my rule hold?

No. Both narrow the default append check, and that check reads the event source’s tail when the events are appended, after the validator and Handle() have decided. It can’t tie the commit to what the decision read. For that you need a constraint, a guarded read, a stream decision, an aggregate or an explicit scope. See Part 7 and Arc’s FAQ.

Why did my command fail when nothing it decided on changed?

The guard is wider than the read you were thinking of. Reads of one event source merge into one guard over the event types of all of them, so a retitle refuses a borrow whose validator also read a title model of the same book. A whole-source read beside a per-stream read widens the guard to every month, reading two months of one stream drops the stream id, and a Concurrency declared on the definition with the event source id but not both stream dimensions widens it the same way. A wider guard still includes everything the narrower one watched; it adds conflicts and doesn’t drop any. Mark reads you only use as context [Unprotected("why")], and take only the per-stream model when the rule is about one period. ARCCHR0038 reports the combinations it can see. See Part 4, Part 5 and Part 10.

Questions about Chronicle, other languages and DCB

Can I use this from Kotlin, Java, TypeScript or Elixir?

Arc’s read protection, command scenarios and analyzers are part of Arc for .NET. Chronicle’s decision reads, the mechanism underneath, are in the .NET and Elixir clients. Constraints and concurrency scopes are in all five Chronicle clients, and the kernel checks a constraint on every append, whichever client sent it. See Part 7 and Part 8.

Can I get the same guard without Arc?

Yes. In the .NET client, GetDecisionReads().GetDetached<T>(key) notes the position and folds the key, and AppendMany(…, guardedBy: [read]) appends with that read as the condition. Check IsSuccess, and GetDecisionConflicts to tell a lost race from a constraint violation: a conflict is a result, not an exception. Inside an ASP.NET Core request, IDecisionReads.Get<T> enrolls the read in the request’s unit of work; stage events with Transactional.Append and commit with IUnitOfWorkCompletionFeature.CommitAsync() before you respond, because the middleware otherwise commits after the response and reports nothing. In Elixir, read with DecisionReads.get inside Chronicle.decide. See Part 8 and Chronicle’s decision reads.

Is this the Dynamic Consistency Boundary?

Chronicle supports DCB-style decision models and append conditions within its event-source model. It is not a DCB event store. Each event belongs to one event source, and the event source ID, event source type, event stream type and event stream ID play the part of tags, with one value each. Custom tags take no part in consistency, and a fact about two entities is two events in one atomic append. See Part 8, Einar’s DCB, but not DCB and DCB in Chronicle.

Questions about testing and seeing the guard

How do I test that a rule holds?

Put a competing write between the command’s read and its commit. In Arc, new CommandScenario<T>(), seed events with Given.ForEventSource(id).Events(...), queue the competitor with AppendConcurrently(id, ...), and assert ShouldHaveValidationErrorBecauseOf(ValidationResultReason.ConcurrencyViolation) and an empty AppendedEvents. The scenario runs the command in the mode it declares, in its project or on the command, so under Off or Measure the test fails, which is what it’s for. Seed events rather than pinned read models: a guarded read never sees a pinned instance. See Part 9 and Arc’s Test the race.

How do I see what a commit guarded?

In code that calls Chronicle directly with read protection enforced on the unit of work, call IUnitOfWork.GetAppendConditions() after the commit. It returns one condition per guarded event source, with its event types, stream values, position and the origins behind it. Assert on the origins and the number of conditions rather than on their text. See Part 10 and Chronicle’s How guards are derived.

The series

The bug you never see. Check-then-act decisions, why two requests can both pass the check, and what the database defaults do about it.
The read model said yes. A command that checks a read model and then appends, and the project setting that makes the check hold at the append.
One rule, two entities, one append. Two reads, one fact for each entity, and one atomic append.
A limit for one account and one month. Guarding a decision on one stream, so last month’s activity doesn’t conflict with today’s.
When Arc says no. The two kinds of refusal, what each means, and what the caller and the UI should do.
Turning read protection on in an application that already runs. Measuring first, fixing what it finds, and switching on per project.
Not every rule needs a guarded read. Constraints, aggregates, explicit scopes, stream decisions, repair and hints, and the choices that fail silently.
The same guard without Arc: decision reads and append conditions. The Chronicle calls underneath, and how they map to the Dynamic Consistency Boundary.
Testing a decision against a race. Putting a competing write between a command’s read and its commit.
How a guard is built, merged and widened. Predicting exactly which events make a command fail.
Questions and a decision guide. This page.

Where the docs are

For Arc commands, start at Choosing how a command’s rule holds. From there, Getting started turns On for a first command, Adopting read protection is the path from Off through Measure, Refusals lists every error with its fix, How it works derives and merges guards, Pitfalls covers what fails silently, and the FAQ has more short answers.

For Chronicle without Arc, start at Dynamic Consistency Boundary, which has a reading order. Choosing how a rule holds picks the mechanism, DCB in Chronicle says what maps and what doesn’t, How guards are derived and Costs and limits go into the detail, and its questions and answers cover the client’s side. The API pages are Decision reads and Read protection.

Read protection as described here needs Arc 22.108.0 or later and Chronicle 19.68.0 or later; per-stream read models need Chronicle 19.71.0 or later; decision reads need a Chronicle server of 19.0.0 or later.

Previous: Part 10 — How a guard is built, merged and widened

How a guard is built, merged and widened · Decisions that hold, Part 10

Fri, 13 Nov 2026 09:00:00 GMT

Decisions that hold · Part 10 of 11

Every part of this series so far has leaned on the same object. A validator reads BookStock and the command’s append carries a guard. A monthly limit reads one stream of an account and the guard covers that month. A test puts a competing event between the read and the commit and the guard refuses the commit. I’ve described what each guard covers, but not how it’s put together.

A guard is an append condition: a position in the event log plus a filter. The kernel checks it atomically with the append and rejects the append if any event that matches the filter was appended after the position. Everything in this part is about where the position and the filter come from, what happens when a command has more than one source of them, and how to print the result so you don’t have to take my word for any of it.

The examples assume read protection is On, as in new Cratis applications (see Part 2). Under On, Arc drives the Chronicle machinery shown here for every command. The code below drives it directly, because that’s where you can print the guard.

Print the guard first

Chronicle’s unit of work can report what it sent with the append. Under a read-protection frame, GetAppendConditions() returns one AppendCondition per guarded event source after the commit:

using Cratis.Chronicle;
using Cratis.Chronicle.Auditing;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.Projections.ModelBound;
using Cratis.Chronicle.ReadModels;
using Cratis.Chronicle.Transactions;
using Cratis.Execution;

public record AccountId(string Value) : EventSourceId(Value);

[EventType]
public record MoneyWithdrawn(decimal Amount);

// Counts the withdrawals in the stream the read is scoped to.
[Passive]
[FromEvent<MoneyWithdrawn>]
public record MonthlyWithdrawals(string Id, [Count<MoneyWithdrawn>] int Count);

public static class ShowTheGuard
{
    public static async Task<IReadOnlyList<AppendCondition>> Withdraw(IEventStore eventStore, AccountId account)
    {
        var unitOfWork = (UnitOfWork)eventStore.UnitOfWorkManager.Begin(CorrelationId.New());
        using var frame = unitOfWork.EnforceReadProtection();
        var owner = unitOfWork.ClaimDecisionReadCommitOwnership();

        // Account, stream type "Transactions", stream id "2026-10".
        await eventStore.GetDecisionReads().GetFor<MonthlyWithdrawals>(unitOfWork, account, "Transactions", "2026-10");
        unitOfWork.AddEvent(
            EventSequenceId.Log,
            account,
            new MoneyWithdrawn(100),
            Causation.Unknown(),
            eventStreamType: "Transactions",
            eventStreamId: "2026-10");
        await unitOfWork.CommitAsOwner(owner);

        // One AppendCondition per guarded event source. Print it to see what the commit guarded.
        return unitOfWork.GetAppendConditions();
    }
}

defmodule MyApp.Events.SeeTheGuardMoneyWithdrawn do
  use Chronicle.Events.EventType, id: "see-the-guard-money-withdrawn"

  defstruct [:amount]
end

# Counts the withdrawals in the stream the read is scoped to.
defmodule MyApp.ReadModels.SeeTheGuardMonthlyWithdrawals do
  use Chronicle.ReadModels.ReadModel, passive: true

  defstruct id: nil, count: 0

  from MyApp.Events.SeeTheGuardMoneyWithdrawn, set: [id: :event_source_id], count: :count
end

defmodule MyApp.SeeTheGuardShowTheGuard do
  alias Chronicle.ReadModels.DecisionReads
  alias Chronicle.Transactions.UnitOfWork
  alias MyApp.ReadModels.SeeTheGuardMonthlyWithdrawals

  def withdraw(account_id) do
    unit_of_work = UnitOfWork.begin()

    # Account, stream type "Transactions", stream id "2026-10".
    {:ok, _read} =
      DecisionReads.get(SeeTheGuardMonthlyWithdrawals, account_id, "Transactions", "2026-10")

    # One concurrency scope per guarded event source. Inspect it to see what a commit would guard.
    guards = UnitOfWork.get_decision_reads(unit_of_work)

    UnitOfWork.rollback(unit_of_work)
    guards
  end
end

The first three lines of Withdraw and the CommitAsOwner call are what Arc does for a command under On: begin the unit of work, turn read protection on for the whole invocation, claim the right to commit, and commit as that owner at the end. Read protection is part of Arc for .NET. The Elixir tab works differently: it inspects the decision reads enrolled in the unit of work before anything is committed, rather than the conditions a commit sent.

With one earlier withdrawal in October already in the log, at position 0, ToString() on the single condition prints:

guard BankAccount-7: types=[MoneyWithdrawn], streamType=Transactions, streamId=2026-10, after 0

Read it left to right. BankAccount-7 is the event source, whose events count. types=[…] lists the event type ids that count. For a .NET [EventType] record without an explicit id, that’s the type name. streamType and streamId narrow it to one stream of the source. after 0 is the position: an event that matches everything before it and lands after position 0 rejects the append. On an empty log the boundary prints as no matching event instead, which is how “create it only if nothing like it exists yet” holds.

The condition also says where it came from. Origins is [ProtectedRead, DefaultRouting] and Reads is [MonthlyWithdrawals 'BankAccount-7']: the read gave the guard its filter and position, and it replaces the ordinary optimistic check for an append to that source. DefaultRouting only records that the append’s routing was taken into account; it adds nothing to the filter. A source the command reads but doesn’t append to carries only ProtectedRead.

The parts of a guard

Every guard has the same four parts. What changes is who supplies them:

Part	Decision read	Explicit scope	Event source definition
Event source	The key you read	`WithEventSourceId`	The event’s own source, when the definition declares the event source id
Event types	The types the model folds, including the types that remove it	`WithEventType`	None. Any type counts
Source type, stream type, stream id	Only for a stream-scoped read, with the values you pass	Whatever you set on the builder	The dimensions the definition declares
Position	The log’s tail, taken before the fold	The sequence number you captured	The tail, read when you append

Only the decision read takes the position before it reads the facts it decides on. That ordering is the whole trick. The client asks the kernel for the tail, then folds the key’s events. An event that lands during the fold, or after it, is after the position, so it conflicts. Take the tail after the fold instead and an event that arrives in between is in nobody’s guard.

The position is the tail of the whole log, not of the key. With MemberRegistered for member-1 at position 0 and one for member-2 at position 1, a read of MemberLoans for member-1 gives:

guard member-1: types=[MemberRegistered,LoanTaken,LoanReturned], after 1

That’s harmless: the filter decides what counts, and nothing for member-1 arrived after position 1. What the filter means in practice, with competing events appended between that read and the commit:

Competing event	Commit
`MemberRenamed` for `member-1`, a type the model doesn’t fold	Succeeds
`LoanTaken` for `member-2`, another source	Succeeds
`LoanTaken` for `member-1`	Rejected, nothing written

The rejection is a ConcurrencyViolation with the event source and the expected and actual sequence numbers. It doesn’t say which event caused it (Chronicle#4926 tracks that), and Chronicle doesn’t re-run your decision. A model that doesn’t exist yet is guarded the same way: the read of an unknown member-9 returns no instance, and a MemberRegistered for member-9 that arrives before the commit rejects it.

Several reads

A command often reads more than once. The unit of work collects every read, any explicit scope you pass, and the routing of the events you append, and merges them per event source when you commit. Only routing a definition declares joins the merge; ordinary routing leaves the reads’ guard as it is:

Everything a commit is guarded by is collected in the unit of work and merged per event source.

Reads of different sources stay separate. Reading MemberLoans for both member-1 and member-2 gives two conditions, checked in the same atomic append, so a conflict on either one rejects the whole batch:

guard member-1: types=[MemberRegistered,LoanTaken,LoanReturned], after 1
guard member-2: types=[MemberRegistered,LoanTaken,LoanReturned], after 1

Reads of the same source merge into one condition. The event types are the union, the position is the earliest of the reads, and each stream value survives only if the reads agree on it. Here are the two cases that surprise people, both printed from a commit under a read-protection frame. October’s and November’s MonthlyWithdrawals for the same account:

guard BankAccount-7: types=[MoneyWithdrawn], streamType=Transactions, after 0

The stream ids differ, so the stream id is gone. A withdrawal in December now rejects the commit, though neither read looked at December. October’s MonthlyWithdrawals beside a whole-account AccountBalance, which folds deposits too:

guard BankAccount-7: types=[MoneyWithdrawn,MoneyDeposited], after 0

The whole-account read has no stream, so the stream type and id are both gone, and the types are the union of both models.

What a second read of the same account does to the guard.

That’s the rule to remember: merging only widens. The merged condition covers everything either read would have caught, so a second read can add conflicts but can’t hide one. Outside a read-protection frame, for example AppendMany(guardedBy: reads), the stream values are kept only when both match and are otherwise both dropped; under a frame each value is kept or dropped on its own. If a rule really depends on two streams, read the whole source once instead, so the guard says what it covers. In an Arc command, ARCCHR0038 points out a per-stream read whose guard another read will widen.

An explicit scope beside a read

You can still pass your own concurrency scope for a source you also read. Chronicle doesn’t guess whether it’s enough. Under a frame it checks that the scope covers the read: its source, source type, stream type and stream id are each unset or equal to the read’s, its event types are empty or a superset, and its position is the same or earlier. A scope on the whole account, captured before the October read, covers it, and becomes the condition:

guard BankAccount-7: any type, after 0

Its Origins are [ProtectedRead, Explicit, DefaultRouting]. A scope that is narrower than the read is refused at commit. A scope on Transactions/2026-10 beside a whole-account AccountBalance read fails with ExplicitScopeDoesNotCoverReads:

The command returns an exact concurrency scope for 'BankAccount-7' that does not watch what it read: AccountBalance 'BankAccount-7'. Widen the scope and capture its boundary before reading.

Outside a frame, combining a decision read and an explicit scope on one source is refused outright with DecisionReadConflictsWithConcurrencyScope. In Arc, a stream decision is an explicit scope, so a stream decision beside a whole-source read of the same source is refused for the same reason: the stream is narrower than the read. Part 4 met the same refusal from the other side: a stream decision beside a per-stream validator, whose scope is captured after the validator’s read.

Declared concurrency on a definition

An event source definition can declare which dimensions guard every append to it. This one makes every event in one month of a ledger conflict with every other event in that month:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSources;

// Every event in one month of a ledger conflicts with every other event in that month.
[EventSource("Ledger")]
[EventStream(
    "Transactions",
    Concurrency = ConcurrencyDimensions.EventSourceId | ConcurrencyDimensions.EventStreamType | ConcurrencyDimensions.EventStreamId)]
public class LedgerEventSource : IEventSource;

[EventType]
public record LedgerPosted(decimal Amount);

Read a per-month model of LedgerPosted for source type Ledger, Transactions/2026-10, then stage the posting without the definition’s routing. The read passes the source type along with the stream type and stream id, so the guard is the read’s own, with origins [ProtectedRead, DefaultRouting]:

guard BankAccount-7: types=[LedgerPosted], sourceType=Ledger, streamType=Transactions, streamId=2026-10, after 0

Stage the same posting through LedgerEventSource, and under a frame the declared dimensions merge into the read’s guard:

guard BankAccount-7: any type, streamType=Transactions, streamId=2026-10, after 0

The origins change from DefaultRouting to DeclaredRouting. The declared dimensions are kept only where they equal the read’s, so the month stays. The event types become any type, because the definition says every event in the month counts. The source type isn’t among the declared dimensions, so it’s dropped. The position is still the read’s. Any event in October now rejects the commit, not only a posting.

Arc follows the same rule under On: it doesn’t build the routing scope itself, it hands the declared dimensions to Chronicle, which merges them at commit.

The definition declares	What it does to a read’s guard
Nothing, or `None`	Nothing
Dimensions that include the event source id	Merged into the read’s guard. Event types become any type
Dimensions without the event source id	A separate guard, not tied to the read. It doesn’t protect the state you read

That’s correct when the month really is the consistency boundary, such as a ledger, a numbering sequence or an approval stream, where every writer should see every other. For anything else it only adds conflicts. ARCCHR0038 also reports a declared Concurrency that includes the event source id without both stream dimensions, because it widens a per-stream guard to the whole source.

Aggregates and stream decisions

Two more dependencies supply guards in Arc, and both fit the same shape:

Dependency	Guard
Aggregate root	Taken when the aggregate is rehydrated: its event source and the event types it handles, from the tail at that moment. An aggregate and a protected read of the same source are refused
Stream decision	An explicit scope taken when the stream is read: the routed stream, any event type
Fresh identifier check	An “expect no matching event” guard on the new id

What a guard cannot see

A guard compares events appended after a position with a filter, so anything that isn’t an appended event matching that filter is outside it: revisions and redactions, writers without a guard, projection definitions changed elsewhere, other sequences and stores. Part 8 and Part 9 list these in full. Two details follow from the anatomy. Chronicle refuses Revise and Redact inside a read-protection frame, so a protected command can’t do them to itself (Chronicle#4900 tracks a kernel check for other processes). And a command that reads but appends nothing has no guard at all: GetAppendConditions() is empty.

Guards also have a cost shape worth knowing. Each guarded read folds the key’s history of the model’s types, every time, and folds of one model type are served through one projection per type in the kernel, so they are expected to queue behind each other across keys and tenants. Chronicle’s costs and limits page has the one measurement published so far, with its environment. Keep guarded models flat and keys short-lived.

Chronicle’s How guards are derived page has the full merge tables, Arc’s How read protection works shows what Arc does for each command, and read protection documents the frame API. The last part of the series collects the questions that come up most and a guide to which mechanism a rule needs.

The examples need Chronicle 19.68.0 or later. With Arc, read protection needs Arc 22.108.0 or later.

Previous: Part 09 — Testing a decision against a race

Testing a decision against a race · Decisions that hold, Part 9

Wed, 11 Nov 2026 09:00:00 GMT

Decisions that hold · Part 09 of 11

Part 1 said the race is invisible in the tests most of us write, because they run one request at a time. Parts 2 to 8 showed how Arc and Chronicle guard a decision. This part is about the test that shows the guard is there: the command reads, someone else writes, and the command must not commit.

The examples assume read protection is On, as in new Cratis applications (see Part 2). They use the library from Part 2: BookStock folded from CopyAdded, BookBorrowed and BookReturned, and BorrowBook with a validator that takes BookStock?. Command scenarios and read protection are part of Arc for .NET. The general tour of command scenarios is in Testing with Arc and Chronicle; this post assumes it.

A test that passes once

These are the tests I’d write first for BorrowBook: one where a copy is on the shelf, and one where it isn’t.

using Cratis.Arc.Chronicle.Testing.Commands;
using Cratis.Arc.Testing.Commands;
using Cratis.Arc.Validation;
using Xunit;

public class when_borrowing_a_book
{
    [Fact]
    public async Task with_a_copy_on_the_shelf_it_is_lent()
    {
        await using var scenario = new CommandScenario<BorrowBook>();
        var isbn = new Isbn("isbn-1");
        scenario.Given.ForEventSource(isbn).Events(new CopyAdded());

        var result = await scenario.Execute(new BorrowBook(isbn, new MemberId(Guid.NewGuid())));

        result.ShouldBeSuccessful();
        await scenario.ShouldHaveAppendedEvent<BorrowBook, BookBorrowed>(isbn);
    }

    [Fact]
    public async Task with_no_copy_on_the_shelf_it_is_refused()
    {
        await using var scenario = new CommandScenario<BorrowBook>();
        var isbn = new Isbn("isbn-1");
        scenario.Given.ForEventSource(isbn).Events(new CopyAdded(), new BookBorrowed(new MemberId(Guid.NewGuid())));

        var result = await scenario.Execute(new BorrowBook(isbn, new MemberId(Guid.NewGuid())));

        result.ShouldHaveValidationErrorBecauseOf(ValidationResultReason.Rule);
        Assert.Empty(scenario.AppendedEvents);
    }
}

Both are worth having. The second asserts the reason, not just that the command failed. ShouldHaveValidationErrors() passes for almost any rejection: a rule, a constraint, a race, a validator that threw. It fails on purpose when the only results are dependencies that couldn’t be resolved, because then no rule ran at all: a validator whose read model the test forgot to seed is never built, and the test would keep passing with the rule deleted. ShouldHaveValidationErrorBecauseOf(ValidationResultReason.Rule) passes only when the validator’s rule said no.

Neither test says anything about a race. Both pass with read protection Off, where the validator’s read is a plain snapshot that guards nothing. A test that never puts another writer between the read and the commit can’t tell a guarded read from an unguarded one.

A competitor between the read and the commit

This is the race from Part 2 as a test. One copy is on the shelf, another member borrows it after our command has read the stock, and our command must not commit:

using Cratis.Arc.Chronicle.Testing.Commands;
using Cratis.Arc.Testing.Commands;
using Cratis.Arc.Validation;
using Xunit;

public class when_another_member_borrows_the_last_copy_first
{
    [Fact]
    public async Task it_is_refused_and_nothing_is_written()
    {
        await using var scenario = new CommandScenario<BorrowBook>();
        var isbn = new Isbn("isbn-1");
        scenario.Given.ForEventSource(isbn).Events(new CopyAdded());
        scenario.AppendConcurrently(isbn, new BookBorrowed(new MemberId(Guid.NewGuid())));

        var result = await scenario.Execute(new BorrowBook(isbn, new MemberId(Guid.NewGuid())));

        result.ShouldHaveValidationErrorBecauseOf(ValidationResultReason.ConcurrencyViolation);
        Assert.Equal("ReadChanged", Assert.Single(result.ValidationResults).ReasonDetail);
        Assert.Empty(scenario.AppendedEvents);
    }
}

Line by line:

Given.ForEventSource(isbn).Events(new CopyAdded()) seeds the book’s history into the scenario’s event log. The validator’s BookStock is folded from that log, so it sees one copy and the rule passes.
AppendConcurrently(isbn, ...) queues a competing event. The scenario doesn’t append it now. It appends it while the command runs: after the validator has read and Handle() has returned, and before the command’s unit of work commits. That’s the window two real requests race in.
Execute runs the command through the same pipeline as production. The commit finds a BookBorrowed for this book after the position the read took, and refuses the append.
The assertions check the reason (ConcurrencyViolation), the detail (ReadChanged, which tells a changed read from one that couldn’t be read completely), and that nothing from the command was written. AppendedEvents holds the command’s own appends that succeeded. The competitor’s event stays in the log, but it isn’t in that list.

The validation result carries the same message a caller gets:

BookStock 'isbn-1' changed after BorrowBook read it. Nothing from this command was written; submit it again.

The seeded events are there before the read. The competitor lands between the read and the commit.

This is the test that changes when the mode changes. Compile the same command with read protection Off and run the same test: the command succeeds, its BookBorrowed is appended next to the competitor’s, and the assertion on ConcurrencyViolation fails. That failure is the test doing its job. It says the rule isn’t guarded.

What the scenario sets up for you

There’s no setup in that test beyond new CommandScenario<BorrowBook>(). The scenario looks at the command first. When it runs under read protection On or Measure, is marked [ProtectedDecision], or takes a decision dependency (DecisionRead<T>, IDecisionReads, IStreamReads, StreamDecision, or a per-stream read model), the scenario uses one real in-process Chronicle event log for everything: the seeded events, the guarded reads, the competitor and the command’s commit. The read and the commit see the same history, which is what makes the race real.

Older tests may call UseDecisionReads() to get that log. It isn’t needed anymore. It’s hidden from IntelliSense and kept so those tests compile.

The mode comes from the assembly that declares the command, or from [ReadProtection(...)] on the command, as in production. The test project doesn’t set anything. If the command’s project says On, the test runs under On.

Two things change in that mode:

scenario.EventScenario throws EventScenarioUnavailableInDecisionMode. It belongs to a separate log that the command’s reads would never see. Seed with Given.ForEventSource(...).Events(...). scenario.EventLog points at the shared log, and it holds everything: seeds, competitors and commits.
Seeding on a route, Given.ForEventSource(...).OnRoute(route).Events(...), needs this log. Outside it, routed seeding throws.

Measure selects the same log, but it doesn’t add a guard. A command under Measure returns what it would return under Off, so the race test fails under Measure just as it does under Off. Measure reports what On would do; it doesn’t do it. Test the command in the mode it runs in.

Seed events, not read models

Command scenarios can also pin a read model instead of deriving it from events:

scenario.Given.ForEventSource(isbn).ReadModel(new BookStock(isbn, 1));

Under On that doesn’t do what it looks like. A guarded read always folds the event log, as it does in production, and never sees a pinned instance. With that pin and no events, the validator gets null and the command is refused with “No copies of this book are available.” A pinned instance serves only the reads that don’t guard the decision, such as a read marked [Unprotected]. For a [ProtectedDecision] command that takes the model as a DecisionRead<T>, pinning it throws PinnedReadModelCannotProvideDecisionToken.

So seed the events that produce the state. For a guarded read they’re the only way to supply it, and they test the projection as well.

Two keys

Part 3’s BorrowBook reads two models, BookStock for the book and MemberLoans for the member, and appends one event to each in one batch. Each read guards its own key, so a competing write on either key must refuse the whole borrow. This test competes on the member: two loans are taken, a third arrives after the read, and the borrow would have been the fourth.

using Cratis.Arc.Chronicle.Testing.Commands;
using Cratis.Arc.Testing.Commands;
using Cratis.Arc.Validation;
using Xunit;

public class when_the_member_takes_another_loan_first
{
    [Fact]
    public async Task the_whole_borrow_is_refused()
    {
        await using var scenario = new CommandScenario<BorrowBook>();
        var isbn = new Isbn("isbn-1");
        var member = new MemberId("member-1");
        scenario.Given.ForEventSource(isbn).Events(new CopyAdded());
        scenario.Given.ForEventSource(member).Events(new LoanTaken(new Isbn("isbn-2")), new LoanTaken(new Isbn("isbn-3")));
        scenario.AppendConcurrently(member, new LoanTaken(new Isbn("isbn-4")));

        var result = await scenario.Execute(new BorrowBook(isbn, member));

        result.ShouldHaveValidationErrorBecauseOf(ValidationResultReason.ConcurrencyViolation);
        Assert.Empty(scenario.AppendedEvents);
    }
}

The message names the model and the key that changed:

MemberLoans 'member-1' changed after BorrowBook read it. Nothing from this command was written; submit it again.

Neither the book’s BookBorrowed nor the member’s LoanTaken is written. Write the same test with the competitor on the book, a BookBorrowed for isbn-1, and it’s refused too. One test per key you read is the way to find a key that isn’t guarded, for example a model that is read through a key other than the one you expected.

One month

Part 4’s withdrawal limit reads MonthlyWithdrawals from one month’s stream. The competitor has to land on the same route for the test to mean anything, so seed and compete on the route, not just the account:

using Cratis.Arc.Chronicle.Testing.Commands;
using Cratis.Arc.Testing.Commands;
using Cratis.Arc.Validation;
using Xunit;

public class when_another_withdrawal_lands_while_withdrawing
{
    [Fact]
    public async Task in_the_same_month_it_is_refused()
    {
        await using var scenario = new CommandScenario<Withdraw>();
        var account = new AccountId("account-1");
        var october = scenario.EventRoutes.For<BankAccountEventSource>("Transactions").WithStreamId("2026-10");
        scenario.Given.ForEventSource(account).OnRoute(october).Events(new MoneyWithdrawn(4000m));
        scenario.AppendConcurrently(account, october, new MoneyWithdrawn(500m));

        var result = await scenario.Execute(new Withdraw(account, "2026-10", 500m));

        result.ShouldHaveValidationErrorBecauseOf(ValidationResultReason.ConcurrencyViolation);
        Assert.Empty(scenario.AppendedEvents);
    }

    [Fact]
    public async Task in_another_month_it_goes_through()
    {
        await using var scenario = new CommandScenario<Withdraw>();
        var account = new AccountId("account-1");
        var transactions = scenario.EventRoutes.For<BankAccountEventSource>("Transactions");
        scenario.Given.ForEventSource(account).OnRoute(transactions.WithStreamId("2026-10")).Events(new MoneyWithdrawn(4000m));
        scenario.AppendConcurrently(account, transactions.WithStreamId("2026-11"), new MoneyWithdrawn(500m));

        var result = await scenario.Execute(new Withdraw(account, "2026-10", 500m));

        result.ShouldBeSuccessful();
        await scenario.ShouldHaveAppendedEvent<Withdraw, MoneyWithdrawn>(account);
    }
}

scenario.EventRoutes resolves a route from the event source definitions the scenario discovered, so For<BankAccountEventSource>("Transactions") is the same stream type the command is routed to, and WithStreamId("2026-10") is the month. OnRoute seeds there, and the AppendConcurrently overload that takes a route makes the competitor land there.

The second test is the one people skip. It checks that the guard isn’t wider than the rule: a withdrawal in November doesn’t touch October’s total, so it mustn’t refuse an October withdrawal. Part 4 showed how a whole-account read next to the monthly one widens the guard to every month. A test like this is how you’d notice. The same goes for the library: a borrow of another book, or a BookRenamed on the same book, which BookStock doesn’t fold, should leave the command alone.

Without Arc

When you call Chronicle directly, as in Part 8, the race test has the same shape without a scenario: take the decision read, append a competing event, then do the guarded append and check that it was refused. Chronicle’s Test the race scenario shows it in C# and Elixir.

If the code runs in a unit of work with read protection enforced, you can also check what was guarded. After the commit, unitOfWork.GetAppendConditions() (namespace Cratis.Chronicle.Transactions) returns one AppendCondition per guarded source, with its event types, stream values, position and the origins behind it. Assert on the origins and the number of conditions rather than on their text. See what a commit guarded in Chronicle’s docs has the example. Part 10 is about how those conditions are built.

What a green race test does not show

A race test checks one interleaving: one competitor, at one point, after the read and before the commit. It shows the guard covers that event on that key. It doesn’t show:

Timing or load. The log is Chronicle’s in-process store for tests, not a Chronicle server or its storage. A green test says nothing about how the guard behaves under contention or what it costs.
Writers that don’t guard their own decision. Your command detects a matching event from any writer. A command elsewhere that reads plainly, under Off, through [Unprotected] or with an immediate append, can still break the rule with its own decision.
What’s outside every guard. Revise and Redact, projection definitions changed by another process, services, other databases and other event sequences.
The mode in production. The test runs in the mode compiled into the command’s assembly. A runtime cap, ReadProtection:MaximumMode, can lower it on a host. Part 6 covers that.

The command runs under On: a plain new CommandScenario<T>(), events seeded with Given.ForEventSource(...).Events(...), a competitor with AppendConcurrently, and ShouldHaveValidationErrorBecauseOf(ValidationResultReason.ConcurrencyViolation) plus an empty AppendedEvents.
The test pins read models with .ReadModel(...): seed the events instead. A guarded read never sees a pinned instance.
An old test seeds through scenario.EventScenario: move the seeding to Given.ForEventSource(...).Events(...). EventScenario throws under On and Measure.
The command reads two keys: one race test per key. Each must refuse the whole command.
The read is per stream: seed and compete on the same route, and add a test where a competitor on another stream id goes through.
The command runs under Off or Measure: the race test fails, because nothing is guarded. That’s the answer the test is there to give.
The code calls Chronicle directly: read, compete, append with the guard; under enforced read protection, assert on GetAppendConditions() after the commit.

The reference is Arc’s Test the race, and Testing Chronicle commands covers the scenario’s decision mode in full, including how reads that don’t guard the decision are resolved.

The examples need Arc 22.108.0 or later and Chronicle 19.71.0 or later.

Previous: Part 08 — The same guard without Arc: decision reads and append conditions

The same guard without Arc: decision reads and append conditions · Decisions that hold, Part 8

Mon, 09 Nov 2026 09:00:00 GMT

Decisions that hold · Part 08 of 11

Parts 2 to 7 let Arc do the work. A command takes a read model, read protection is On, and the read guards the command’s append without any code that mentions a guard. Those examples assume read protection is On, as in new Cratis applications (see Part 2).

Not every decision runs as an Arc command. A minimal API endpoint, an MVC controller, a background worker or an Elixir service talks to Chronicle directly, and there nothing enrolls a read for you. The mechanism underneath Arc is a Chronicle API, and you can call it yourself. This part does that, and then uses the result to say concretely what Chronicle’s guard is in the terms of the Dynamic Consistency Boundary (DCB), and what it is not.

What Arc was doing for you

Arc’s read protection is a host for Chronicle’s decision reads. For each command under On, it does three things:

In an Arc command under On	In Chronicle’s API
A read-model parameter is read fresh	`IDecisionReads.GetFor<T>(unit, key)`: note the log position, fold the key, enroll the read as a guard in the command’s unit of work
The events `Handle()` returns are written	Staged in the unit and appended with every enrolled guard in one call
A lost race comes back as a 400 with `ReadChanged`	The unit’s commit fails, and `GetDecisionConflicts()` names the read model and key

Without Arc, those three are yours: take the read as a decision read, attach it to the append, and check the result before you answer the caller. Chronicle’s read protection page has the full mapping.

A decision read and a guarded append

The smallest form guards one append. A workshop has a fixed number of places, and a booking may only be made while one is free. Decision reads exist in the .NET and Elixir clients:

using Cratis.Chronicle;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.Projections.ModelBound;
using Cratis.Chronicle.ReadModels;

public record WorkshopId(string Value) : EventSourceId(Value);

[EventType]
public record WorkshopOpened(int Places);

[EventType]
public record PlaceBooked(string Attendee);

[EventType]
public record PlaceCancelled(string Attendee);

// The decision model: a flat projection with an Id, keyed by the event source.
[FromEvent<WorkshopOpened>]
public record WorkshopPlaces(
    string Id,
    [SetFrom<WorkshopOpened>(nameof(WorkshopOpened.Places))] int Total,
    [Increment<PlaceBooked>] [Decrement<PlaceCancelled>] int Booked);

public static class BookPlace
{
    public static async Task<bool> Handle(IEventStore eventStore, WorkshopId workshop, string attendee)
    {
        // 1. The read notes the log position, then folds the workshop's events.
        var read = await eventStore.GetDecisionReads().GetDetached<WorkshopPlaces>(new ReadModelKey(workshop.Value));
        if (read.Instance is not { } places || places.Booked >= places.Total)
        {
            return false;
        }

        // 2. The append carries the read as its guard. A later PlaceBooked, PlaceCancelled or
        //    WorkshopOpened for this workshop rejects it and nothing is written.
        var result = await eventStore.EventLog.AppendMany(
            [new EventForEventSourceId(workshop, new PlaceBooked(attendee))],
            guardedBy: [read]);

        return result.IsSuccess;
    }
}

defmodule MyApp.Events.WorkshopOpened do
  use Chronicle.Events.EventType, id: "workshop-opened"

  defstruct [:places]
end

defmodule MyApp.Events.PlaceBooked do
  use Chronicle.Events.EventType, id: "place-booked"

  defstruct [:attendee]
end

defmodule MyApp.Events.PlaceCancelled do
  use Chronicle.Events.EventType, id: "place-cancelled"

  defstruct [:attendee]
end

# The decision model: a flat projection keyed by the event source.
defmodule MyApp.ReadModels.WorkshopPlaces do
  use Chronicle.ReadModels.ReadModel

  defstruct id: nil, total: 0, booked: 0

  from MyApp.Events.WorkshopOpened, set: [id: :event_source_id, total: :places]
  from MyApp.Events.PlaceBooked, add: [booked: 1]
  from MyApp.Events.PlaceCancelled, subtract: [booked: 1]
end

defmodule MyApp.BookPlace do
  alias Chronicle.EventSequences.EventLog
  alias Chronicle.ReadModels.{DecisionConflict, DecisionReads}
  alias MyApp.Events.PlaceBooked
  alias MyApp.ReadModels.WorkshopPlaces

  def handle(workshop_id, attendee) do
    result =
      Chronicle.decide(fn _unit_of_work ->
        # 1. The read notes the log position, folds the workshop's events and enrolls
        #    itself as the guard of the unit of work.
        {:ok, read} = DecisionReads.get(WorkshopPlaces, workshop_id)

        case read.instance do
          %WorkshopPlaces{total: total, booked: booked} when booked < total ->
            # 2. The append is buffered and committed with the guard. A later booking,
            #    cancellation or opening for this workshop rejects the whole commit.
            :ok = EventLog.append(workshop_id, %PlaceBooked{attendee: attendee})
            :booked

          _ ->
            :full
        end
      end)

    case result do
      {:ok, :booked} -> true
      {:ok, :full} -> false
      {:error, %DecisionConflict{}} -> false
      {:error, _reason} -> false
    end
  end
end

GetDetached does two things in order. It notes the position of the event log’s tail, and then it folds WorkshopPlaces for that workshop from the event log in a fresh projection session. It does not use the stored read model, which can lag and has no position. What comes back is the state (read.Instance) and the guard (read itself), and guardedBy: [read] hands the guard to the append. The kernel then rejects the append if an event of a type the model folds (WorkshopOpened, PlaceBooked or PlaceCancelled) was appended for this workshop after the noted position.

The fold is what you decide on. The key, the model’s event types and the noted position are what the append is checked against.

Three details matter when you write this yourself.

An absent model is guarded too. If nothing has opened the workshop, Instance is null and the guard expects no matching event at all, so a WorkshopOpened that lands before the append rejects it. The example returns false in that case anyway, but a create-if-absent rule depends on it.
A conflict is a result, not an exception. AppendMany returns an AppendManyResult with IsSuccess set to false, and result.GetDecisionConflicts([read]) returns one conflict that names WorkshopPlaces and the key. IsSuccess is also false for a constraint violation, so ask for the conflicts when you need to tell the two apart.
Nothing is retried. Chronicle does not re-run your decision. The fold itself makes up to three attempts if events arrive while it folds, but once you have the value, a lost race means: read again, decide again, or tell the caller.

Events on other keys, or events of a type the model does not fold, such as a hypothetical WorkshopRenamed, leave the append alone. The guard is as narrow as the model.

The Elixir client reads inside Chronicle.decide. DecisionReads.get enrolls the read in the unit of work that decide opens, EventLog.append buffers the event in that unit, and the unit commits with the guard when the function returns. A lost race comes back as {:error, %DecisionConflict{}}.

Inside a request

GetDetached suits code where the read and the append sit next to each other. In a web request they often don’t: the read happens in one service, the append in another. In the .NET client, IDecisionReads.Get<T> enrolls the read in the request’s unit of work instead of returning a detached guard, and every event staged in that unit is appended with the guard when it commits.

A member may hold at most three loans. As a minimal API endpoint, with the loan count as the decision model:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections.ModelBound;

[EventType]
public record LoanTaken(string Isbn);

public record MemberLoans(
    EventSourceId Id,
    [Increment<LoanTaken>] int Active);

using Cratis.Chronicle.AspNetCore.Transactions;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.ReadModels;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;

public record TakeLoanRequest(string Isbn);

public static class LoanEndpoints
{
    public static void Map(WebApplication app) =>
        app.MapPost("/members/{memberId}/loans", async (
            string memberId,
            TakeLoanRequest body,
            HttpContext http,
            IDecisionReads reads,
            IEventLog eventLog) =>
        {
            var loans = await reads.Get<MemberLoans>(memberId);
            if (loans.Instance is { Active: >= 3 })
            {
                return Results.UnprocessableEntity("The member has reached the loan limit.");
            }

            await eventLog.Transactional.Append(memberId, new LoanTaken(body.Isbn));

            var unit = await http.Features.Get<IUnitOfWorkCompletionFeature>()!.CommitAsync();
            if (unit.GetDecisionConflicts().Any())
            {
                return Results.Conflict("The member's loans changed. Nothing was written; read again and decide again.");
            }

            return unit.IsSuccess ? Results.Ok() : Results.UnprocessableEntity("The loan was not recorded.");
        });
}

Chronicle’s ASP.NET Core middleware begins a unit of work for each request, and Get<T> needs that ambient unit. Transactional.Append stages the event in it. The line that is easy to leave out is the commit. Left alone, the middleware commits the unit after the endpoint has returned, when the response is already on its way, and it reports no concurrency violation to the caller. The caller would see a 200 for a write that was rejected. IUnitOfWorkCompletionFeature.CommitAsync() asks the middleware’s owner to commit now, so the endpoint can answer with the outcome, and the middleware does not commit that unit again.

When another loan for the same member lands between the read and the commit, this endpoint answers 409, and the member’s log has the competing loan and not this one. A member who already holds three gets the 422 before anything is staged. The conflict check comes before IsSuccess because IsSuccess is also false for a constraint violation. And the 409 carries a message, not the conflicts themselves: in Chronicle 19.73 and earlier, a DecisionConflict holds the read model’s Type, which System.Text.Json refuses to serialize, so Results.Conflict(unit.GetDecisionConflicts()) fails while it writes the response, on exactly the path you wanted to report. Map conflicts to your own response shape.

One mistake undoes it quietly: a plain eventLog.Append(...) in the same request is written immediately and bypasses the guard. A controller action uses the same calls, with HttpContext.Features instead of the http parameter; Arc’s Chronicle used directly page has both. In Elixir, Chronicle.decide commits when its function returns, so the outcome is known while you can still choose the response.

In DCB terms

DCB, as the specification describes it, gives every event a set of tags. A decision builds its state, the decision model, from a query: event types (any of them) and tags (all of them). When it appends, it passes an append condition: fail if an event matching that query was stored after the position the decision read up to. One event can carry several tags, so a fact about a student and a course is one event that both decisions see.

Chronicle has the same two parts, a decision model and an append condition, but not the tags. Each event belongs to exactly one event source. The role of the tags is played by four values on every event, each with exactly one value: the event source ID, the event source type, the event stream type and the event stream ID. For the workshop read above, the query is “WorkshopOpened or PlaceBooked or PlaceCancelled, with event source ID ws-1”, and the position is the one noted before the fold.

DCB	Chronicle
Decision model	The state of a decision read: a flat projection keyed by the event source, over a finite set of event types
Query: event types ORed, tags ANDed	The read model’s event types, and the event source ID plus, where you narrow it, event source type, stream type and stream ID
`after`: the position the decision read up to	The position the decision read notes before it folds
Append condition	`guardedBy:` on `AppendMany`, or the reads enrolled in a unit of work
Atomic append across entities	`AppendMany`, all or nothing across event sources. A unit of work commits as one `AppendMany`

What DCB can do and Chronicle cannot follows from the one-source-per-event model. One event can’t be tagged with two entities, so a fact about two entities is two events in one atomic AppendMany, one per event source. There is no query for “events about both X and Y”. Custom tags are stored and filterable, but take no part in concurrency, so anything the guard must tell apart has to be an event type or one of the four values. Two independent conditions on the same event source are merged into one wider one. A decision read refuses a projection that joins entities or is keyed by something other than the event source. And a guard covers the event log only, not other event sequences.

Chronicle’s own summary is the sentence I’d keep: it supports DCB-style decision models and append conditions within its event-source model. It is not a DCB event store. Einar’s DCB, but not DCB argues for naming what you want from DCB instead. The DCB in Chronicle page has the full mapping and says when recording one fact as two events is acceptable, and DCB examples in Chronicle answers each canonical DCB example, including the course subscription with two decision reads and two events.

When no model fits: tail first

Some decisions don’t fit an admitted read model: a balance summed from two event types with no projection for it, or a rule over raw events. You can build the same guard by hand. Note the tail first, read the facts after, and append with a concurrency scope from the noted tail. In the .NET client:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;
using Microsoft.AspNetCore.Http;
using ScopeBuilder = Cratis.Chronicle.EventSequences.Concurrency.ConcurrencyScopeBuilder;

[EventType]
public record Deposited(decimal Amount);

[EventType]
public record Withdrawn(decimal Amount);

public static class Withdraw
{
    public static async Task<IResult> Handle(IEventLog eventLog, EventSourceId accountId, decimal amount)
    {
        var tail = await eventLog.GetTailSequenceNumber(accountId);
        var events = await eventLog.GetFromSequenceNumber(EventSequenceNumber.First, accountId);
        var balance = events.Select(_ => _.Content).Sum(content => content switch
        {
            Deposited deposited => deposited.Amount,
            Withdrawn withdrawn => -withdrawn.Amount,
            _ => 0m
        });

        if (balance < amount)
        {
            return Results.UnprocessableEntity("Insufficient funds.");
        }

        var scope = tail.IsUnavailable
            ? new ScopeBuilder().WithEventSourceId(accountId).ExpectingNoMatchingEvent().Build()
            : new ConcurrencyScope(tail, EventSourceId: accountId);

        var result = await eventLog.Append(accountId, new Withdrawn(amount), concurrencyScope: scope);
        return result.IsSuccess ? Results.Ok() : Results.Conflict();
    }
}

The order is the guard. With the tail noted before the read, a withdrawal that lands in between is after the scope’s position and rejects the append. Note the tail after the read instead, and that same withdrawal sits before the position: the append succeeds against a balance that no longer holds. When the account has no events yet, the tail is unavailable, and the scope expects no matching event at all.

This scope is wider than a decision read’s guard: it names no event types, so any event for the account after the tail rejects the append. That is safe, and more conflicts than you need on a busy account. Name the types with WithEventType<T>() on the builder when only some events matter. The alias at the top is there because in an Arc project Cratis.Arc.Chronicle.Commands has a static class called ConcurrencyScopeBuilder as well. Part 7 shows a concurrency scope in every Chronicle client.

Results you must check

Outside an Arc command, nothing reads the result for you, and every failure on this path is a value.

Append returns an AppendResult and AppendMany an AppendManyResult. A concurrency or constraint violation sets IsSuccess to false and throws nothing, so code that ignores the result reports success whatever happened.
GetDecisionConflicts tells a lost race from a constraint violation and names the read model and key. It does not name the event that conflicted.
A scope you build yourself without a position fails closed. If it narrows by event source, stream, source type or event types, the client turns it into “no matching event may exist”, so the append is rejected if anything matching is already in the log. Only a scope that narrows nothing is sent unchecked, with a client warning, and ConcurrencyCheckPerformed on the result says whether a scope was compared at all, so a skipped check does not look like a passing one. ConcurrencyOptions.SkipIncompleteExplicitScopes = true brings back the older skip. Give a scope the tail you noted, or say ExpectingNoMatchingEvent() when that is what you mean, as Withdraw does.
The first-append skip belongs to the default check. When Chronicle’s concurrency strategy issues the scope and nothing matching has been appended yet, there is no tail to compare against, and the check is skipped unless CheckFirstAppendIntoAScope is on. A decision read of an absent model already expects no matching event.

Limits

A decision read guards less than it might seem to, and costs more than a plain read.

Only some models can be read this way. A flat projection keyed by the event source, or an unfiltered reducer without constructor dependencies other than ILogger<T>. Joins, children, event-property keys, filtered reducers and other event sequences are refused with DecisionReadRefused and a typed reason, before anything is read.
GUID keys must be written the same way everywhere. For a model keyed by a GUID, every writer of that event source must use the lowercase canonical form. A writer in another language that formats it differently is outside the guard.
It is a full fold every time. Each attempt makes two tail reads, opens a fresh projection session and folds the key’s whole history. The first read of a model type also checks its definition. Keep the keys short-lived. Chronicle’s docs publish one measurement with its environment.
What it does not see. A revision or redaction of an earlier event does not move the tail, so it does not conflict. Other event sequences, external data, clocks and projection definitions changed by another process are not guarded either. And a guard only protects the decisions that carry it: a writer that appends without one can still break the rule. The rule holds only when every writer that decides on it is guarded, or when it is a constraint, which the kernel checks for every append.

Where this goes next

Everything here is opt-in, append by append. That is the trade: code that calls Chronicle directly chooses each guard, and nothing stops the next change from reading through IReadModels and appending without one. Chronicle’s EnforceReadProtection() turns that around for a unit of work: inside it, a decision read is enrolled as a guard, a plain read is refused unless you mark it advisory with a reason, and an immediate append is refused. That is the contract Arc enforces for commands under On. Part 10 covers that, and how guards from several reads are merged. Part 9 is first: testing a decision against a competing write.

Chronicle’s decision reads page covers the unit-of-work lifecycle, stream-scoped reads and admitted shapes in full. Choosing how a rule holds compares decision reads with constraints and scopes, and Arc’s pitfalls page lists the results to check when you call Chronicle directly.

The .NET examples need Cratis.Chronicle and Cratis.Chronicle.AspNetCore 19.68.0 or later (decision reads themselves arrived in 19.9.0; the scope behaviour described here in 19.68.0), and the Elixir example needs the Elixir client 3.13.0 or later. Decision reads need a Chronicle server of 19.0.0 or later; on servers older than 19.40.1, an append renumbered after a duplicate-sequence collision is not checked again.

Previous: Part 07 — Not every rule needs a guarded read

Careers that remember: introducing the Cratis Cast

Mon, 09 Nov 2026 00:00:00 GMT

“Event Sourcing” on a CV says nothing. It reads the same whether the person skimmed the docs last week or has shipped three systems on Chronicle. A client looking for help can’t tell the two apart, and the people who do the work get little credit for it outside GitHub.

There’s a second problem we run into all the time. Event sourcing is easier to show than to explain. Most people have never watched a system rebuild its state by replaying facts, and a diagram of an event log doesn’t make them feel it.

The Cratis Cast is our answer to both. Its tagline is the people behind the play, which fits the rest of the family: Screenplay, Stage, Scene, Prologue. Cratis is software that remembers. Cast is careers that remember.

One file, one site

You run one command and edit one file:

npm create @cratis/cast@latest my-site

The scaffolder asks for your GitHub handle, prefills a cast.yaml from your public profile, and writes a GitHub Pages workflow that rebuilds the site every hour. The site itself comes from @cratis/cast, an Astro integration. Your editor completes and checks cast.yaml against its published schema, and engine updates arrive as a version bump.

What you get is a static site in the Cratis design, with one accent color of your own and light and dark themes. It has sections for what you do now, your writing, your talks and your projects, and a printable CV at /cv built from the same data. There’s a terminal behind the backtick key and a command palette on ⌘K or Ctrl+K, because the people who build with Cratis tend to like those.

A career is an event stream

The part I care most about is the career replay. A career is a sequence of things that happened: you joined a company, took on a role, picked up a skill, left, started something. Cast stores it that way. A visitor presses play, the events fold into a projection in the browser, and the current role, the organizations and the skills rebuild one event at a time.

That’s event sourcing in about ten seconds, on a page someone opened for a different reason. Nobody has to read an explanation first.

The numbers on the page come from GitHub, not from you. Merged pull requests, contributions and releases are read from public data on every hourly build and refreshed again in the browser. Private repositories are filtered out at every step.

A badge the site can’t claim

A personal site is static and its owner controls every byte of it, so anything it says about itself is a claim. Cast is built around that fact.

There are three tiers:

Core: the founders and maintainers of Cratis.
Partner: consultants and companies Cratis vouches for, people we’ve worked with and would recommend for Cratis work.
Contributor: anyone with at least one merged pull request in a public repository in the Cratis organization.

Core and Partner come only from Registry/members.yaml in the Cast repository, and that file changes only through reviewed pull requests. Contributor is computed from GitHub when a site or the directory builds, and is never listed in the file. cast.yaml has no tier field, and the engine rejects one if you add it.

The badge on a member’s site links to their page on the directory. Cratis builds that page from the registry and live GitHub data, so the directory is the source of truth and the badge is a pointer to it. Badges are SVG images you can embed in a GitHub README, an email signature or anywhere else, and each one links back to its verification page.

A tier says what someone’s relationship to Cratis is. It isn’t a certification, and it doesn’t come with program benefits, discounts or referrals.

The directory

cast.cratis.io lists the people behind the play. For each Core and Partner member it renders a full profile in the Cratis design from their /cast.json.

That file is an open format with a published JSON Schema, and a site doesn’t need to be built with Cast to publish one. My own site, www.woksin.com, is a custom build that publishes /cast.json, and the directory turns it into my Cast profile. Contributors get a profile built from public GitHub data.

Every Cast site also publishes /resume.json in the JSON Resume format and an /llms.txt. People, the directory and AI agents read the same data, and nobody has to scrape a page to get it.

Today the Core tier is Einar Ingebrigtsen, Co-founder and CTO, and me, Co-founder and Chief Architect. There are no Partners yet. The directory already shows the verified Contributors.

Try it

Scaffold a site: npm create @cratis/cast@latest my-site, then fill in cast.yaml and push.
Browse the directory at cast.cratis.io.
See a full profile at cast.cratis.io/woksin, and press play.
Read the code at github.com/Cratis/Cast. It’s MIT licensed.

How to join

Contributor. Get a pull request merged in any public Cratis repository. The next build of the directory, and of your Cast site if you have one, shows the badge. There’s nothing to apply for.

Partner. Open a pull request that adds you to Registry/members.yaml, and say in it how you work with Cratis. We review it, may ask to talk first, and merge it only when we can vouch for the work. Not everyone who asks becomes a Partner. If you point the entry at a site that publishes /cast.json, the directory renders your full profile; without one it builds a profile from GitHub.

You can change your own entry or remove yourself at any time with another pull request. If a partnership ends, we remove the entry and say so in the pull request that does it. The registry README has the exact policy.

What’s next

The roadmap is public. Cratis/Cast#3 grows the Cast into a network: case studies modeled as events, with the client’s approval, and skills earned from evidence such as merged pull requests instead of self-declared tags. #4 runs the Cast on Cratis itself: the directory on Chronicle and Arc, modeled in Screenplay, with an MCP server for agents and cratis cast commands in the CLI. #5 collects the ideas further out.

If you build with Cratis, put your career on the stream. If you’ve shipped Cratis work with a client and want to be a Partner, open the pull request and tell us about it.

Not every rule needs a guarded read · Decisions that hold, Part 7

Thu, 05 Nov 2026 09:00:00 GMT

Decisions that hold · Part 07 of 11

The last five parts made one tool dependable. A command takes a read model, read protection is On, the read is folded fresh, and if an event the model folds arrives for that key before the commit, nothing is written. That is the right tool when the rule is about state on a key the command reads: the copies of one book, the loans of one member, one account’s withdrawals in one month.

It is the wrong tool for a lot of other rules. A guarded read can’t make an email unique, because two members registering the same address are two different keys. It doesn’t know which revision of a document the user was looking at when they pressed save. And it costs a fold of the key’s history on every command, which a rule you would rather repair afterwards doesn’t need to pay. This part goes through the alternatives: what each one guards, when it is too much, and the mistakes that make a rule stop holding without any error.

The examples assume read protection is On, as in new Cratis applications (see Part 2). Read protection, aggregates and the commands are part of Arc for .NET. Constraints, concurrency scopes and reactors are Chronicle, and those examples come in every Chronicle client that has them.

Start from the rule, not the tool

Arc’s guide to choosing how a rule holds has a flowchart. It reads well as a list of questions, asked in order, where the first yes picks the mechanism:

Ask in order. A guarded read is what is left when none of the other shapes fits.

The order matters. A constraint comes first because it needs no read at all: the kernel checks it inside every append, whoever writes. A rule that needs no stored state (“the title is not empty”) needs no guard either. Repair comes before every guard because when a short violation is acceptable, any guard is cost without benefit. The rest are guards of different shapes, and a guarded read is the general one at the bottom.

Each section below ends with two things: what the mechanism must never be relied on for, and when it is too much. “Never rely on” means the mechanism can fail silently: the command succeeds and the rule is broken.

A unique value: a constraint

A unique email is the classic check-then-act rule. A validator asks “is this email taken?”, the answer is no, and the command appends. Two requests with the same email both get “no”. Turning read protection On doesn’t change that. A guard watches the history of the key the command read, and the key here is the new member. A registration command has no member id yet, so each call starts a new member, and no read of one new member can see another.

The rule belongs in the kernel, as a constraint on the event:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Events.Constraints;

[EventType]
public record MemberRegistered([property: Unique(message: "A member with this email address is already registered.")] string Email, string Name);

// Requires io.cratis:chronicle 6.5.0 or later.
import io.cratis.chronicle.constraints.Unique
import io.cratis.chronicle.events.EventType

@EventType
data class MemberRegistered(
    @Unique(message = "A member with this email address is already registered.") val email: String,
    val name: String
)

// Requires io.cratis:chronicle 6.5.0 or later.
import io.cratis.chronicle.constraints.Unique;
import io.cratis.chronicle.events.EventType;

@EventType
record MemberRegistered(
    @Unique(message = "A member with this email address is already registered.") String email, String name) {}

defmodule MyApp.Events.MemberRegistered do
  use Chronicle.Events.EventType, id: "member-registered"

  defstruct [:email, :name]

  unique(:email, message: "A member with this email address is already registered.")
end

import { eventType, unique } from '@cratis/chronicle';

@eventType('member-registered')
class MemberRegistered {
    @unique(undefined, 'A member with this email address is already registered.') email = '';
    name = '';
}

The client registers the constraint when it connects, and the kernel keeps an index of the values. Every append of MemberRegistered is checked against that index inside the append, so of two registrations with the same email, one is written and the other is rejected, whatever the timing and whoever sends them. A value belongs to an event source: the same member may append its own email again, and a new email replaces its previous claim and frees the old one.

“Once per entity” is the same mechanism on the event type instead of a property. One library card per member:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Events.Constraints;

[EventType]
[Unique(name: "OneLibraryCard", message: "This member already has a library card.")]
public record LibraryCardIssued(string CardNumber, string HolderName);

// Requires io.cratis:chronicle 6.5.0 or later.
import io.cratis.chronicle.constraints.Unique
import io.cratis.chronicle.events.EventType

@EventType
@Unique(id = "OneLibraryCard", message = "This member already has a library card.")
data class LibraryCardIssued(val cardNumber: String, val holderName: String)

// Requires io.cratis:chronicle 6.5.0 or later.
import io.cratis.chronicle.constraints.Unique;
import io.cratis.chronicle.events.EventType;

@EventType
@Unique(id = "OneLibraryCard", message = "This member already has a library card.")
record LibraryCardIssued(String cardNumber, String holderName) {}

defmodule MyApp.Events.LibraryCardIssued do
  use Chronicle.Events.EventType,
    id: "library-card-issued"

  defstruct [:card_number, :holder_name]

  # Elixir supports a custom constraint name, but not a custom violation message.
  unique_event_type(name: "OneLibraryCard")
end

import { eventType, unique } from '@cratis/chronicle';

@eventType('library-card-issued')
@unique('OneLibraryCard', 'This member already has a library card.')
class LibraryCardIssued {
    cardNumber = '';
    holderName = '';
}

An Arc command that returns either event needs nothing else. When the kernel rejects the append, Arc turns the violation into a validation result with the reason constraintViolation and your message:

reason:  constraintViolation
message: A member with this email address is already registered.

A constraint has its own limits, and they are different from a guard’s. It is checked per event sequence and per namespace, so tenants in different namespaces can claim the same value. If the index update fails after an append is already durable, Chronicle logs it, and a later duplicate can pass until the index is rebuilt. A value that may change, or be given up, is released with a removal event marked [RemoveConstraint]. And it is a fixed rule about values: it can’t count, so “at most three loans” is not a constraint. Chronicle’s constraints documentation covers removal, grouping and scoping, and Einar’s post on how Chronicle constraints work explains why the check lives in the kernel.

Never rely on a validator that asks whether the value exists. Too much: read protection added only to make a value unique. It costs a fold and still doesn’t do it.

Rich behaviour: an aggregate

When one entity has many rules and state transitions, the rules can be easier to write as methods on the entity than as one validator per rule. A copy of a book that is lent to one member at a time, with more rules to follow:

using Cratis.Arc.Chronicle.Aggregates;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Concepts;

public record MemberId(Guid Value) : ConceptAs<Guid>(Value);

public record CopyId(string Value) : EventSourceId(Value);

[EventType]
public record CopyLent(MemberId Member);

[EventType]
public record CopyReturned();

public class Copy : AggregateRoot
{
    bool _lent;

    public async Task Lend(MemberId member)
    {
        if (_lent)
        {
            Failed("The copy is already lent.");
            return;
        }

        await Apply(new CopyLent(member));
    }

    public void OnCopyLent(CopyLent @event) => _lent = true;

    public void OnCopyReturned(CopyReturned @event) => _lent = false;
}

[Command]
public record LendCopy(CopyId Copy, MemberId Member)
{
    public async Task<AggregateRootCommitResult> Handle(Copy copy)
    {
        await copy.Lend(Member);
        return await copy.Commit();
    }
}

An aggregate carries its own guard. Arc rehydrates Copy from the copy’s events and notes the position of the log’s tail at that moment. The commit is guarded from that position, for the event types the aggregate handles:

guard copy-1: types=[CopyLent, CopyReturned], after <tail when the aggregate was rehydrated>

That is notation, not output. If another CopyLent lands on the copy between the rehydration and the commit, nothing is written. A new aggregate expects an empty history, so two commands that both create it can’t both succeed.

Return the result of Commit(). Failed(...) only records the failure; Commit() turns it into a result. A handler that awaits Commit() and throws the result away reports success for a copy that was already lent, and nothing reports that mistake.

Under On, an aggregate and a read model of the same event source in one command are refused with ReadAndAggregateOnSameSource, a 500, and ARCCHR0033 warns about it at build time. Decide from the aggregate’s own state instead. A read model of a different source, the member for example, is fine; each gets its own guard.

The aggregate’s guard covers its own event source only. Two aggregates for two keys each guard their own, which is not a rule across both; that takes two read models, as in Part 3. An aggregate also has no snapshots, so every command reads the key’s handled events again, and a key with a long history gets slower with every event.

Never rely on a Commit() whose result you don’t return. Too much: a read model for each invariant of an entity that has a dozen.

Two people editing: an explicit scope

Some conflicts are not about state the server reads. An editor loads a document at some revision, the user works on it for ten minutes, and presses save. The question is whether anyone changed it since the revision the user saw, and only the client knows that revision. A guarded read in the command reads the document fresh at save time, which is ten minutes too late.

The command takes the revision as input and returns an explicit concurrency scope built from it:

using Cratis.Arc.Commands.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

public record DocumentId(string Value) : EventSourceId(Value);

[EventType]
public record DocumentTitleChanged(string Title);

[Command]
public record RenameDocument(DocumentId Document, string Title, ulong ExpectedRevision)
{
    public EventsWithConcurrencyScopes Handle() => new(
        [new(Document, new DocumentTitleChanged(Title))],
        [new(Document, new ConcurrencyScope(
            new EventSequenceNumber(ExpectedRevision),
            EventSourceId: Document,
            EventTypes: [typeof(DocumentTitleChanged).GetEventType()]))]);
}

guard doc-1: types=[DocumentTitleChanged], after <ExpectedRevision>

The append fails if any DocumentTitleChanged for this document has a sequence number above ExpectedRevision. The caller gets a validation result with the reason concurrencyViolation. With two title changes at sequence numbers 0 and 1, and a client that last saw revision 0, the message reads:

Event source 'doc-1' has new events since the command read it: expected events up to sequence number 0, but it has events up to sequence number 1. Read it again and resubmit.

How the client learns the revision is up to your read model and query. Whatever you choose, the scope is only as strong as that number. The client chooses it, and a revision at or ahead of the log’s tail passes the check. For an editing conflict that is acceptable: a client that lies about its revision only overwrites a change its own user never saw. For a rule that protects someone else, such as an authorization or a limit, it is not. Resolve that revision on the server while handling the command, as Arc’s notes on exact scopes say; otherwise the caller chooses which version of the fact the command is checked against.

Two related shapes look similar and are not. concurrency: true on [EventSourceType], [EventStreamType] or [EventStreamId] narrows the default check, but that check reads the tail after Handle(), so it can never carry the revision the user saw. And if the same command also takes a read model of the document, the scope must cover what that read watches and must not be captured after it; otherwise the command is refused with ExplicitScopeDoesNotCoverReads, which ARCCHR0036 reports at build time.

Without Arc, the scope goes on the append itself, and your code reads the result. Chronicle’s own example is the other common scope: opening an account, where the append must fail if the account already exists. Each client asks the kernel for that as an explicit expectation that no matching event exists, not as a sequence number:

using Cratis.Chronicle;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

public static class ConcurrencyFirstAppendCheckSetup
{
    // Application-wide: every first append into a scope the optimistic strategy resolves is checked.
    public static void ConfigureChronicle(ChronicleOptions options) =>
        options.ConcurrencyOptions.CheckFirstAppendIntoAScope = true;
}

[EventType]
public record ConcurrencyFirstAppendPartitionOpened(string Name);

public class ConcurrencyFirstAppendPartitionService(IEventLog eventLog)
{
    // Per append: ask for the same check on one behavior, without turning it on everywhere.
    public async Task<bool> TryOpenPartition(EventSourceId accountId, string name)
    {
        var concurrencyScope = new ConcurrencyScopeBuilder()
            .ExpectingNoMatchingEvent()
            .WithEventSourceId(accountId)
            .WithEventType<ConcurrencyFirstAppendPartitionOpened>()
            .Build();

        var result = await eventLog.Append(
            accountId,
            new ConcurrencyFirstAppendPartitionOpened(name),
            concurrencyScope: concurrencyScope);

        return result.IsSuccess;
    }
}

import io.cratis.chronicle.IEventStore
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.eventSequences.AppendOptions
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder

@EventType
data class ConcurrencyFirstAccountOpened(val accountName: String = "")

/**
 * Opts in to the first-append check with [ConcurrencyScopeBuilder.withExpectsNoMatchingEvent].
 * The kernel rejects the append with a concurrency violation if an event already exists for
 * this event source, so two concurrent "open account" appends cannot both succeed.
 */
suspend fun openAccountOnce(store: IEventStore, accountId: String, accountName: String): Boolean {
    val concurrencyScope = ConcurrencyScopeBuilder()
        .withEventSourceId()
        .withExpectsNoMatchingEvent()
        .build()

    val result = store.eventLog.append(
        accountId,
        ConcurrencyFirstAccountOpened(accountName),
        AppendOptions(concurrencyScope = concurrencyScope)
    )

    return result.isSuccess
}

import io.cratis.chronicle.EventStore;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.AppendOptions;
import io.cratis.chronicle.eventSequences.AppendResult;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScope;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder;

import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
record ConcurrencyFirstAccountOpened(String accountName) {}

class EventsConcurrencyFirstAppendCheck {
    // Opts in to the first-append check with withExpectsNoMatchingEvent(). The kernel rejects the
    // append with a concurrency violation if an event already exists for this event source, so
    // two concurrent "open account" appends cannot both succeed.
    boolean openAccountOnce(EventStore store, String accountId, String accountName) {
        ConcurrencyScope scope = new ConcurrencyScopeBuilder()
            .withEventSourceId()
            .withExpectsNoMatchingEvent()
            .build();

        AppendResult result = EventLogJavaBridge.append(
            store.getEventLog(), accountId, new ConcurrencyFirstAccountOpened(accountName), new AppendOptions(null, scope));

        return result.isSuccess();
    }
}

defmodule MyApp.Events.ConcurrencyFirstAppendAccountOpened do
  use Chronicle.Events.EventType, id: "concurrency-first-append-account-opened"

  defstruct account_name: ""
end

defmodule MyApp.ConcurrencyFirstAppendAccountService do
  alias Chronicle.Events.ConcurrencyScope
  alias MyApp.Events.ConcurrencyFirstAppendAccountOpened

  # Per append: ask for the check on one behavior without changing the client's default.
  def open_account(account_id, account_name) do
    scope =
      ConcurrencyScope.expecting_no_matching_event(
        event_source_id: true,
        event_types: [ConcurrencyFirstAppendAccountOpened]
      )

    Chronicle.append(
      account_id,
      %ConcurrencyFirstAppendAccountOpened{account_name: account_name},
      concurrency_scope: scope
    )
  end
end
{Chronicle.Client,
  connection_string: "chronicle://localhost:35000",
  event_store: "my-store",
  concurrency: [default: :optimistic, check_first_append: true]}

import { eventType, EventSequenceNumber, IEventStore } from '@cratis/chronicle';
import { field } from '@cratis/fundamentals';

@eventType()
class ConcurrencyFirstAccountOpened {
    @field(String) readonly accountName: string;

    constructor(accountName: string) {
        this.accountName = accountName;
    }
}

class ConcurrencyFirstAppendService {
    constructor(private readonly store: IEventStore) {}

    async openAccount(accountId: string, accountName: string): Promise<void> {
        // EventSequenceNumber.beforeFirst expects that no event matching the scope exists yet.
        // The client sends it as the kernel's ExpectsNoMatchingEvent condition.
        const result = await this.store.eventLog.append(accountId, new ConcurrencyFirstAccountOpened(accountName), {
            concurrencyScope: {
                sequenceNumber: EventSequenceNumber.beforeFirst.value,
                eventSourceId: true
            }
        });
        if (!result.isSuccess) {
            throw new Error('The account already has events');
        }
    }
}

The C# and Elixir versions narrow the expectation to the opening event type, so other events on the account don’t count; the Kotlin, Java and TypeScript versions expect no event at all for the account. TypeScript writes it as EventSequenceNumber.beforeFirst, which the client sends as the same no-matching-event condition. The C# and Elixir versions also show the application-wide switch, CheckFirstAppendIntoAScope and check_first_append: true. An expected sequence number is not the same thing: the kernel rejects such an append only when a matching event sits after that position in the log, so expecting 0 lets an append through for an account whose one event is at position 0. In .NET, Append returns a violation in its AppendResult instead of throwing, and the other clients report it in their result too, so code that appends directly has to check it. Chronicle’s concurrency page covers narrowing by event type, stream and source type.

Never rely on concurrency: true as the guard for a decision, or on a client-supplied revision for a rule that protects someone else. Too much: a read model that folds the document to detect what a revision number already tells you.

A short raw stream: a stream decision

Part 4 covered rules that live in one routed stream, such as one account’s withdrawals in one month, with a per-stream read model. When the rule is only “has this fact happened in this stream?”, for example “has this month’s report been approved?”, there is no state to fold. A stream decision reads the raw events of the command’s own stream, captures the tail before reading, and returns a scope that fails the append if anything arrives in that stream after the read. The whole stream crosses the wire for each decision, so it suits short streams. Use either a per-stream model or a stream decision in a command, not both. Stream decisions in the Arc docs has the API.

Never rely on an injected read of the stream under Off. Too much: a read of the whole event source when only one period matters.

A rare violation you can repair

Some rules can be broken for a while. An airline may let a flight be briefly overbooked and cancel the extra reservations afterwards. Then the command needs no guard: it appends with the default check, and a reactor appends a correcting event when it sees the violation.

A reactor that returns an event has Chronicle append it, to the event source of the event it handled. The shape in each client:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reactors;

[EventType]
public record CopyReserved(string Isbn);

[EventType]
public record StockCheckRequested(string Isbn);

[EventType]
public record StockDecreased(string Isbn, int Quantity);

public class WarehouseReactor : IReactor
{
    [OnceOnly]
    public StockDecreased CopyReserved(CopyReserved @event, EventContext context) =>
        new(@event.Isbn, 1);

    [OnceOnly]
    public async Task<StockDecreased> StockCheckRequested(StockCheckRequested @event, EventContext context)
    {
        var available = await FetchCurrentStockAsync(@event.Isbn);
        return new StockDecreased(@event.Isbn, available);
    }

    Task<int> FetchCurrentStockAsync(string isbn) => Task.FromResult(0);
}

import io.cratis.chronicle.events.EventContext
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.observation.Reactor

@EventType
data class CopyReserved(val isbn: String)

@EventType
data class StockCheckRequested(val isbn: String)

@EventType
data class StockDecreased(val isbn: String, val quantity: Int)

@Reactor
class WarehouseReactor {
    // Return the event directly - it is appended to the event log using the EventSourceId from
    // the incoming event.
    fun copyReserved(event: CopyReserved, context: EventContext) =
        StockDecreased(event.isbn, 1)

    // A handler may suspend before returning its side-effect event.
    suspend fun stockCheckRequested(event: StockCheckRequested, context: EventContext): StockDecreased {
        val available = fetchCurrentStock(event.isbn)
        return StockDecreased(event.isbn, available)
    }

    private suspend fun fetchCurrentStock(isbn: String): Int = 0
}

import io.cratis.chronicle.events.EventContext;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.observation.Reactor;

@EventType
record CopyReserved(String isbn) {}

@EventType
record StockCheckRequested(String isbn) {}

@EventType
record StockDecreased(String isbn, int quantity) {}

@Reactor
class WarehouseReactor {
    // Return the event directly - it is appended to the event log using the EventSourceId from
    // the incoming event.
    StockDecreased copyReserved(CopyReserved event, EventContext context) {
        return new StockDecreased(event.isbn(), 1);
    }

    StockDecreased stockCheckRequested(StockCheckRequested event, EventContext context) {
        int available = fetchCurrentStock(event.isbn());
        return new StockDecreased(event.isbn(), available);
    }

    private int fetchCurrentStock(String isbn) {
        return 0;
    }
}

defmodule MyApp.Events.CopyReserved do
  use Chronicle.Events.EventType, id: "copy-reserved"

  defstruct [:isbn]
end

defmodule MyApp.Events.StockDecreased do
  use Chronicle.Events.EventType, id: "stock-decreased"

  defstruct [:isbn, :quantity]
end

defmodule MyApp.Reactors.WarehouseReactor do
  use Chronicle.Reactors.Reactor

  alias MyApp.Events.{CopyReserved, StockDecreased}

  @handles CopyReserved

  @impl true
  def handle(%CopyReserved{} = event, _context) do
    {:ok, %StockDecreased{isbn: event.isbn, quantity: 1}}
  end
end

import { EventContext, eventType, onceOnly, reactor } from '@cratis/chronicle';
import { field } from '@cratis/fundamentals';

@eventType()
class CopyReserved {
    @field(String) readonly isbn: string;

    constructor(isbn: string = '') {
        this.isbn = isbn;
    }
}

@eventType()
class StockDecreased {
    @field(String) readonly isbn: string;
    @field(Number) readonly quantity: number;

    constructor(isbn: string = '', quantity: number = 0) {
        this.isbn = isbn;
        this.quantity = quantity;
    }
}

@reactor()
class WarehouseReactor {
    // Returning an event from a handler appends it for you, targeting the triggering
    // event's own event source id, stream, and subject.
    @onceOnly()
    async copyReserved(event: CopyReserved, context: EventContext): Promise<StockDecreased> {
        return new StockDecreased(event.isbn, 1);
    }
}

The repair itself, in C#:

using Cratis.Chronicle;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.Reactors;

[EventType]
public record SeatReserved(Guid ReservationId);

[EventType]
public record ReservationCancelled(Guid ReservationId, string Reason);

public class OverbookingRepair(IEventStore eventStore) : IReactor
{
    const int Capacity = 100;

    [OnceOnly]
    public async Task<ReservationCancelled?> Reserved(SeatReserved @event, EventContext context)
    {
        var events = await eventStore.EventLog.GetFromSequenceNumber(
            EventSequenceNumber.First,
            context.EventSourceId);
        if (events.Any(_ => _.Content is ReservationCancelled cancelled && cancelled.ReservationId == @event.ReservationId))
        {
            return null;
        }

        var upToThis = events.Where(_ => _.Context.SequenceNumber <= context.SequenceNumber).ToList();
        var active = upToThis.Count(_ => _.Content is SeatReserved) - upToThis.Count(_ => _.Content is ReservationCancelled);

        return active > Capacity
            ? new ReservationCancelled(@event.ReservationId, "The flight was overbooked.")
            : null;
    }
}

The reactor skips a reservation it has already cancelled, then counts the active reservations on the flight up to and including the one it is handling: reservations minus cancellations, so a seat a passenger gave up earlier doesn’t count against a later reservation. It cancels this reservation if the flight is over capacity. Returning null records nothing. [OnceOnly] keeps the repair out of replays, but it doesn’t make delivery exactly-once, which is why the reactor checks for its own earlier cancellation first. A reactor is not a command, so read protection doesn’t apply to it.

What you give up is time. Between the violation and the repair the data is wrong, and anything that acted on it in between acted on wrong data. A repair can append a correcting event; it can’t take back an email that was sent or a boarding pass that was printed.

Never rely on the repair running before the harm. Too much: any guard on a rule you have decided to repair.

A hint

Some reads are not the rule at all. “This book has too many reservations” may be a soft limit, where going a little over is fine, or a message you show before the user submits while the real rule is enforced somewhere else. Then the read doesn’t need a guard, and under On you say so on the parameter:

using Cratis.Arc.Chronicle.ReadModels;
using Cratis.Arc.Commands;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections.ModelBound;
using FluentValidation;

public record Isbn(string Value) : EventSourceId(Value);

[EventType]
public record BookReserved();

[ReadModel]
public record Reservations(
    Isbn Id,
    [Increment<BookReserved>] int Count);

[Command]
public record ReserveBook(Isbn Isbn)
{
    public BookReserved Handle() => new();
}

public class ReserveBookValidator : CommandValidator<ReserveBook>
{
    public ReserveBookValidator([Unprotected("soft limit: a few reservations over ten are acceptable")] Reservations? reservations) =>
        RuleFor(command => command.Isbn)
            .Must(_ => reservations is not { Count: >= 10 })
            .WithMessage("This book has too many reservations.");
}

[Unprotected("why")] makes the read a plain snapshot. It costs no fold and guards nothing: with ten reservations the validator refuses the command, but a reservation that lands between the read and the commit doesn’t stop it. The reason is the part a reviewer reads, so write down why staleness is acceptable or what holds the rule instead. Put the attribute on the parameter rather than the read-model type, unless every command that reads the type can live with a stale value. When the hint is only for the screen, a query is simpler still, and the command doesn’t read the model at all.

Never rely on the hint as the rule. Too much: a guarded read to display a message.

External data

Some decisions use a value that isn’t in the event log at all: a price from a price list, a tax rate, an exchange rate. A command that sells a copy only while one is in stock, at the current price:

using Cratis.Arc.Commands;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections.ModelBound;
using FluentValidation;

public interface IPriceList
{
    Task<decimal> PriceOf(EventSourceId bookId);
}

public record QuotedPrice(decimal Amount);

public record BookId(string Value) : EventSourceId(Value);

[EventType]
public record CopyStocked();

[EventType]
public record CopySold(decimal Price);

public record CopiesInStock(
    EventSourceId Id,
    [Increment<CopyStocked>, Decrement<CopySold>] int Available);

[Command]
public record SellCopy(BookId Book)
{
    public async Task<QuotedPrice> Provide(IPriceList prices) => new(await prices.PriceOf(Book));

    public CopySold Handle(QuotedPrice price) => new(price.Amount);
}

public class SellCopyValidator : CommandValidator<SellCopy>
{
    public SellCopyValidator(CopiesInStock? stock) =>
        RuleFor(command => command.Book)
            .Must(_ => stock is { Available: > 0 })
            .WithMessage("No copies are left.");
}

Provide() fetches the price from the service before Handle() runs, and Handle() puts the amount into CopySold. The CopiesInStock parameter is guarded as usual: if another CopySold for the book lands between the read and the commit, the command is refused with CopiesInStock 'book-1' changed after SellCopy read it. and nothing is written. The price is not guarded. Read protection can’t see what IPriceList does, and a price that changes a millisecond after Provide() read it doesn’t stop the command. What you get instead is a record: the event carries the price the decision used, so nobody has to reconstruct it later from a service that has moved on.

Never rely on the external value being guarded. Too much: guarding state you don’t decide from.

What fails silently

Most mistakes with these mechanisms produce an error: a refused read, a 500 that names the problem, an analyzer warning. These eight don’t. The command succeeds, the tests pass one request at a time, and the rule is broken in production.

Mistake	What happens	Signal	Fix
A “does it exist?” check for a unique value	Both requests see “not taken” and both append	None	A constraint
A read under `Off` or `Measure`	A plain snapshot; `Measure` only reports what `On` would do	ARCCHR0011 at Info, under `Off` only	Turn read protection `On`
`Commit()` awaited, its result ignored	The command reports success though the aggregate failed	None	Return `Commit()`
No event source id on the command	A new random id on every call, so nothing ever conflicts	ARCCHR0002 only when there are two candidates	An `EventSourceId` property, or `ICanProvideEventSourceId`
A model keyed differently from where the facts go	The count stays at zero; the guard watches a stream nobody writes	None	Write the facts to the key you read
`concurrency: true` as the guard	The check reads the tail after `Handle()`, not before your read	ARCCHR0016 only next to exact scopes	A real guard
The first append into a new scope	No tail to compare with; by default two creations both succeed	None	`CheckFirstAppendIntoAScope`, or `ExpectingNoMatchingEvent()` on the scope
A writer that decides without a guard	Its decision is unprotected; yours catches its event only inside your own window	None	Guard every writer that decides on the rule, or use a constraint

The last row is the easiest to miss. A guard detects any matching event appended through the kernel, whoever wrote it, but it protects only the decision that carries it. An import job that appends without reading is checked by nothing. A rule holds fully only when every writer that decides on it is guarded, or when it is a constraint, which the kernel checks on every append. Arc’s pitfalls page has a code example for each row.

Rule shape	Use	Never rely on	Too much
A unique value (email, user name)	`[Unique]` on the event property	A validator asking “does it exist?”	Read protection only for uniqueness
Once per entity (one library card)	`[Unique]` on the event type	An “exists” check in a validator	A read over the whole history
State on one key (stock, loans)	A read-model parameter under `On`, the rule in a validator	The same validator under `Off`	A constraint: it can’t count
An editing conflict	An explicit scope with the client’s revision	`concurrency: true` alone	A read model that folds what a revision tells you
One short stream (approvals this month)	A per-stream model or a stream decision	An injected read under `Off`	A whole-source read when one period matters
Rich behaviour on one entity	An aggregate root that returns `Commit()`	Ignoring the result of `Commit()`	A read model for each invariant
A rare, repairable violation	The default append and a reactor	The repair running before the harm	Any guard
A hint (“too many reservations”)	A query, or `[Unprotected("why")]`	The hint as the rule	A guarded read
External data (a price, a tax rate)	`Provide()` fetches it, the event records it, a read-model parameter guards your own state	Assuming the external value is guarded	Guarding state you don’t decide from
:::

The scenarios in the Arc docs have each shape written out, including unique and once, the aggregate, the editing conflict and rules that need no guard. Script to stage, Part 5 goes deeper into constraints, scopes and aggregates in one application. The next part leaves Arc and builds the same guard with Chronicle’s decision reads and append conditions directly.

The examples need Arc 22.108.0 or later and Chronicle 19.68.0 or later.

Previous: Part 06 — Turning read protection on in an application that already runs

Turning read protection on in an application that already runs · Decisions that hold, Part 6

Tue, 03 Nov 2026 09:00:00 GMT

Decisions that hold · Part 06 of 11

Part 2 turned a validator’s read into a guard with one project setting, <CratisReadProtection>On</CratisReadProtection>. New applications from the Cratis templates have that setting already. An application that already runs is a different matter. It has commands that read through IReadModels, read models with joins, and services that append to the event log as a side effect, and under On each of those fails the command instead of running unguarded. Part 5 went through those refusals one by one. This part is about finding them before your users do.

Why On is not a flag you flip

Read protection is Off by default today. The next major version of Arc makes On the default (Cratis/Arc#3255), so an explicit <CratisReadProtection> setting also keeps the mode from changing under you when you upgrade. There are three reasons not to jump straight to On in existing code:

A protected command fails closed. It refuses a read it can’t guard, an immediate append and a read outside a parameter. Commands that work today would start returning 500s.
Moving a read from Handle() into a parameter or a validator changes where a rule lives and what it decides from. That’s a code change per command, not a setting.
A guarded read is a fresh fold of the key’s history, and costs more than a plain one. A team should choose that where a rule needs it.

So Arc has a third mode between the two.

The path

Step	Mode	What you do	What callers see
1	`Off`	Update the packages	Nothing changes
2	`Measure`	Set the mode, run the application and its tests	Nothing changes. Arc records what `On` would do
3	`Measure`	Read the report. Fix each refused read and immediate append, or mark a read advisory	The fixes are ordinary code changes
4	`On`, one project at a time	Switch the project and run its tests	Reads are guarded, reads Arc can’t guard fail the command, and validation errors block whatever severity the caller allows

Measure is set the same way as On, in the project that contains the commands or in a Directory.Build.props that covers several:

<PropertyGroup>
    <CratisReadProtection>Measure</CratisReadProtection>
</PropertyGroup>

Modes mix. A command can stay where it is while its project moves: [ReadProtection(ReadProtectionMode.Off)] (namespace Cratis.Arc.Commands) keeps one command Off in a Measure or On project, and [ReadProtection(ReadProtectionMode.On)] turns one command on ahead of the rest. A command-level [Unprotected] means Off for that command.

Read protection is part of Arc for .NET.

Callers see a difference only under On.

What Measure does and what it costs

Under Measure, reads, key lookups, concurrency scopes, results and status codes stay as they are under Off. A read model in a validator is still a plain read, and it still guards nothing. What Arc adds is a record of what On would have done with each command. A failure inside that measurement never fails the command.

It does three things:

On the request path, it classifies each parameter Arc resolves for the command: a read model On would guard, a read On would refuse, an advisory read, or a dependency Arc can’t see into. This is local reflection and costs nothing beyond that.
At the start of each command, it reads the event log’s tail once. This is the one awaited call Measure adds, and it has a timeout of 250 ms by default.
After the command, on a sample of commands (10 percent by default), a background scan looks for events written by someone else between that tail and the scan that match what the command read. These are the commands where On might have returned a 400.

The sample rate, the tail timeout, the scan timeout and the most events one scan looks at are runtime settings (MeasureSampleRate, MeasureTailTimeout, MeasureScanTimeout, MeasureScanLimit) in the ReadProtection configuration section. No benchmark of Measure is published. The cost has the shape above: one extra awaited call per command and background reads on a sample.

It’s best effort. A command whose tail read timed out, or whose scan was dropped, is reported as measurement_unavailable and counts as no evidence either way. The report is a set of hypotheses about On. It isn’t protection, and an application in Measure is exactly as unguarded as one in Off.

What the report looks like

Take an illustrative library application with four commands. BorrowBook is Part 2’s command: a validator that takes BookStock. The other three are written the way older code often is. PlaceHold reads BookStock through IReadModels in Handle(). ReturnBook calls a service that appends BookReturned through IEventLog. SendPickupNotice copies a shelf name from a read model that joins the shelf’s events. The code for each is in the next section.

Measure reports through three channels:

Channel	What you get
Metric	The counter `cratis.arc.read_protection.events` on the meter `Cratis.Arc.ReadProtection`, tagged `command`, `category`, `model` and `reason`
Trace	A span event `read-protection.plan` on the current activity, with the same tags
Log	A Warning once per command and category for `refused_read`, `immediate_append` and `scope_refusal`, and a periodic Information summary

Start with the counter, grouped by category and command. Run each of the four commands once under Measure, here in an Arc CommandScenario with a MeterListener on the meter, and every one succeeds, as it would under Off. The counter receives these observations:

`command`	`category`	`model`	`reason`
`BorrowBook`	`protected_read`	`BookStock`	`Would be protected`
`PlaceHold`	`refused_read`	`Cratis.Chronicle.ReadModels.IReadModels`	`IReadModels`
`ReturnBook`	`immediate_append`	`BookReturned`	`Would be refused while reads are protected`
`SendPickupNotice`	`refused_read`	`BookCard`	`Join`

The category that matters most is missing: matching_events_since_start, even though the BorrowBook run had another member’s BookBorrowed appended between its read and its commit. That category comes from the background scan, and a CommandScenario can’t run the scan. It has no host to start the scan queue, and its in-process event log can’t serve the scan’s reads, so a sampled command there reports measurement_unavailable instead. Races show up in the scan of a running application with real traffic, which is where Measure belongs, not only in your test suite.

ReturnBook also reported unknown_dependency for ILoanLedger, the service it calls. Every command in that run reported unknown_dependency for services resolved by the framework rather than by the command, too: Orleans.IGrainFactory from the in-process test kernel, Cratis.Chronicle.Sequences.RequestCausation and Cratis.Arc.Authorization.ICurrentPrincipalAccessor. They’re left out of the table. Which of these appear depends on the host, so when you group the counter, look at the dependencies that are yours. The command and model tags are full type names; the example’s types are in the global namespace, so they’re short here.

The log said the same thing for the three that need work, once each:

Read-protection hypothesis for PlaceHold: category=refused_read, model=Cratis.Chronicle.ReadModels.IReadModels, reason=IReadModels; this may need attention before turning On
Read-protection hypothesis for ReturnBook: category=immediate_append, model=BookReturned, reason=Would be refused while reads are protected; this may need attention before turning On
Read-protection hypothesis for SendPickupNotice: category=refused_read, model=BookCard, reason=Join; this may need attention before turning On

These are the categories you’ll meet most:

`category`	What it means	What to do
`protected_read`	`On` would guard this read	Nothing
`refused_read`	`On` would refuse this read. `reason` names the cause or the API	Fix it, or mark it advisory
`advisory_read`	The read is marked `[Unprotected]`. `reason` is your text	Check the reason still holds
`immediate_append`	The command appended through `IEventLog` at once, and `On` would refuse it	Return the event from `Handle()`
`unknown_dependency`	A service Arc can’t see into	Check what the service reads. A Chronicle read inside it is still refused under `On`
`redirect`	`On` would look the model up by a different key than today	Say which key you mean with `[LookUpBy]`
`matching_events_since_start`	Someone else wrote an event matching the read while the command ran. `On` might have returned `400`	A real race. These commands gain the most from `On`
`scope_refusal`	`On` would refuse the command’s explicit concurrency scope as narrower than the read, captured after it, or incomplete	Widen the scope or remove it
`measurement_unavailable`	A measurement couldn’t be taken. `reason` says why	Raise the timeouts, or ignore it
`mode_lowered`	The run-time cap lowered the declared mode	See the last section

The full list, including displacement, coarsened, self_write and conflict_today, is on Arc’s Adopting read protection page.

A quiet report isn’t a clean bill of health. Measure doesn’t currently report everything On would do differently: it can’t tell from its observations which concurrency scopes were explicit and which were derived, and it doesn’t see a nested command reading an event its outer command has staged but not committed. The absence of a category means only that Measure didn’t observe it. The background scan runs on a sample, so a race that happened on an unsampled command isn’t in the report either.

Fixing what it finds

The examples use Isbn, MemberId, BookStock and the book events from Part 2, and one new event:

using Cratis.Chronicle.Events;

[EventType]
public record HoldPlaced(MemberId Member);

A read through IReadModels

PlaceHold lets a member queue for a book when no copy is on the shelf. The rule lives in Handle(), and the read goes through IReadModels:

using Cratis.Arc.Commands.ModelBound;
using Cratis.Arc.Validation;
using Cratis.Chronicle.ReadModels;
using Cratis.Monads;

[Command]
public record PlaceHold(Isbn Isbn, MemberId Member)
{
    public async Task<Result<HoldPlaced, ValidationResult>> Handle(IReadModels readModels)
    {
        var stock = await readModels.GetInstanceById<BookStock>(Isbn);
        if (stock is { Available: > 0 })
        {
            return ValidationResult.Error("A copy is on the shelf. Borrow it instead.");
        }
        return new HoldPlaced(Member);
    }
}

Under On, Arc refuses the GetInstanceById call with a 500, because a read through IReadModels has no position and can’t guard the append. The fix is the shape from Part 2. The read becomes a constructor parameter of a validator, and the rule moves with it:

using Cratis.Arc.Commands;
using Cratis.Arc.Commands.ModelBound;
using FluentValidation;

[Command]
public record PlaceHold(Isbn Isbn, MemberId Member)
{
    public HoldPlaced Handle() => new(Member);
}

public class PlaceHoldValidator : CommandValidator<PlaceHold>
{
    public PlaceHoldValidator(BookStock? stock) =>
        RuleFor(command => command.Isbn)
            .Must(_ => stock is not { Available: > 0 })
            .WithMessage("A copy is on the shelf. Borrow it instead.");
}

Under On, that BookStock is folded fresh and guards the append. A copy returned between the read and the commit makes the command fail with ReadChanged instead of placing a hold on a book that is on the shelf.

An append that happens at once

ReturnBook doesn’t append through its return value. It calls a service, and the service appends:

using Cratis.Arc.Commands.ModelBound;
using Cratis.Chronicle.EventSequences;

public interface ILoanLedger
{
    Task RecordReturn(Isbn isbn, MemberId member);
}

public class LoanLedger(IEventLog eventLog) : ILoanLedger
{
    public Task RecordReturn(Isbn isbn, MemberId member) =>
        eventLog.Append(isbn, new BookReturned(member));
}

[Command]
public record ReturnBook(Isbn Isbn, MemberId Member)
{
    public Task Handle(ILoanLedger ledger) => ledger.RecordReturn(Isbn, Member);
}

IEventLog.Append writes at once, before the command commits. If the command’s guard then conflicts, nothing rolls that event back, so under On Arc refuses it. The build doesn’t see this one. Arc’s analyzers warn when Handle() takes IEventLog itself (ARCCHR0007), but here the append is behind an interface, and it compiled without a diagnostic. Measure saw it at run time, as immediate_append with the event type, next to unknown_dependency for ILoanLedger.

The fix is to return the event, so it’s committed with the command:

using Cratis.Arc.Commands.ModelBound;

[Command]
public record ReturnBook(Isbn Isbn, MemberId Member)
{
    public BookReturned Handle() => new(Member);
}

When the append has to stay in a service, IEventLog.Transactional.Append adds the event to the command’s unit of work instead of writing it at once, and On accepts that.

A read model with a join

SendPickupNotice tells a member where to collect a book, and takes the shelf’s name from a read model that joins the shelf’s events:

using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections.ModelBound;
using Cratis.Concepts;

public record ShelfId(Guid Value) : ConceptAs<Guid>(Value);

[EventType]
public record BookShelved(ShelfId Shelf);

[EventType]
public record ShelfNamed(string Name);

[EventType]
public record PickupNoticeSent(MemberId Member, string Shelf);

[ReadModel]
public record BookCard(
    Isbn Id,
    [SetFrom<BookShelved>] ShelfId Shelf,
    [Join<ShelfNamed>(on: nameof(Shelf), eventPropertyName: nameof(ShelfNamed.Name))] string ShelfName);

using Cratis.Arc.Commands.ModelBound;

[Command]
public record SendPickupNotice(Isbn Isbn, MemberId Member)
{
    public PickupNoticeSent Handle(BookCard? card) => new(Member, card?.ShelfName ?? "Front desk");
}

A joined model folds events from more than one key, so a guard on the book’s key can’t cover it, and On refuses the read. This one the build flags already in Measure: ARCCHR0024 warns that BookCard has joins or children, “so protection is not proven”.

There are two honest answers. If a decision depends on the joined data, read the parts as separate models, each keyed by its own entity, and look each up by the command property that holds its key with [LookUpBy] (Part 3 does that for a book and a member). Here the shelf name is only copied into the notice, and a stale name is acceptable, so the read can say so:

using Cratis.Arc.Chronicle.ReadModels;
using Cratis.Arc.Commands.ModelBound;

[Command]
public record SendPickupNotice(Isbn Isbn, MemberId Member)
{
    public PickupNoticeSent Handle([Unprotected("copied as of read; may be stale")] BookCard? card) =>
        new(Member, card?.ShelfName ?? "Front desk");
}

An [Unprotected] read is a stored read that guards nothing, on purpose. Measure then reports it as advisory_read with your reason, so the reasons stay visible in the same report. Use it for context, never to silence a refusal you don’t understand.

The other categories

redirect: under Off and Measure, Arc looks up a read-model parameter by the command’s event source id. Under On, it uses the one command property whose type is the model’s Id type, when there is one. A redirect means those two disagree for this command, so On would read a different instance. Put [LookUpBy(nameof(Property))] (namespace Cratis.Arc.Commands) on the parameter, naming the command property that holds the key you mean. It applies in every mode, so the lookup no longer changes when the project moves to On.
refused_read with other reasons: a reducer with an event filter or constructor dependencies, children, a key taken from an event property, Pinned generation delivery. Part 5 has the table of reasons and fixes.
unknown_dependency: look inside the service. If it calls an HTTP API or another database, there’s nothing to fix, and that read stays outside the guard under On too. If it reads Chronicle, through IReadModels for example, Measure records only the service, but On still refuses the read when the command runs. Move that read into a parameter of the command, as with PlaceHold.

Switching a project to On

When a project’s report shows only protected_read, advisory_read with reasons you still agree with, and dependencies you know about:

Set <CratisReadProtection>On</CratisReadProtection> for that project.
Build, and fix ARCCHR0024 (a read model shape that can’t be protected), ARCCHR0028 (a Chronicle read that isn’t proven protected) and ARCCHR0033 (an aggregate and a read of the same source). Raise them to errors in projects you’ve moved.
Run the project’s tests. Arc’s CommandScenario picks the in-process event log that supports guarded reads from the command’s mode, so the scenarios run the commands under On. Part 9 is about testing the race itself.
Exercise every command at least once. Refusals happen when a command runs, not at startup, and a command nobody ran under Measure has no report.

From Arc 22.108.0, a command declared On also blocks on Error and Unknown validation results whatever X-Allowed-Severity the caller sends (Part 5 explains why). Measure has no category for this, so look for clients that send an allowed severity before you switch.

Under On, a validator with read-model parameters has to be registered by convention, so Arc can build a fresh one per command. A validator registered by hand as scoped, singleton, a factory or an instance is refused.

With the fixed commands in an On project, PlaceHold places a hold when no copy is on the shelf and fails with the rule’s message when one is. With a BookReturned appended between its read and its commit, it fails with concurrencyViolation and ReadChanged, and nothing is written. ReturnBook commits its event with the command, and SendPickupNotice runs with its advisory read.

Backing out at run time

If something goes wrong after a deployment with On, operations can lower the mode without a build:

{
  "ReadProtection": {
    "MaximumMode": "Measure"
  }
}

`MaximumMode`	Effect
`On`, missing or invalid	The compiled modes apply
`Measure`	Commands compiled as `On` run as `Measure`
`Off`	Commands compiled as `On` or `Measure` run as `Off`

The cap only lowers. It never raises a mode that wasn’t compiled in, so a missing or mistyped value can’t switch anything on. At startup, Arc logs a Warning for each command it lowers, in this form (the command name here is an example):

Read protection for Library.PlaceHold is lowered from On to Measure by ReadProtection:MaximumMode.

Measure reports mode_lowered for those commands too. The cap lowers the guard, not the severity floor: that follows the declared mode, so a command declared On keeps blocking on Error under any cap. Only changing the declared mode to Off or Measure gives callers their threshold back. There, callers filter as before, so declare [BlockOnValidationSeverity(ValidationResultSeverity.Error)] on a command whose validators must not be skipped. With the cap set, the commands run unguarded, so use it to get through an incident while you fix the code, and then remove it. Measure and a lowered cap both leave an application that looks protected and isn’t. Check that production configuration has no cap you didn’t set on purpose.

Arc’s Adopting read protection has the full category list and the refusal reasons, and Pitfalls covers what still fails silently once a project is On. Why protection is opt-in gives the reasons Off is the default.

The next part steps back from read protection. Not every rule needs a guarded read: uniqueness is a constraint, rich behaviour is an aggregate, and some rules are cheaper to repair than to guard.

Read protection as described here needs Arc 22.108.0 or later and Chronicle 19.68.0 or later.

Previous: Part 05 — When Arc says no

When Arc says no · Decisions that hold, Part 5

Fri, 30 Oct 2026 09:00:00 GMT

Decisions that hold · Part 05 of 11

The previous parts were about getting a decision to hold: a guarded read of one entity, of two, and of one month. Each ended at the same place, a command that Arc refuses when the state it decided from has changed. This part is about the refusals themselves. Read protection fails closed: when it can’t guard a read exactly, it refuses the command instead of running it unguarded. That leaves the caller with two kinds of no, and they need different handling.

There’s also a no that a command doesn’t give when it should. Under Off, a stale read can approve a borrow, and so can a caller who asks Arc to ignore the validator’s errors. The last section covers both, and what On changes.

The examples assume read protection is On, as in new Cratis applications (see Part 2). Read protection is part of Arc for .NET; the frontend code below is Arc’s TypeScript client.

Two kinds of no

	Status	What it means	What to do
The read changed	`400`	An event that the command’s read depends on arrived before it committed. Nothing was written	Read again, and let the user decide again
The code can’t be guarded	`500`	The command reads or appends something Arc can’t put under a guard. Nothing was written	Change the code. Submitting again fails the same way

Neither one is retried for you. Arc and Chronicle don’t re-run the command. A 400 means the state the decision rested on has moved, and a blind resubmit of the same decision would undo the point of the guard. A 500 is a configuration error, and nothing about the next request will be different.

The two families of refusal, and what each asks of the caller.

The read changed

Part 2 showed the common one. Two members borrow the last copy, and the second commit is refused:

BookStock 'isbn-1' changed after BorrowBook read it. Nothing from this command was written; submit it again.

The validation result carries the reason concurrencyViolation, the detail ReadChanged, and a state object naming the model and the key, {"readModel":"BookStock","key":"isbn-1"}. It has no members. It isn’t about any field of the command, and nothing the user typed was wrong.

The second 400 comes from the read, not the commit:

BookStock 'isbn-1' could not be read completely. Nothing was written; submit it again.

That’s ReadIncomplete. Before each attempt at a guarded read, Chronicle notes the position of the log and of the last event of the model’s types for that key, and then folds. If the fold doesn’t reach that last event, it tries again. It makes up to three attempts in total, and if the last one still falls short, the read fails and the command stops. Events that arrive during the fold are a different case: they make Chronicle fold again too, but the last attempt returns a guarded read, and a conflict shows up at commit as ReadChanged. A ReadIncomplete result has the reason concurrencyViolation too, with the detail ReadIncomplete and no state. Submitting again is safe for the same reason as with ReadChanged: the next request reads fresh state and runs every rule again.

You get one result per guarded read that changed. A command whose validator reads both BookStock and a BookTitle model of the same book guards both, and a concurrent retitle produces a ReadChanged for each of them, BookStock included, although BookStock doesn’t fold titles. Reads of one event source merge into one guard that covers the event types of all of them, so an event that conflicts with the guard conflicts with every read in it. That’s one reason to keep context you don’t decide from out of the guard, as the section on advisory reads below shows.

The message doesn’t name the event that caused the conflict. Chronicle doesn’t report it yet.

Commands that opted in on their own with [ProtectedDecision], outside On, word it differently and carry no detail: BookStock 'isbn-1' changed after it was read. Read it again and resubmit. Branch on the reason, not on the text.

Handling it in the UI

Arc’s frontend puts the same fields on each validation result: reason, reasonDetail, state, members and message. The only reason whose message is meant for the user is rule, a rule you wrote. A concurrencyViolation message is developer text in English. A UI decides from reason:

import { ICommandResult } from '@cratis/arc/commands';
import { ValidationResultReason } from '@cratis/arc/validation';

export type Outcome = 'done' | 'readAgain' | 'rejected' | 'failed';

export function outcomeOf(result: ICommandResult<unknown>): Outcome {
    if (result.isSuccess) return 'done';
    const reasons = result.validationResults.map(_ => _.reason);
    if (reasons.includes(ValidationResultReason.ConcurrencyViolation)) return 'readAgain';
    if (reasons.includes(ValidationResultReason.Rule)) return 'rejected';
    return 'failed';
}

Every concurrencyViolation asks for the same thing, whichever guard produced it: read again and decide. reasonDetail says which kind it was, ReadChanged or ReadIncomplete, and is a plain string with no TypeScript constant. Use it for wording or telemetry if you need to. reason is an open set. Arc’s own guidance is to treat an unfamiliar value like rule; this handler deliberately sends it to failed and shows generic copy, because it can’t know that the message was written for a user.

In a React form, the same function runs from CommandForm’s onFailed callback, which receives the whole command result:

import { useState } from 'react';
import { CommandForm } from '@cratis/arc.react/commands';
import { ValidationResultReason } from '@cratis/arc/validation';
import { BorrowBook } from './BorrowBook';
import { outcomeOf } from './outcome';

type Props = { isbn: string; member: string; onReadAgain: () => void };

export function BorrowButton({ isbn, member, onReadAgain }: Props) {
    const [notice, setNotice] = useState('');
    return (
        <CommandForm
            command={BorrowBook}
            initialValues={{ isbn, member }}
            onSuccess={() => setNotice('Borrowed.')}
            onFailed={result => {
                switch (outcomeOf(result)) {
                    case 'readAgain':
                        onReadAgain();
                        setNotice('This book changed while you were looking. Check the stock and borrow again if you still want it.');
                        break;
                    case 'rejected':
                        setNotice(result.validationResults
                            .filter(_ => _.reason === ValidationResultReason.Rule)
                            .map(_ => _.message)
                            .join(' '));
                        break;
                    default:
                        setNotice('The library could not lend this book right now.');
                }
            }}>
            <button type="submit">Borrow</button>
            <p role="status">{notice}</p>
        </CommandForm>
    );
}

BorrowBook is the proxy Arc generates for the command. onReadAgain is the page’s own: it reloads whatever showed the stock, so the user decides from the new value. The rule’s message, “No copies of this book are available.”, is the user’s to see, and only rule messages are shown. Its result names the isbn member, so a form with an isbn field shows it there. A ReadChanged names no member, so CommandForm never attaches it to a field.

Validation all the way down covers results, reasons and severities in general. The only thing read protection adds is ReadChanged and ReadIncomplete under a reason a UI already had to handle.

The code can’t be guarded

A 500 from read protection means the command reads or appends something that Arc can’t fold fresh and put under a guard. Under Off the same code runs, unguarded. Under On it’s refused before anything is written, and the message names the read and the fix. For a read-model parameter whose model has a shape Chronicle can’t guard, it looks like this:

BorrowBook reads 'details' (BookDetails) with joins or children, so read protection cannot guard it. If it is only context, mark it [Unprotected("why")]. Otherwise read the parts as separate models.

The common causes, and what to change:

Refusal	Cause	Fix
`ReadCannotBeProtected`	A read-model parameter whose model has joins or children	Read the parts as separate models
`ReadCannotBeProtected`	A read-model parameter keyed by an event property	Append a fact to the entity the model is keyed by, or use a constraint
`ReadCannotBeProtected`	A model built by a reducer with an event filter or constructor dependencies	Remove the filter or the dependencies, or read an unfiltered projection
`ReadCannotBeProtected`	A projection with Pinned generation delivery, or a model of another event sequence	Use Compatibility delivery; read a model of the event log
`ReadCannotBeProtected`	An `IMongoCollection<T>` of a Chronicle-backed model	Take the read model as a parameter instead
`AmbiguousReadModelLookup`	Several command properties have the model’s `Id` type	Name one with `[LookUpBy(nameof(Property))]` on the parameter
`ReadRefusedWhileReadsAreProtected`	A read through `IReadModels`, `IEventStore`, `IEventLog` or an event sequence inside the command	Take the read model as a parameter, use `IDecisionReads.Get` in `Provide()`, or mark the method `[Unprotected("why")]`
`ImmediateAppendWhileReadsAreProtected`	`IEventLog.Append`, `AppendMany`, `Revise` or `Redact`, which write at once	Return the event from `Handle()`, or stage it with `IEventLog.Transactional.Append`
`ReadAndAggregateOnSameSource`	An aggregate and a guarded read-model parameter of the same event source in one command	Decide from the aggregate’s state, read another source, or mark the read `[Unprotected("why")]` if it’s only context
`DiscoverableValidatorRefusedInProtectedDecision`	A validator registered by hand as scoped, singleton, a factory or an instance	Let convention discovery register it

An immediate append is refused for a reason that has nothing to do with reads: it’s written before the commit and stays if the commit conflicts, so it can’t be part of a guarded decision. The validator row is the one Part 2 mentioned. Under On, Arc builds a fresh validator for every command so its read-model parameters belong to that command, and a validator the container hands out from another registration is refused:

Discoverable validator 'BorrowBookValidator' cannot run while read protection is On because Arc did not construct it for this invocation. Let convention discovery register it as transient; do not use a scoped, singleton, factory or instance registration.

Any of the read-model-parameter rows can also be a read you only use as context; then mark it [Unprotected("why")], as the next section shows. An IMongoCollection<T> can’t be marked that way: the collection itself is refused, so take the read model as an [Unprotected("why")] parameter instead. Arc’s refusals page has the full list, including scopes, nested commands and declarations.

A 500 carries its message in exceptionMessages, not in validationResults. In Development that’s the text above. Elsewhere, for model-bound commands, ArcOptions.ExposeExceptionDetails is false by default, and the caller gets this instead:

An internal error occurred while processing the request. See server logs for details.

The full message goes to the server log, and the result keeps its correlationId, which is what you search the log for. These refusals don’t depend on timing: they come back the first time the command runs, so a test or a run in development finds them.

Declaring a read advisory

Some reads are context, not part of the decision. Say the rejection message should name the book. The title comes from its own read model of the same book:

using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections.ModelBound;

[EventType]
public record BookTitled(string Title);

[ReadModel]
public record BookTitle(Isbn Id, [SetFrom<BookTitled>] string Title);

The validator takes it beside BookStock. A title that’s a moment stale changes no decision, so the read is declared advisory:

using Cratis.Arc.Chronicle.ReadModels;
using Cratis.Arc.Commands;
using Cratis.Arc.Commands.ModelBound;
using FluentValidation;

[Command]
public record BorrowBook(Isbn Isbn, MemberId Member)
{
    public BookBorrowed Handle() => new(Member);
}

public class BorrowBookValidator : CommandValidator<BorrowBook>
{
    public BorrowBookValidator(
        BookStock? stock,
        [Unprotected("only words the message; a stale title changes no decision")] BookTitle? title) =>
        RuleFor(command => command.Isbn)
            .Must(_ => stock is { Available: > 0 })
            .WithMessage($"No copies of {title?.Title ?? "this book"} are available.");
}

Without the attribute, BookTitle would be guarded like BookStock, and a retitle that lands between the read and the commit would refuse the borrow with two ReadChanged results. With it, the title is a plain read that guards nothing, and the retitle doesn’t conflict. BookStock is still guarded.

[Unprotected("why")] is in Cratis.Arc.Chronicle.ReadModels. Where you put it decides what it covers:

Place	Covers
A parameter	That parameter. The common case
A read-model type	Every parameter of that type, in every command
A `Handle()` or `Provide()` method	The method body only: `IReadModels` and other raw reads inside it, not the method’s parameters
A command	The whole command runs as `Off`

The reason is a sentence for a reviewer, and it goes to telemetry. Don’t use the attribute to silence a refusal you don’t understand. A refusal means Chronicle couldn’t guard that read exactly, and marking it advisory makes the rule depend on a stale value again.

A yes that should have been a no

Everything so far is about On. Under Off, the default, there are two ways a command approves something it should refuse, and neither one shows up as an error.

The first is the snapshot read from Part 2. The validator checks Available > 0 against a value that’s already stale, the rule passes, and the commit doesn’t check the read.

The second has nothing to do with concurrency. Validation results have a severity, and Arc lets the caller choose which severities block. A model-bound command reads it from the X-Allowed-Severity header. With a threshold, only results above it block, and 3 is Error, with nothing above it. Any HTTP client can send the header, and Arc’s TypeScript client sends it when you pass a severity to execute():

import { ValidationResultSeverity } from '@cratis/arc/validation';
import { BorrowBook } from './BorrowBook';

export async function borrowIgnoringErrors(isbn: string, member: string) {
    const borrow = new BorrowBook();
    borrow.isbn = isbn;
    borrow.member = member;
    return await borrow.execute(ValidationResultSeverity.Error);
}

For a book whose last copy is out, Arc drops the validator’s “No copies of this book are available.”, Handle() runs, and BookBorrowed is appended for a book with no copy on the shelf. This is documented behaviour: severities are there for warnings a user can confirm, and Arc’s severity filtering page says not to use them for integrity. A command can declare a floor the caller can’t lower with [BlockOnValidationSeverity], but only if somebody remembers to add it to every command with a rule that must hold.

Under On, both are closed, the second from Arc 22.108.0. The read is fresh and guarded, so a stale value gives a 400 ReadChanged instead of a yes. And a command that declares read protection On, in the project or on the command, gets an Error floor: Error and Unknown results block whatever threshold the caller sends, and the caller can only let warnings and information through, which is what the threshold is for. The floor follows the declaration, so lowering ReadProtection:MaximumMode at runtime removes the guard but not the floor. A command with its own [BlockOnValidationSeverity] keeps that policy instead, so a Warning floor still blocks warnings. Commands declared Off or Measure, without such an attribute, keep the caller’s threshold as before.

The threshold applies to the results of filters, validators and Provide(). The ReadChanged from the commit isn’t one of them, so no threshold turns it into a success.

Two ways a command says yes under Off, and what On does with each. The Error floor under On needs Arc 22.108.0 or later.

The build tells you first

Most 500s can be seen in the code, and Arc’s analyzers report them at build time. This command reads the stock through IReadModels instead of taking it as a parameter:

using Cratis.Arc.Commands.ModelBound;
using Cratis.Chronicle.ReadModels;

[Command]
public record BorrowBookThroughReadModels(Isbn Isbn, MemberId Member)
{
    public async Task<BookBorrowed> Handle(IReadModels readModels)
    {
        await readModels.GetInstanceById<BookStock>(Isbn);
        return new(Member);
    }
}

It compiles, with a warning:

warning ARCCHR0028: Command 'BorrowBookThroughReadModels' calls 'GetInstanceById' while read protection is On; this read is not proven protected. Take a read model as a parameter, use IDecisionReads.Get in Provide, or mark the method [Unprotected("why")].

At runtime it’s refused with ReadRefusedWhileReadsAreProtected, a 500 with the same three fixes. The analyzers that matter here:

Diagnostic	Severity	Reports
ARCCHR0024	Warning	A read-model parameter whose shape can’t be protected
ARCCHR0028	Warning	A Chronicle read under `On` that isn’t proven protected
ARCCHR0033	Warning	An aggregate and a read-model parameter of the same source
ARCCHR0023	Warning	A read-model lookup key that isn’t proven
ARCCHR0029	Error	Conflicting read-protection declarations on one command
ARCCHR0031	Error	An invalid `[LookUpBy]`
ARCCHR0037	Error	A per-stream read model the command isn’t routed to
ARCCHR0011	Info	Under `Off`, a plain read model in a command that produces events
ARCCHR0012	Info (Warning under `On`)	An immediate append that bypasses a protected decision

The diagnostics say “not proven” for a reason. They see what’s visible in the code, and some refusals depend on how a model is registered at runtime, so a clean build doesn’t mean no command will be refused. Info diagnostics are easy to miss in a build log. Raise ARCCHR0011 in a project with commands still under Off. ARCCHR0012 only fires for commands that are On, use decision reads or carry [ProtectedDecision], and raising it makes the [ProtectedDecision] and decision-read cases warnings too, so an immediate append there shows up at build time rather than at runtime:

[*.cs]
dotnet_diagnostic.ARCCHR0011.severity = warning
dotnet_diagnostic.ARCCHR0012.severity = warning

With warnings treated as errors, each of them then fails the build instead of scrolling past.

400 with ReadChanged: read again and show the user the new state. Don’t put an error on a field, and don’t resubmit automatically.
400 with ReadIncomplete: submit again. The read didn’t reach that key’s latest events in three attempts.
500 with ReadCannotBeProtected: reshape the model, read the parts separately, or mark the read [Unprotected("why")] if it’s only context.
500 with ReadRefusedWhileReadsAreProtected: take the read model as a parameter, or use IDecisionReads.Get in Provide().
500 with ImmediateAppendWhileReadsAreProtected: return the event from Handle(), or use IEventLog.Transactional.Append.
500 from a validator: let convention discovery register it.
Production shows “An internal error occurred”: the message is redacted outside Development. Find the correlationId in the server log.
A rule must hold whatever the caller sends: run the command under On (Arc 22.108.0 or later). Under Off or Measure, add [BlockOnValidationSeverity] to it.

The refusals page lists every refusal with its message, Reads explains what each kind of read becomes, and the frontend’s command result page covers reasons and details. The next part is about getting an application that already runs from Off to On, by finding these refusals with Measure before they reach a user.

The examples need Arc 22.108.0 or later and Chronicle 19.68.0 or later.

Previous: Part 04 — A limit for one account and one month

A limit for one account and one month · Decisions that hold, Part 4

Wed, 28 Oct 2026 09:00:00 GMT

Decisions that hold · Part 04 of 11

The previous two parts guarded a read model keyed by an entity: a book, a member. The guard watched that entity’s whole history for the event types the model folds. That’s the right boundary when the rule is about the whole entity. Many rules aren’t. A bank account may allow at most 5000 in withdrawals per calendar month. The rule depends on this account and this month, and nothing else.

Neither of the obvious read models fits it. A model keyed by the account folds every month into one total, and a guard on the account’s withdrawals makes every withdrawal conflict with any concurrent one, whatever month it’s in. A model keyed by the month collides across accounts. What the rule needs is the account as the key, with the fold limited to one month.

Chronicle has a place for that already. An event source definition can declare named streams, and an event appended to an account can carry a stream type (Transactions) and a stream id (2026-10). A read model can be declared on one such stream. Arc then reads it for the stream the command is routed to, and the guard it builds covers that stream only.

Declare the stream on the read model

The examples assume read protection is On, as in new Cratis applications (see Part 2). Read protection is part of Arc for .NET. The definition, the event and the read model:

using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSources;
using Cratis.Chronicle.Projections.ModelBound;
using Cratis.Chronicle.ReadModels;

[EventSource("BankAccount")]
[EventStream("Transactions")]
public class BankAccountEventSource : IEventSource;

public record AccountId(string Value) : EventSourceId(Value);

[EventType]
public record MoneyWithdrawn(decimal Amount);

[ReadModel, EventStream<BankAccountEventSource>("Transactions")]
public record MonthlyWithdrawals(
    AccountId Id,
    [AddFrom<MoneyWithdrawn>(nameof(MoneyWithdrawn.Amount))] decimal Total)
{
    public static async Task<MonthlyWithdrawals?> ForMonth(AccountId account, EventStreamId month, IReadModels models)
    {
        var instance = await models.GetInstanceById<MonthlyWithdrawals>(account, month);
        return instance is null ? null : await models.Release(instance);
    }
}

There are two attributes with the same name here, and they do different things. [EventStream("Transactions")] on BankAccountEventSource declares that bank accounts have a Transactions stream. [EventStream<BankAccountEventSource>("Transactions")] on the read model, from Cratis.Chronicle.ReadModels, says that MonthlyWithdrawals is folded from that one stream of that definition.

The model keeps the account as its Id. The month isn’t part of the key; it selects which stream the fold reads. Declaring the stream also makes the model passive: Chronicle doesn’t keep a stored instance per account that could accumulate several months, and folds the requested stream when it’s read. ForMonth is a query for screens, and I’ll come back to it below.

Route the command to the month

The command and the validator:

using Cratis.Arc.Chronicle.Commands;
using Cratis.Arc.Commands;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Chronicle.Events;
using FluentValidation;

[Command]
[EventSource<BankAccountEventSource>("Transactions")]
[EventStreamId("{Month}")]
public record Withdraw(AccountId Account, string Month, decimal Amount)
{
    public MoneyWithdrawn Handle() => new(Amount);
}

public class WithdrawValidator : CommandValidator<Withdraw>
{
    public WithdrawValidator(MonthlyWithdrawals? month) =>
        RuleFor(command => command.Amount)
            .Must(amount => (month?.Total ?? 0m) + amount <= 5000m)
            .WithMessage("The monthly withdrawal limit is 5000.");
}

[EventSource<BankAccountEventSource>("Transactions")] routes the command’s events to the definition’s Transactions stream, and [EventStreamId("{Month}")] takes the stream id from the command’s Month property. AccountId derives from EventSourceId, so it’s the event source. MoneyWithdrawn from Handle() is appended to BankAccount / Transactions / 2026-10 for that account.

The validator takes MonthlyWithdrawals as a plain parameter, the same way the book’s validator took BookStock. There’s no [LookUpBy] and no month argument. Arc sees that the model is declared on a stream, takes the source and the stream from the command’s route, and reads the model for that account in that month. Arc resolves {Month} before it builds the validator: a missing or blank Month comes back as a 400 with a rule failure on Month (“‘Month’ is required to read MonthlyWithdrawals”), and nothing is read.

The rule lives in the validator, as before, and Handle() only returns the event. With 4800 already withdrawn in October, a withdrawal of 500 in October fails with “The monthly withdrawal limit is 5000.” With 4800 withdrawn in September, the same withdrawal in October succeeds, because September’s events aren’t in October’s fold.

What it guards

The guard now has the stream in it. Written in the notation the Arc docs use (it’s not an API):

guard account: types=[MoneyWithdrawn], sourceType=BankAccount, streamType=Transactions, streamId=2026-10, after <position before the read>

Compared to the book’s guard, three dimensions are added: the event source type, the stream type and the stream id. A MoneyWithdrawn for this account that arrives in 2026-10 after the read conflicts. The command comes back with the same 400 as in Part 2, reason concurrencyViolation, detail ReadChanged, and nothing from it is written:

MonthlyWithdrawals 'account-1' changed after Withdraw read it. Nothing from this command was written; submit it again.

The message names the model and the account, not the month. A MoneyWithdrawn for this account in 2026-11 doesn’t conflict, and the command commits.

Which concurrent withdrawals make an October withdrawal fail.

If Handle() also took MonthlyWithdrawals, it would get the same instance as the validator, from the same fold, under the same guard.

Under Off and Measure, the same parameter still folds only that month, but it’s a plain read and guards nothing.

Keep the route exact

The guard is only as narrow and as complete as the route, so a few things are worth checking.

The command has to be routed to the same definition and stream as the model, with an explicit stream id. A command routed to another definition or stream, to all streams, or with no stream id, can’t read the model for its own month. Arc refuses that in every mode, Off included, with ReadModelStreamNotOnCommandRoute, before anything is read. The ARCCHR0037 analyzer reports it as a build error when the mismatch is visible in the source. [LookUpBy] on a per-stream parameter is refused too: the source always comes from the command’s route. To read another account or another month, use the stream overloads of IDecisionReads in Provide().

The event source type is part of both the fold and the guard. A MoneyWithdrawn written to Transactions/2026-10 without the BankAccount source type isn’t folded into October’s total, and the guard doesn’t see it. Every writer that takes part in the rule has to use the definition’s route, and decide through a guard of its own. Routing commands with [EventSource<BankAccountEventSource>("Transactions")] rather than repeating the strings keeps them aligned.

The guard can also get wider than one month. Chronicle merges the reads a command makes on one event source into one guard, and keeps only the dimensions they agree on. If the validator also took a whole-source model of the same account, a count of all its withdrawals for example, the merged guard covers every month, and a November withdrawal makes the October command fail. Both reads come back as ReadChanged. Reading two months of the same stream drops the stream id. A Concurrency policy declared on the definition that includes the event source id but not both stream dimensions widens it the same way. ARCCHR0038 reports the combinations it can see, as information.

The same November withdrawal, with and without a whole-source read beside the monthly one.

A wider guard rejects commands that would have been fine. It still includes everything the narrower guard watched, so it adds conflicts and doesn’t drop any. If you need only this month’s state, take only the per-stream model. If you need the whole balance as well, keep both reads and accept the wider guard.

The rest of the limits from Part 2 apply. Revise and Redact between the read and the commit aren’t detected. Other event sequences, services and data outside Chronicle aren’t guarded. EventStreamId.Default doesn’t narrow a fold to one id: in Chronicle it folds every id of the stream type, and Arc refuses it as a command route for a per-stream model.

Querying one month

ForMonth on the model is a model-bound query for the screen that shows how much is left this month. It calls the stream overload of IReadModels.GetInstanceById, which takes the source and stream types from the declaration and the month from its argument. It returns October’s total for that account, or null if nothing was withdrawn in October.

It’s a plain read. It guards nothing, and nothing it returns should decide a withdrawal; the validator does that. Chronicle refuses the reads that have no stream to fold: a key-only GetInstanceById, collections and snapshots, and Watch. A per-stream model has no stored instance per account, so there is nothing for those to return. Chronicle’s analyzer CHR0064 reports such reads when it can see them.

If you call Chronicle without Arc, the same per-stream read model can be read as a decision read and guard an append directly. Chronicle’s page on per-stream read models has that example, and Part 8 covers decision reads without Arc.

Or no model at all: a stream decision

Some rules over a short stream don’t need folded state. “Has this report been approved this month?” is a question about whether one event exists. Arc’s stream decisions answer it from the raw events of the command’s stream:

using Cratis.Arc.Chronicle.Commands;
using Cratis.Arc.Chronicle.Streams;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSources;

[EventSource("Report")]
[EventStream("Approval", Concurrency = ConcurrencyDimensions.EventSourceId | ConcurrencyDimensions.EventStreamType | ConcurrencyDimensions.EventStreamId)]
public class ReportEventSource : IEventSource;

public record ReportId(string Value) : EventSourceId(Value);

[EventType]
public record ReportApproved;

[Command]
[EventSource<ReportEventSource>("Approval")]
[EventStreamId("{Owner}:{Month}")]
public record ApproveReport(ReportId Report, string Owner, string Month)
{
    public Task<StreamDecision> Provide(IStreamReads reads) => reads.ForCommand();

    public EventsWithConcurrencyScopes Handle(StreamDecision decision) =>
        decision.Has<ReportApproved>()
            ? decision.Append([])
            : decision.Append(new ReportApproved());
}

reads.ForCommand() reads the events of this report in Approval/owner-1:2026-10 and notes the position. decision.Append returns the events with a concurrency scope for that stream, and any event in that stream after the read refuses the append, of any type, including the first one. The refusal is a concurrencyViolation too, with a message about the event source instead of a read model. Another month doesn’t conflict. If the report is already approved, Append([]) writes nothing, so a second approval is an identical retry rather than a second fact.

The whole stream crosses the wire for the decision, so keep it short. When the rule needs a count or a folded status rather than “has it happened”, use a per-stream model. Choose one of the two for a command, not both: the validator reads before Provide() runs, and a stream decision’s scope, captured later, may not cover that read. Arc refuses it with ExplicitScopeDoesNotCoverReads, and ARCCHR0036 warns about it at build time. Part 7 puts stream decisions next to the other mechanisms that aren’t guarded reads.

A rule depends on folded state of one stream on the command’s route (a month, a period, a process): declare [EventStream<TSource>("…")] on the read model, route the command with [EventSource<TSource>("…")] and [EventStreamId("{…}")], and take the model in the validator.
The rule is “has X happened in this short stream?”: a stream decision, without a model.
The rule depends on the entity’s whole history, a balance for example: a whole-source model. Combining it with a per-stream model gives a whole-source guard.
You need another month or another account: the stream overloads of IDecisionReads in Provide(), not [LookUpBy].
Another month’s activity makes your command fail: look for a second read on the same source or a declared Concurrency without both stream dimensions (ARCCHR0038).

The one-stream scenario in the Arc docs has both examples, stream decisions covers IStreamReads and testing on a route, and How read protection works explains how guards from several reads merge. The next part is about the other side of a guard: what Arc says when it refuses a command, and what to do with each answer.

The examples need Arc 22.108.0 or later and Chronicle 19.71.0 or later.

Previous: Part 03 — One rule, two entities, one append

One rule, two entities, one append · Decisions that hold, Part 3

Mon, 26 Oct 2026 09:00:00 GMT

Decisions that hold · Part 03 of 11

The previous part ended with one book and one guard. BorrowBook takes a BookStock read model in its validator, and with read protection On that read is folded fresh and guards the append: if a BookBorrowed for the same book lands between the read and the commit, nothing is written.

Now add a rule the library already has on paper: a member may hold at most three loans. Member 1 has two books out, opens two tabs, and borrows a different book in each. If both requests read the member’s loan count before either commits, both see two loans and both approve a third. The guard from the previous part doesn’t help: it watches the book, and the competing borrow is of another book. The rule depends on two entities, so the decision has to hold for both.

A member and a book

The rule needs a fact on the member to count, so the command writes one event to each entity, and the validator reads one model of each:

using Cratis.Arc.Commands;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.Projections.ModelBound;
using FluentValidation;

public record Isbn(string Value) : EventSourceId(Value);

public record MemberId(string Value) : EventSourceId(Value);

[EventType]
public record CopyAdded();

[EventType]
public record BookBorrowed(MemberId Member);

[EventType]
public record BookReturned(MemberId Member);

[EventType]
public record LoanTaken(Isbn Book);

[EventType]
public record LoanReturned(Isbn Book);

[ReadModel]
public record BookStock(
    Isbn Id,
    [Increment<CopyAdded>, Decrement<BookBorrowed>, Increment<BookReturned>] int Available);

[ReadModel]
public record MemberLoans(
    MemberId Id,
    [Increment<LoanTaken>, Decrement<LoanReturned>] int Active);

[Command]
public record BorrowBook(Isbn Isbn, MemberId Member)
{
    public IEnumerable<EventForEventSourceId> Handle() =>
    [
        new(Isbn, new BookBorrowed(Member)),
        new(Member, new LoanTaken(Isbn))
    ];
}

public class BorrowBookValidator : CommandValidator<BorrowBook>
{
    public BorrowBookValidator(
        [LookUpBy(nameof(BorrowBook.Isbn))] BookStock? stock,
        [LookUpBy(nameof(BorrowBook.Member))] MemberLoans? loans)
    {
        RuleFor(command => command.Isbn)
            .Must(_ => stock is { Available: > 0 })
            .WithMessage("No copies of this book are available.");
        RuleFor(command => command.Member)
            .Must(_ => loans is null || loans.Active < 3)
            .WithMessage("The member has reached the loan limit.");
    }
}

Read protection is part of Arc for .NET, and the project still has <CratisReadProtection>On</CratisReadProtection> from the previous part. Three things changed from the one-book version:

MemberId derives from EventSourceId now. Before, the command only mentioned the member, so a plain concept was enough. Now it appends to the member, so the member is an event source with its own history.
Handle() returns EventForEventSourceId values. Each one names the event source it goes to, so the command doesn’t need a single event source id, and Arc doesn’t need ICanProvideEventSourceId to pick one.
The validator takes two read models, and [LookUpBy] names the command property that supplies each key. BookStock is read for Isbn, and MemberLoans for Member.

Under On, each read-model parameter is its own decision read. Chronicle notes the log’s position, folds that one key’s history, and enrolls a guard before the validator sees the value. Two reads give two guards, one per key:

guard isbn-1:   types=[CopyAdded, BookBorrowed, BookReturned], after <tail before the BookStock read>
guard member-1: types=[LoanTaken, LoanReturned], after <tail before the MemberLoans read>

That is notation, not output: one line per guard, with the key, the event types the model folds, and the position captured before the fold. Arc commits both events as one atomic append, and the kernel checks both guards with it. If either one is violated, neither event is written.

Each read guards its own key. Both guards are checked with the one append.

Back to the two tabs. Both requests read MemberLoans with Active = 2, and both pass the validator. The first to commit appends BookBorrowed to its book and LoanTaken to member 1. The second commit carries a guard on member 1 that says “no LoanTaken or LoanReturned after the position I read”, and the first request just broke it. The kernel rejects the second append, and its book keeps its copy. The caller gets a 400 with the reason concurrencyViolation, the detail ReadChanged, and a message that names the model and key that moved:

MemberLoans 'member-1' changed after BorrowBook read it. Nothing from this command was written; submit it again.

If instead another member took the last copy of the same book, the book’s guard is the one that fires, and the message says BookStock 'isbn-1' changed after BorrowBook read it. with the same ending. The validation result’s state carries readModel and key as separate values, so a client can tell which side changed without parsing the text. Arc and Chronicle do not re-run the command. The caller reads again, and if it submits again, the validator sees three loans and refuses with “The member has reached the loan limit.”, an ordinary rule failure.

Events that don’t touch either guard leave the command alone. Another member’s borrow of a different book, or an event on member 1 that MemberLoans doesn’t fold, lets both events commit as usual. Member 1 borrowing a different book does conflict: that borrow appends LoanTaken to member 1.

Each entity gets its own fact

BookBorrowed goes to the book and LoanTaken goes to the member. It is tempting to write BookBorrowed to both and have MemberLoans count it. Don’t. A model-bound projection folds an event into the instance keyed by the event source it was appended to, so every model that counts BookBorrowed would see both copies. A BookBorrowed appended to member 1 gives member 1 a BookStock of its own, with Available at -1. Two event types keep each model to its own entity’s events.

They are also two different facts. “A copy left the shelf” belongs in the book’s history, and “the member took a loan” belongs in the member’s. Returning a book appends BookReturned to the book and LoanReturned to the member, the same way.

If you know the dynamic consistency boundary, this is where Chronicle differs from it. In DCB, one event can carry a tag for each entity it concerns, and one query reads both. In Chronicle every event belongs to exactly one event source, so a fact about two entities is two events in one atomic append, and each read model reads its own entity’s events. Chronicle’s DCB page says when two events for one fact are the right answer, and when to look for a form with one event instead.

Choosing the key

A read-model parameter reads the instance whose Id equals a key taken from the command. Under On, Arc picks that key in this order:

The command property named by [LookUpBy(nameof(...))] on the parameter.
Without it, the one command property whose type equals the model’s Id type.
If several properties match, the command fails with AmbiguousReadModelLookup.
If none matches, the command’s event source id.

BookStock has an Isbn Id and MemberLoans a MemberId Id, and BorrowBook has exactly one property of each type, so under On the second rule would find both keys on its own. I still write [LookUpBy], for two reasons. It works the same in every mode, while under Off and Measure a parameter without it reads the command’s event source id. And it survives the next property: add a MemberId ReservedFor to the command, and the type rule no longer has a single answer. A command with two properties of the model’s Id type and no [LookUpBy] fails with AmbiguousReadModelLookup, a 500 whose message names both properties and asks you to select one with [LookUpBy].

[LookUpBy] goes on the parameter, also on a validator constructor, and names a property of the command. The property’s type doesn’t have to match the model’s Id type: Arc converts the value to the key, so an Isbn property can select a model with an EventSourceId Id. When the second key isn’t on the command at all, because it’s computed or looked up, read it with IDecisionReads.Get in Provide(). That read is guarded in the same way. The reads page has the conversion rules.

A course and a student

The canonical example for a rule across two entities is course subscription: a course has a fixed number of seats, and a student can join at most three courses. In Arc it’s the same shape as the library:

using Cratis.Arc.Commands;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.Projections.ModelBound;
using FluentValidation;

public record CourseId(string Value) : EventSourceId(Value);

public record StudentId(string Value) : EventSourceId(Value);

[EventType]
public record CourseDefined(int Capacity);

[EventType]
public record SeatTaken(StudentId Student);

[EventType]
public record CourseJoined(CourseId Course);

[ReadModel]
[FromEvent<CourseDefined>]
public record CourseSeats(
    CourseId Id,
    int Capacity,
    [Increment<SeatTaken>] int Taken);

[ReadModel]
public record StudentCourses(
    StudentId Id,
    [Increment<CourseJoined>] int Count);

[Command]
public record SubscribeToCourse(CourseId Course, StudentId Student)
{
    public IEnumerable<EventForEventSourceId> Handle() =>
    [
        new(Course, new SeatTaken(Student)),
        new(Student, new CourseJoined(Course))
    ];
}

public class SubscribeToCourseValidator : CommandValidator<SubscribeToCourse>
{
    public SubscribeToCourseValidator(
        [LookUpBy(nameof(SubscribeToCourse.Course))] CourseSeats? course,
        [LookUpBy(nameof(SubscribeToCourse.Student))] StudentCourses? student)
    {
        RuleFor(command => command.Course)
            .Must(_ => course is not null)
            .WithMessage("The course does not exist.")
            .Must(_ => course is null || course.Taken < course.Capacity)
            .WithMessage("The course is full.");
        RuleFor(command => command.Student)
            .Must(_ => student is null || student.Count < 3)
            .WithMessage("The student is already in three courses.");
    }
}

guard course-1:  types=[CourseDefined, SeatTaken], after <tail before the CourseSeats read>
guard student-1: types=[CourseJoined], after <tail before the StudentCourses read>

[FromEvent<CourseDefined>] sets Capacity from the event with the same property name. A SeatTaken on the course after the read rejects the command with CourseSeats 'course-1' changed…, and a CourseJoined on the student, from the same student subscribing to another course, rejects it with StudentCourses 'student-1' changed…. Neither case writes anything.

A decision guards each key it reads, whether or not it writes there. A command that reads a member’s standing and appends only to the book is still rejected if the member is suspended between its read and its commit. The guard is built from the read, not from the append.

The trap: a model keyed by an event property

There is a shorter way to count loans that looks right. BookBorrowed already names the member, so a model can fold the book’s events and key them by that property:

using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Projections.ModelBound;

[ReadModel]
[FromEvent<BookBorrowed>(key: nameof(BookBorrowed.Member))]
public record MemberLoans(
    MemberId Id,
    [Increment<BookBorrowed>] int Active);

As a query model this is fine. As a decision it can’t be guarded. A guard covers the events of one event source, and this model’s events live on the books’ event sources, one per book. A borrow of any other book by the same member changes the count, and there is no key a guard could watch to see it.

Arc says so twice. The build reports ARCCHR0024 as a warning on the validator parameter, and under On the command is refused with a 500 and writes nothing. In Development the response carries this message; elsewhere the client gets a generic error and the message goes to the server log:

BorrowBook reads 'loans' (MemberLoans) keyed by an event property, so read protection cannot guard it. If it is only context, mark it [Unprotected("why")]. Otherwise append a fact to the entity it is keyed by, or use a constraint.

The fix is the first example: append LoanTaken to the member, and key the model by the member’s own events. Marking the read [Unprotected("why")] would let the command run, with the loan count as an unguarded snapshot. That is right only if the count is context, not the rule.

What this does not cover

The guards cover exactly the keys the command read. That has two consequences worth checking in your own rules.

If the set of keys a rule counts over can grow, the new keys are outside every guard. Say each loan were its own event source, and the limit counted open loans across them. A loan created after the read is on a key nobody read, so no guard sees it. Put such a limit on one key that receives every relevant fact, which is what MemberLoans on the member does.

A rule also holds only as far as every writer that decides on it reads through a guard. An import job that appends LoanTaken to a member without reading MemberLoans doesn’t check the limit. If its event lands inside our command’s window, our guard on the member detects it and our command is the one rejected. If it lands after our commit, nothing checks it at all.

The rest of the limits from the previous part apply to each read here: a Revise or Redact between read and commit is not detected, other event sequences and data outside Chronicle are not guarded, and with read protection Off, the default, both reads are plain snapshots that guard nothing.

The two-entities scenario in the Arc docs has both examples, and refusals lists the 500s with their fixes. A rule over one account and one month, read from a single stream, is the next shape.

The examples need Arc 22.108.0 or later and Chronicle 19.68.0 or later.

Previous: Part 02 — The read model said yes

The read model said yes · Decisions that hold, Part 2

Thu, 22 Oct 2026 09:00:00 GMT

Decisions that hold · Part 02 of 11

Part 1 was about the check that passes twice: a rule reads state, decides, and writes, and two requests can both pass the check before either writes. This part is that bug in an event-sourced application, written the way most of us write the command first, and the one project setting that makes Arc and Chronicle guard it.

A library lends a book only while a copy is on the shelf. In an event-sourced system the stock is a fold over the book’s events, and Chronicle can keep it as a read model:

using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections.ModelBound;
using Cratis.Concepts;

public record Isbn(string Value) : EventSourceId(Value);

public record MemberId(Guid Value) : ConceptAs<Guid>(Value);

[EventType]
public record CopyAdded();

[EventType]
public record BookBorrowed(MemberId Member);

[EventType]
public record BookReturned(MemberId Member);

[ReadModel]
public record BookStock(
    Isbn Id,
    [Increment<CopyAdded>, Decrement<BookBorrowed>, Increment<BookReturned>] int Available);

The command most of us write first takes that read model and checks it. The check belongs in a validator, because “may this command proceed” is what validators are for:

using Cratis.Arc.Commands;
using Cratis.Arc.Commands.ModelBound;
using FluentValidation;

[Command]
public record BorrowBook(Isbn Isbn, MemberId Member)
{
    public BookBorrowed Handle() => new(Member);
}

public class BorrowBookValidator : CommandValidator<BorrowBook>
{
    public BorrowBookValidator(BookStock? stock) =>
        RuleFor(command => command.Isbn)
            .Must(_ => stock is { Available: > 0 })
            .WithMessage("No copies of this book are available.");
}

Isbn derives from EventSourceId, so it’s the command’s event source id and the key Arc reads BookStock by. MemberId is a ConceptAs<Guid>: it refers to the member, and this command doesn’t append to the member. BookStock? is nullable because a book with no events has no read model yet. A non-nullable parameter fails the command with ReadModelDoesNotExistForCommand instead.

Arc looks up BookStock by the book’s key, builds the validator with it, and runs the rule. Handle() returns an event, and when the command succeeds Arc commits that event to Chronicle. Nothing in this path connects the commit to the value of Available that the validator looked at.

Two requests for the last copy

Take a book with one copy left and two members who press Borrow at about the same time:

request A                                  request B
read BookStock: Available = 1
                                           read BookStock: Available = 1
validate: 1 > 0, Handle: BookBorrowed
commit: read tail, append, success
                                           validate: 1 > 0, Handle: BookBorrowed
                                           commit: read tail, append, success

BookStock.Available is now -1

Both commands succeed, both BookBorrowed events are in the log, and the stock folds to -1.

Arc does run a concurrency check when it commits to an event source that already has events. By default the .NET client reads the event source’s tail when the events are appended and sends that position along, so the kernel rejects the append if another event landed between that tail read and the write. That window opens after the validator and Handle() have decided. It catches two commits that overlap, so when both requests arrive at exactly the same moment it can reject one of them. With request B a few milliseconds behind A, as above, B reads the tail after A’s event is already there, and the check passes.

It doesn’t even take concurrency. BookStock here is a materialized read model, which Chronicle updates after the append returns, not with it. A second request sent after the first one has completed can still read Available = 1 and be approved.

The same holds for the other places a command can read state on its way to the append. A read-model parameter on Handle() gets the same snapshot as the validator. A passive projection folds fresh from the events when it’s read, so it doesn’t lag, but it records no position either, and the append that follows isn’t conditioned on it.

None of this is new. Rules that hold when you write and Validation all the way down described the snapshot, and the per-command opt-in with [ProtectedDecision] and DecisionRead<T>. What’s new is that the fix no longer needs a different command.

Turning the read into a guard

Arc has a mode for this, called read protection. It’s Off by default, and under Off an injected read model is a plain read, as above. The next major version of Arc turns it On by default, and you’ll still be able to turn it off for one command with [ReadProtection(ReadProtectionMode.Off)] or for one read with [Unprotected("why")] (Cratis/Arc#3255). Set it to On in the project that contains your commands, or in a Directory.Build.props that covers several:

<PropertyGroup>
    <CratisReadProtection>On</CratisReadProtection>
</PropertyGroup>

The value is compiled into the assembly, so analyzers and tests see the mode that runs in production. It must be Off, Measure or On. Anything else fails the build with CratisReadProtection must be Off, Measure, or On. To turn it on for one command instead, put [ReadProtection(ReadProtectionMode.On)] (namespace Cratis.Arc.Commands) on the command; a command-level value overrides the assembly’s.

The command and the validator above don’t change. What changes is when the position is taken and what the commit checks against it:

Arc starts a unit of work for the command and turns on read protection for the whole invocation, before any filter or validator runs. The unit of work collects the command’s events and its guards, and only Arc’s command pipeline may commit it: code inside the command can’t commit it early or roll it back.
Arc builds the validator inside that unit. For its BookStock parameter, Chronicle first captures the position of the event log, and only then folds BookStock from the book’s own events, in a fresh session straight from the event log. The materialized copy isn’t used.
The read is enrolled in the unit of work as a guard: no event of the types BookStock is built from, on this book, after that position.
The validator decides from that instance, and Handle() returns BookBorrowed. If Handle() took BookStock too, it would get the same instance under the same guard.
Arc commits the unit of work, which sends the command’s events and the guards to the kernel in one append. The kernel rejects the append if anything matching a guard arrived after the position, and nothing from the command is written.

Taking the position before the fold is what makes the guard sound. An event that lands during the fold, or after it, is after the position, so it’s detected. If events keep arriving while it folds, Chronicle folds again; the read makes up to three attempts.

The same two requests under each mode.

In the interleaving above, request B now loses:

request A                                  request B
position p, fold BookStock: Available = 1
                                           position p, fold BookStock: Available = 1
validate: 1 > 0, Handle: BookBorrowed
commit: nothing after p, success
                                           validate: 1 > 0, Handle: BookBorrowed
                                           commit: BookBorrowed after p, refused

BookStock.Available is now 0

If B starts late enough to fold A’s event, it gets the business rejection instead, “No copies of this book are available.” Either way the book has one BookBorrowed event and the stock ends at zero.

The Arc docs write a guard as one line. It’s a notation, not an API:

guard isbn-1: types=[CopyAdded, BookBorrowed, BookReturned], after <position before the read>

The filter is the key and the model’s event types, nothing more. A borrow of the same book conflicts. An event on the same book that BookStock doesn’t fold, a rename for example, doesn’t. A borrow of another book doesn’t either. A model that doesn’t exist yet is guarded too: the parameter is null, and a first event of the model’s types that arrives after the read conflicts. That’s how “only if it doesn’t exist yet” holds.

Which concurrent events make the command fail.

Nothing is locked. Two borrowers of the same book both run to the commit, and the commit is where one of them may be refused.

Under On, Arc builds a fresh validator for every command so that its read-model parameters are guards in that command’s unit of work. That’s why the validator has to be registered by convention, as a transient, which is what Arc does when you don’t register it yourself. A validator registered by hand as scoped, singleton, a factory or an instance is refused. Part 5 has the refusals and their fixes.

If you have commands marked [ProtectedDecision] that read through DecisionRead<T>: under On you don’t need [ProtectedDecision] or DecisionRead<T>; they keep working.

Read protection is part of Arc for .NET.

What the caller sees

The refused command returns a 400. Its validation result has the reason concurrencyViolation (ValidationResultReason.ConcurrencyViolation in .NET), the detail ReadChanged, a state object with the model and the key ({"readModel":"BookStock","key":"isbn-1"}), and this message:

BookStock 'isbn-1' changed after BorrowBook read it. Nothing from this command was written; submit it again.

Arc and Chronicle don’t re-run the command. The read itself makes up to three attempts at the fold, but once the validator and Handle() have decided, a conflict ends the command. The state the decision rested on has changed, and deciding again from new state is the caller’s call: read again, show the user, and submit again if it still makes sense. Resubmitting blindly in a loop would undo the point of the guard. The message doesn’t say which event caused the conflict.

A rejection by the validator itself is a different result. “No copies of this book are available.” is an ordinary rule failure, not a concurrencyViolation. It writes nothing, so it needs no guard.

Part 5 goes through every refusal, the 500s that mean the code can’t be guarded, and how a UI tells a changed read from a field error. If you want to see the race in a test now, Arc’s Test the race page puts a competing append between the read and the commit. Part 9 is about that.

Where the guard stops

A guard covers one key’s history, for the event types the model folds, from the position taken before the read. Some things are outside it:

Revise and Redact between the read and the commit aren’t detected, because they don’t move the tail. Chronicle refuses them inside a protected invocation.
Services, HTTP calls, other databases and other event sequences aren’t guarded.
A read marked [Unprotected("why")] is a stored read that guards nothing, on purpose.
A projection definition changed by another process isn’t detected until this client registers it again.
A writer that decides without a guard can still break the rule. If another command appends BookBorrowed with read protection Off, the protected command detects that event. The unprotected command’s own decision is still unguarded: if it reads first and commits last, it lends a copy that isn’t there.
Uniqueness across keys is a constraint, not this. Two members registering the same email are two different keys, and no read of one key can see the other.

Under On, Arc also refuses reads it can’t guard instead of running them unguarded: IReadModels, raw event-log reads, an IMongoCollection<T> of a Chronicle-backed model, immediate appends through IEventLog.Append, and read models with joins, children or keys taken from an event property. So under On every read Arc can see is guarded, marked advisory or refused. That’s also why turning it on in an application that already runs is a project of its own.

What it costs

A guarded read is a fresh fold of the key’s history every time. Chronicle doesn’t use the materialized state, because that can lag and has no position, and nothing caches the result between commands. Each read makes two tail reads and a fold of the key’s events of the model’s types, and the read makes up to three attempts at the fold if events arrive during it. The first read of a model type in a process also checks the projection definition. Identical reads inside one command share one fold.

In the kernel, those folds go through one projection per model type, shared by every key of that type and every tenant, so heavy use of one model type queues across keys. No benchmark for read protection is published, and the costs section of Arc’s docs gives the shape of the cost without figures. Keep guarded models flat and keys short-lived: a key per book, order, booking or period rather than one for the life of the library.

Where to start

For new code, set On in the project and put each “may this proceed” rule in a validator that takes the read model. For an application that already runs, I wouldn’t flip it blind. Measure runs every command as before and reports what On would guard, refuse or reject. Part 6 is about that path.

The next part takes the same command to two entities: a member may hold three loans and a book has one copy left, with two read models in one validator and one atomic append.

The full walkthrough is Arc’s Getting started with read protection, and Validators and read protection covers what a validator may take. How read protection works explains how guards are derived and merged, and Choosing how a command’s rule holds compares read protection with constraints, aggregates, stream decisions and explicit scopes.

Read protection as described here needs Arc 22.108.0 or later and Chronicle 19.68.0 or later.

Previous: Part 01 — The bug you never see

The bug you never see · Decisions that hold, Part 1

Tue, 20 Oct 2026 09:00:00 GMT

Decisions that hold · Part 01 of 11

Is there a copy left? Is this user name free? Is the balance enough for the withdrawal? Is the 10:30 slot still open? Has this customer already used the welcome discount?

Most applications are full of questions like these, and each one is half of a decision. The code reads something, checks it, and then writes. Between the read and the write there is a gap, and in most code nothing connects the write to what the read saw. Two requests can both read “yes”, both pass the check, and both write.

This series is about making those decisions hold. This first part is about the problem itself, because in my experience it’s one of the most common bugs in business software and one of the least discussed. It doesn’t throw and it doesn’t show up in tests. When it does surface, it rarely looks like a bug.

Two requests for the last copy

Here is the code most of us have written, in some form, many times. An order is accepted only while there is stock:

using Microsoft.EntityFrameworkCore;

public class Product
{
    public int Id { get; set; }
    public int Stock { get; set; }
}

public class Order
{
    public int Id { get; set; }
    public int ProductId { get; set; }
    public int Quantity { get; set; }
}

public class ShopContext(DbContextOptions<ShopContext> options) : DbContext(options)
{
    public DbSet<Product> Products => Set<Product>();
    public DbSet<Order> Orders => Set<Order>();
}

public class PlaceOrder(ShopContext db)
{
    public async Task<bool> Handle(int productId, int quantity)
    {
        var product = await db.Products.SingleAsync(p => p.Id == productId);
        if (product.Stock < quantity)
        {
            return false;
        }

        product.Stock -= quantity;
        db.Orders.Add(new Order { ProductId = productId, Quantity = quantity });
        await db.SaveChangesAsync();
        return true;
    }
}

It reads well, and every test of it passes. Now take a product with one item left and two customers who press Buy within a few milliseconds of each other:

request A                                   request B
SELECT product 7: Stock = 1
                                            SELECT product 7: Stock = 1
1 >= 1, set Stock = 0, add an order
SaveChanges: UPDATE Stock = 0, INSERT order
                                            1 >= 1, set Stock = 0, add an order
                                            SaveChanges: UPDATE Stock = 0, INSERT order

Products: Stock = 0      Orders: two rows for product 7

Both checks were right when they ran. The row says 0, and two orders exist for one item.

Both requests succeed. EF Core sends the new value of the property, so both updates write Stock = 0, and the second one overwrites the first. The stock column looks exactly right. The only trace is a second order for an item that was never there, and it appears as a successful request in every log.

That’s the classic lost update. Microsoft’s locking and row versioning guide defines it in one sentence: lost updates “occur when two or more transactions select the same row and then update the row based on the value originally selected.”

Why you never see it

The gap is small, often a few milliseconds, and almost everything about how we build and test software keeps two requests out of it.

Tests run one request at a time. A test of PlaceOrder calls it, checks the result, and stops. A second call that starts after the first has finished reads the new stock and is correctly rejected.
Development has one user. You can’t double-book a slot you’re the only person looking at.
It doesn’t need two users. A double-clicked button, an HTTP client that retries after a timeout, a load balancer that resends, a message delivered twice: each of these is two requests carrying the same intent, and they arrive close together by construction.
Nothing fails. No exception, no error log, no alert. Every request returned success.
The result looks like bad data. A negative balance, a member with four loans when the limit is three, two bookings for one room. Someone fixes the row by hand, and nobody connects it to the code.
It surfaces late. Support hears about it from a customer, or finance finds it in a reconciliation weeks later, long after the logs that would explain it have rotated.

So the bug survives code review, testing and staging, and shows up in production, most often under load on the busiest day or when a retry lands in the gap, where it’s hardest to reproduce.

Doesn’t the database handle this?

It’s a reasonable assumption, and it’s mostly wrong for the default settings.

First, look at where the transaction is. In the code above, EF Core runs SingleAsync as its own statement. By default, “all changes in a single call to SaveChanges are applied in a transaction”, and that transaction begins after the read. The read and the write are in different transactions, so no isolation level on the write can protect a value read before it began.

Second, even with one transaction around both, the default isolation levels don’t stop this:

PostgreSQL: “Read Committed is the default isolation level”.
SQL Server: READ COMMITTED “is the SQL Server default”, and under it “data can be changed by other transactions between individual statements within the current transaction”. Azure SQL Database turns on READ_COMMITTED_SNAPSHOT by default, which changes how reads are served, not this.
MySQL: REPEATABLE READ “is the default isolation level for InnoDB”.

Here is what each does when both requests run the read and the update inside one transaction, and the new stock is computed in application code:

Isolation level	What the second request’s `UPDATE` does
PostgreSQL `READ COMMITTED` (default)	Waits for the first transaction to commit, then writes its own value over it
SQL Server `READ COMMITTED` (default)	The same
MySQL InnoDB `REPEATABLE READ` (default)	The same. The `SELECT` reads a snapshot, but the `UPDATE` works on the latest row
PostgreSQL `REPEATABLE READ` or `SERIALIZABLE`	Fails with “could not serialize access due to concurrent update”, and the application has to retry the transaction
SQL Server `SNAPSHOT`	Fails with error 3960, “Snapshot isolation transaction aborted due to update conflict”, and the application has to retry

The MySQL row surprises people, because “repeatable read” sounds like protection. The manual is explicit that “the snapshot of the database state applies to SELECT statements within a transaction, not necessarily to DML statements”, and its locking reads page opens with the exact case: “If you query data and then insert or update related data within the same transaction, the regular SELECT statement does not give enough protection.”

So the stronger levels do catch this lost update, as an error you have to handle. They catch it because both requests update the same row. Many rules don’t work that way.

The rule nobody writes to

Say a library member may hold at most three loans. The check counts rows and the act inserts one:

-- Both requests run this for member 42, who has two active loans.
BEGIN;
SELECT count(*) FROM loans WHERE member_id = 42 AND returned_at IS NULL;  -- 2, so below 3
INSERT INTO loans (member_id, book_id) VALUES (42, 1001);                 -- the other request inserts 1002
COMMIT;

Both requests see two loans, both insert, and the member now holds four. Neither transaction updated a row the other one touched, so there is no update conflict to detect and no unique key to collide. This is write skew: each transaction decides from data the other one is changing. The PostgreSQL wiki defines it as two concurrent transactions that “each determine what they are writing based on reading a data set which overlaps what the other is writing”.

Snapshot isolation allows it. PostgreSQL’s REPEATABLE READ is implemented as snapshot isolation, and its documentation shows the same shape with two sums and two inserts, where “if either transaction were running at the Repeatable Read isolation level, both would be allowed to commit.” Its Repeatable Read section also says plainly that “attempts to enforce business rules by transactions running at this isolation level are not likely to work correctly without careful use of explicit locks.” SQL Server’s SNAPSHOT checks for conflicts on the rows a transaction modifies, and the two loan inserts modify different rows, so both commit there as well.

Write skew is the general shape of most check-then-act rules: a limit counted over rows, an overlap between bookings, “at least one person on call”, “only one active subscription”, “no more than 5000 withdrawn this month”. The check reads a set and the act adds to it.

The check and the act are separate moments. Every fix is a way of tying the second to what the first saw.

The usual fixes, and where each stops

There are good tools for this in a relational database. Each one covers a particular shape of rule.

A unique constraint makes uniqueness hold for every writer. In PostgreSQL’s words, unique constraints “ensure that the data contained in a column, or a group of columns, is unique among all the rows in the table.” It is the right answer for “is the name free?”, and the SELECT-then-INSERT check in front of it becomes a friendly message, not the rule. It can’t count or sum. PostgreSQL’s exclusion constraints extend the idea to overlaps such as bookings, but not to “at most three”.

A conditional write moves the check into the statement that acts:

using Microsoft.EntityFrameworkCore;

public class PlaceOrderConditionally(ShopContext db)
{
    public async Task<bool> Handle(int productId, int quantity)
    {
        await using var transaction = await db.Database.BeginTransactionAsync();

        var reserved = await db.Products
            .Where(p => p.Id == productId && p.Stock >= quantity)
            .ExecuteUpdateAsync(s => s.SetProperty(p => p.Stock, p => p.Stock - quantity));

        if (reserved == 0)
        {
            return false;
        }

        db.Orders.Add(new Order { ProductId = productId, Quantity = quantity });
        await db.SaveChangesAsync();
        await transaction.CommitAsync();
        return true;
    }
}

That is UPDATE products SET stock = stock - @quantity WHERE id = @id AND stock >= @quantity, and ExecuteUpdateAsync returns the number of rows affected. Under PostgreSQL’s READ COMMITTED, a second update that waited for the first sees the new row, and “the search condition of the command (the WHERE clause) is re-evaluated”, so it matches nothing. It works as long as the whole rule fits in the WHERE clause of one row. Under REPEATABLE READ the same statement fails with a serialization error and you retry.

A concurrency token is EF Core’s optimistic concurrency. Mark a property with [ConcurrencyCheck], or map a SQL Server rowversion with [Timestamp], and EF Core adds its original value to the WHERE clause of the update, so the update “only modifies the row if the Version column hasn’t changed since the moment we queried it.” A conflict throws DbUpdateConcurrencyException, and resolving it, including any retry, is your code. It fixes the lost update in PlaceOrder. It covers only rows you update or delete: the docs note the exception “is generally never thrown when adding entities”, so a token on the rows you insert does nothing for the loan count. A version on the parent row does work, if every writer that adds a loan also bumps the member’s version: two concurrent inserts then both update the member row, and the second one gets the exception. It’s the optimistic form of the parent-row lock below, with the same every-writer condition.

A locking read, SELECT ... FOR UPDATE, holds the rows it returns until the transaction ends. In PostgreSQL it “causes the rows retrieved by the SELECT statement to be locked as though for update.” A row that doesn’t exist yet isn’t returned, so it isn’t locked. MySQL’s REPEATABLE READ adds gap locks over the index range a locking read scans, which do block inserts into it, and PostgreSQL doesn’t. The common pattern for a rule over many rows is to lock a parent row, the member, as a mutex. That holds only while every code path that can break the rule takes the same lock first and checks the rule after it, and it costs waiting and the occasional deadlock. Under PostgreSQL’s REPEATABLE READ even that isn’t enough: the snapshot is fixed when the transaction’s first query starts, and the docs warn that “if the snapshot seen by the transaction predates obtaining the lock, it might predate some now-committed changes in the table”. The count after the lock can still miss the other request’s loan, so take the lock at READ COMMITTED.

Serializable transactions handle write skew in PostgreSQL. Its SERIALIZABLE level monitors read/write dependencies and rolls one transaction back with SQLSTATE 40001. The docs set the conditions: it works “if the Serializable transaction isolation level is used for all writes and for all reads which need a consistent view of the data”, and the application needs a framework that retries transactions rolled back with a serialization failure. SQL Server and MySQL implement SERIALIZABLE with locks, so the same pattern tends to block or deadlock instead, and the losing transaction still has to be retried.

Put together: a constraint when the rule is uniqueness or exclusion, a conditional write when the rule fits in one row, a token when the danger is overwriting a row someone else changed. For rules that span rows or tables, and rules over history (“three in any 30 days”, “5000 per month”), you’re left with locks, a version on a parent row, or serializable transactions, and all of them depend on every writer following the same protocol. None of them is the default, and none of them is visible in the PlaceOrder code above.

Event sourcing doesn’t make it go away

You might expect event sourcing and CQRS to sidestep this. They make it more common.

In many CQRS codebases, including the Arc style this series uses, the side that decides asks a read model: a projection built from the events. Read models are built after the fact. Chronicle’s documentation says it directly: “read models are updated asynchronously as events are processed”, and the append returns before the projection has run. So a command that checks a read model and then appends has the same gap as PlaceOrder, plus the projection’s lag. Two requests don’t even have to overlap. A request that arrives after the first one has completed can still read the old stock and be approved.

Folding the state fresh from the events doesn’t close it either. A fresh read is a correct snapshot of the moment it was taken, and an append that follows it is not conditioned on it. A stream’s expected version helps when the rule lives entirely in the one stream you append to. It says nothing about a read model built from other events, or about a second entity the rule depends on.

Arc is no exception. With read protection Off, which is the default, “an injected read model is a plain read, it returns a snapshot, and it guards nothing.” The next part starts from exactly that command.

What event sourcing does give you is a way to say what the decision depended on. An event log is ordered, and every event has a position. A decision can note the position before it reads, fold the events it needs, and append with a condition: only if no event that would have changed what I read has arrived since. That’s not a lock. Nothing waits, and a conflict is an answer: the state changed, read again and decide again. The condition can be as narrow as the rule: the event types that build this read model, for this key. The rest of the series is about that condition, how to get one, and where it stops.

Look for any rule that reads state before it writes:

A query followed by SaveChanges in the same handler: SingleAsync, FirstOrDefaultAsync, AnyAsync or CountAsync, then Add or a property change.
A value computed in application code from a value you read: product.Stock -= quantity, account.Balance -= amount.
if (!await db.Users.AnyAsync(u => u.Email == email)) followed by an insert.
Words in the requirement such as “at most”, “no more than”, “only one”, “once”, “per month”, “still available”.
A validator, cache, search index or read model consulted before a command writes.
Anything that can arrive twice: a submit button, a client retry, a redelivered message.

For each one, ask what happens if two of them run at the same moment, and what ties the write to what the check read:

Uniqueness → a unique constraint or index; the check in front is only the message.
One row’s state → a conditional UPDATE ... WHERE and a rows-affected check, or a concurrency token.
Many rows or tables → a lock every writer takes before it checks (at READ COMMITTED in PostgreSQL), a version on a parent row every writer bumps, or serializable transactions with retries.
A read model before an append → the append needs a condition on what was read; Part 2 covers how Arc and Chronicle express one, and where it stops.
Nothing ties them → you have the bug. It just hasn’t been reported yet.

The series

Decisions that hold is eleven posts on making a decision still true at the moment it’s written, mostly in Arc and Chronicle, with the limits of each mechanism stated where it applies.

The bug you never see. Check-then-act decisions, why two requests can both pass the check, and what the database defaults do about it.
The read model said yes. A command that checks a read model and then appends, and what it takes in Arc and Chronicle for that check to still hold at the append.
One rule, two entities, one append. A rule over a member and a book: two reads, one fact for each entity, and one atomic append.
A limit for one account and one month. Guarding a decision on one stream, so last month’s activity doesn’t conflict with today’s.
When Arc says no. The two kinds of refusal, what each means, and what the caller and the UI should do.
Turning read protection on in an application that already runs. Measuring first, fixing what it finds, and switching on per project.
Not every rule needs a guarded read. Constraints, aggregates, explicit scopes, stream decisions, repair and hints, and the choices that fail silently.
The same guard without Arc: decision reads and append conditions. The Chronicle calls underneath, and how they map to the dynamic consistency boundary.
Testing a decision against a race. Putting a competing write between a command’s read and its commit.
How a guard is built, merged and widened. Predicting exactly which events make a command fail.
Decisions that hold: questions and a decision guide. One page to come back to.

If you’ve read Cratis: from script to stage, its parts on rules that hold when you write and validation all the way down covered constraints, concurrency scopes and validators. This series goes further into the decisions that read state first.

Next is Part 2, The read model said yes: the same last-copy race as a library command in Arc, and what changes, and what doesn’t, when the read it checks is tied to the append.

Where does each tenant's data live? Storage connection resolution in Chronicle and Arc

Sat, 17 Oct 2026 00:00:00 GMT

TL;DR

Until now, Chronicle and Arc decided for themselves where a tenant’s data lives. Chronicle derived a database name for every event store and namespace and connected with one credential. Arc’s MongoDB integration appended the tenant to a database name, and Entity Framework Core used the same connection for everyone. That’s fine until your platform has opinions: a server per region, a database per customer, a login that can see one tenant and nothing else.

Connection resolution lets them ask instead. When a connection is needed, the caller describes what it’s for, and a resolver answers with the parts it decides. Anything it leaves out stays as configured. Nothing changes until you configure it.

This post explains how that works, and then builds one example you can run: a Chronicle kernel that places each namespace by a naming rule, an Arc application that asks an HTTP endpoint for each tenant’s database and login, and a small client with no Arc in it that asks the same endpoint. Arc is a convenience here, not a requirement.

The example uses .NET 10, Chronicle 19.77.2, Arc 22.112.0, MongoDB 8.2 and MongoDB.Driver 3.12.0. Connection resolution needs Chronicle 19.74.2 or later and Arc 22.109.0 or later.

The question and the answer

The caller says what it needs the connection for. The resolver says what it knows.

The caller describes the connection with a few fields. Arc sends three: the storage (MongoDB, SqlServer, PostgreSql or Sqlite), the purpose (Runtime for reading and writing, Schema for migrations and creating tables) and a scope, which for Arc holds the tenant. Chronicle sends the same storage and purpose, and a scope that says which database it’s about: the cluster, an eventStore, a namespace (its events) or readModels (its projected read models), with the event store and namespace names.

The resolver answers with any of these, and every part is optional:

Part	What it does
`connectionString`	Replaces the configured connection string
`database`	The database to use
`schema`	The schema, for storage that has one
`identity`	`userName` and `password`, or an `accessToken`
`expiresAt`	When to ask again

Arc and Chronicle share this model, and it has two slots: Connection decides where to connect and Identity decides who connects. They apply what’s configured, then what the Connection slot resolved, then what the Identity slot resolved, and a later part wins. That’s how the common split becomes a configuration choice. Keep the server in configuration and fetch only the credential, or the other way around.

Each slot takes one of four resolvers: Default leaves things alone, Template fills in a naming rule such as tenant-{tenant}, Http calls an endpoint you write, and Custom is your own code behind IConnectionResolver. The Arc docs cover them all, and Chronicle’s storage connection resolution page covers what the kernel asks and answers, including SQL storage and schemas.

The contract is plain REST

The Http resolver posts to one endpoint, and that endpoint can be written in anything. This is the request Arc sends for a tenant:

POST /connections
Content-Type: application/json; charset=utf-8
X-Api-Key: dev-only-key

{ "storage": "MongoDB", "purpose": "Runtime", "scope": { "tenant": "acme" } }

This is an answer that places a tenant in its own database with its own login:

{
  "database": "acme-arc",
  "identity": { "userName": "acme", "password": "acme-pw" },
  "expiresAt": "2026-10-17T07:05:51+00:00"
}

204 No Content means “keep the configured connection”, and any other status except 200 fails the connection. That’s the whole connection resolution contract, which also covers caching and security and ships an OpenAPI description. Because the contract doesn’t mention Arc, it’s the seam for the last part of this post.

The example

You’ll run four things: MongoDB and a Chronicle kernel in Docker, a small endpoint that knows your tenants, an Arc application, and a plain client. Two tenants, acme and globex, and one that nobody told the endpoint about, initech.

The infrastructure

MongoDB has to be a replica set because Chronicle appends in transactions, and a replica set with authentication needs a key file:

openssl rand -base64 756 > keyfile

The init script creates one login per tenant. It only allows that tenant into its own -arc database, which is where the Arc application will keep its data:

const admin = db.getSiblingDB("admin");
for (const tenant of ["acme", "globex"]) {
  admin.createUser({
    user: tenant,
    pwd: `${tenant}-pw`,
    roles: [{ role: "readWrite", db: `${tenant}-arc` }]
  });
}

The kernel is configured in the Compose file. The environment variables at the bottom are the whole of Chronicle’s side: a Template resolver on the Connection slot, with a naming rule for the database. The cluster database stays on connectionDetails, as before. The images are pinned by digest, and this is the development image, so it generates its own certificate and OAuth keys. Running Chronicle in production covers what changes for a real deployment.

services:
  mongo:
    image: mongo:8.2@sha256:e0ce8c35124d4a9f9785532d1f268f39e9728ffa1cb38f46fa482436424c4bd3
    command: >
      bash -c "cp /run/keyfile-src /data/keyfile && chmod 400 /data/keyfile && chown mongodb:mongodb /data/keyfile &&
      exec docker-entrypoint.sh mongod --replSet rs0 --bind_ip_all --keyFile /data/keyfile"
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: rootpw
    volumes:
      - ./keyfile:/run/keyfile-src:ro
      - ./mongo/init-tenants.js:/docker-entrypoint-initdb.d/init-tenants.js:ro
    ports:
      - "127.0.0.1:27017:27017"
    healthcheck:
      test: ["CMD", "mongosh", "-u", "root", "-p", "rootpw", "--quiet", "--eval", "try { rs.status().ok } catch (e) { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo:27017'}]}).ok }"]
      interval: 5s
      timeout: 10s
      retries: 20

  chronicle:
    image: cratis/chronicle:19.77.2-development@sha256:91abcf6bc1eba69b7a3887f3dd800ca2630ca39e79c87bb9c01c765047f0c232
    depends_on:
      mongo:
        condition: service_healthy
    environment:
      Cratis__Chronicle__Storage__ConnectionDetails: mongodb://root:rootpw@mongo:27017/?authSource=admin&replicaSet=rs0
      Cratis__Chronicle__Storage__ConnectionResolution__Connection__Resolver: Template
      Cratis__Chronicle__Storage__ConnectionResolution__Connection__Template__Database: "{eventStore}-{namespace}-{kind}"
    ports:
      - "127.0.0.1:35000:35000"

Save the script as mongo/init-tenants.js, the Compose file as compose.yaml, and start it with docker compose up -d.

Chronicle on its own

No Arc yet. This console program uses only the Chronicle client. It appends one event to the orders event store in each of two namespaces:

dotnet new console -n OrdersClient
cd OrdersClient
dotnet add package Cratis.Chronicle --version 19.77.2

using Cratis.Chronicle;
using Cratis.Chronicle.Events;

var client = new ChronicleClient(new ChronicleOptions());

foreach (var tenant in new[] { "acme", "globex" })
{
    var store = await client.GetEventStore("orders", tenant);
    await store.EventLog.Append(Guid.NewGuid().ToString(), new OrderPlaced(tenant, 42));
    Console.WriteLine($"{tenant}: appended");
}

[EventType]
public record OrderPlaced(string Customer, int Total);

Run it, then look in MongoDB. Each namespace’s events are in a database of their own, named by the rule in the Compose file:

docker compose exec mongo mongosh -u root -p rootpw --quiet --eval '
  print("acme:", db.getSiblingDB("orders-acme-namespace").getCollection("event-log").countDocuments({}));
  print("globex:", db.getSiblingDB("orders-globex-namespace").getCollection("event-log").countDocuments({}))'

acme: 1
globex: 1

The projected read models of each namespace get their own database too, orders-acme-readModels, because the rule has {kind} in it. Use {kind} when a namespace’s events and its read models shouldn’t share one. The rule applies to every database Chronicle asks about, so the Default namespace and the event store itself get names from it too, such as orders-Default-namespace and orders--eventStore, where there’s no namespace to fill in. A template only needs configuration, so it works with the standard image. When a rule can’t express your placement, or a login has to differ per tenant, Chronicle’s storage connection resolution page shows the resolvers that call an endpoint or your own code.

The endpoint that knows your tenants

Now the application side. An application that stores its own data per tenant needs somewhere to ask where that is. This is the endpoint. In a real platform it fronts your tenant directory and a secret store, and here it’s a dictionary:

dotnet new web -n Directory

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Your tenant directory. In a real platform this is a service or a database, and the passwords live in a secret store.
var tenants = new Dictionary<string, TenantConnection>
{
    ["acme"] = new("acme-arc", "acme", "acme-pw"),
    ["globex"] = new("globex-arc", "globex", "globex-pw")
};

app.MapPost("/connections", (HttpRequest http, ConnectionRequest request) =>
{
    // The answer holds credentials, so authenticate the caller first.
    if (http.Headers["X-Api-Key"] != "dev-only-key")
    {
        return Results.StatusCode(StatusCodes.Status401Unauthorized);
    }

    // Resolution chooses a destination, so refuse a tenant you do not know instead of guessing one.
    if (!request.Scope.TryGetValue("tenant", out var tenant) || !tenants.TryGetValue(tenant, out var connection))
    {
        return Results.StatusCode(StatusCodes.Status403Forbidden);
    }

    return Results.Ok(new ResolvedConnection(
        Database: connection.Database,
        Identity: new Identity(connection.UserName, connection.Password),
        ExpiresAt: DateTimeOffset.UtcNow.AddMinutes(5)));
});

app.Run("http://localhost:5099");

record TenantConnection(string Database, string UserName, string Password);
record ConnectionRequest(string Storage, string Purpose, Dictionary<string, string> Scope);
record Identity(string? UserName = null, string? Password = null, string? AccessToken = null);
record ResolvedConnection(string? ConnectionString = null, string? Database = null, string? Schema = null, Identity? Identity = null, DateTimeOffset? ExpiresAt = null);

Two things in there matter more than the dictionary. It checks a key before it answers, because the answer holds credentials. And it says no to a tenant it doesn’t know. Resolution picks a destination. It isn’t an authorization check on the person asking, so what the endpoint does with a tenant it can’t place is part of your security model. Run it with dotnet run.

Arc, with Chronicle behind it

The Arc application does two things per tenant. A command records an OrderPlaced event in Chronicle, and another command stores a note in MongoDB. Arc picks the tenant from a header, x-cratis-tenant-id by default, and maps it to the Chronicle namespace, so the first command lands in the namespace the kernel placed above. The second goes through Arc’s own connection resolution, which is configured to call the endpoint.

dotnet new web -n OrdersApp
cd OrdersApp
dotnet add package Cratis --version 22.112.0
dotnet add package Cratis.Arc.MongoDB --version 22.112.0

using Cratis.Arc;

var builder = WebApplication.CreateBuilder(args);

builder.AddCratis(
    configureArcBuilder: arc => arc.WithMongoDB(),
    configureChronicleOptions: chronicle => chronicle.EventStore = "orders");

var app = builder.Build();
app.UseCratis();
app.Run();

using Cratis.Arc.Commands.ModelBound;
using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Events;
using MongoDB.Driver;

[EventType]
public record OrderPlaced(string Customer, int Total);

[Command]
public record PlaceOrder(string Customer, int Total)
{
    public OrderPlaced Handle() => new(Customer, Total);
}

[ReadModel]
public record Note(Guid Id, string Text)
{
    [Path("/api/notes")]
    public static IEnumerable<Note> All(IMongoCollection<Note> notes) => notes.Find(_ => true).ToList();
}

[Command]
public record AddNote(string Text)
{
    public async Task Handle(IMongoCollection<Note> notes) =>
        await notes.InsertOneAsync(new Note(Guid.NewGuid(), Text));
}

The configuration is the other half. Cratis:Arc:ConnectionResolution is the application-wide setting, and Arc’s MongoDB integration reads it. Server and Database stay as they are for anything the endpoint doesn’t answer, and DirectConnection is there because the replica set advertises its Docker name, which your machine can’t reach:

{
  "Cratis": {
    "Arc": {
      "ConnectionResolution": {
        "Connection": {
          "Resolver": "Http",
          "Http": {
            "Endpoint": "http://localhost:5099/connections",
            "Headers": { "X-Api-Key": "dev-only-key" }
          }
        }
      }
    },
    "MongoDB": {
      "Server": "mongodb://localhost:27017/?authSource=admin",
      "Database": "arc",
      "DirectConnection": true
    }
  }
}

Run it with dotnet run --urls http://localhost:5200 and send the same two commands for each tenant:

for tenant in acme globex initech; do
  curl -s -X POST http://localhost:5200/api/place-order \
    -H "x-cratis-tenant-id: $tenant" -H 'content-type: application/json' \
    -d "{\"customer\":\"$tenant-customer\",\"total\":42}"
  curl -s -X POST http://localhost:5200/api/add-note \
    -H "x-cratis-tenant-id: $tenant" -H 'content-type: application/json' \
    -d "{\"text\":\"note for $tenant\"}"
done

Two things decided two ways. The kernel placed the events by rule, and the endpoint placed the notes by answer.

Both commands succeed for acme and globex. For initech, the order succeeds and the note fails. Chronicle’s template doesn’t know who’s allowed to exist. It places any namespace it’s asked about, so initech got its own events database. The endpoint did know, answered 403, and Arc refused to open a connection. The kernel and your endpoint don’t coordinate, so checking that a tenant is real belongs in your application, before it touches either. The tenancy post goes through why a header isn’t proof of membership.

Each tenant now reads back only its own notes:

curl -s http://localhost:5200/api/notes -H "x-cratis-tenant-id: acme"

{ "data": [{ "id": "2a861236-e51d-41f3-93fc-281d08ca1d6f", "text": "note for acme" }], "isSuccess": true }

And the login the endpoint hands out really is limited. This is acme trying to read globex’s database, and then its own:

docker compose exec mongo mongosh -u acme -p acme-pw --authenticationDatabase admin --quiet --eval '
  try { db.getSiblingDB("globex-arc").getCollection("Notes").find().toArray() }
  catch (e) { print("globex-arc:", e.codeName) }
  print("acme-arc:", db.getSiblingDB("acme-arc").getCollection("Notes").countDocuments({}))'

globex-arc: Unauthorized
acme-arc: 1

Arc is optional

Everything Arc did on the application side was ask that endpoint a question and open a connection with the answer. You can do that yourself. This console program knows nothing about Arc. It posts the same request, keeps the answer until a minute before it expires, and builds a MongoDB client with the identity it was given:

dotnet new console -n OwnClient
cd OwnClient
dotnet add package MongoDB.Driver --version 3.12.0

using System.Collections.Concurrent;
using System.Net.Http.Json;
using MongoDB.Bson;
using MongoDB.Driver;

var resolver = new TenantConnections(new Uri("http://localhost:5099/connections"), "dev-only-key");

foreach (var tenant in new[] { "acme", "globex", "initech" })
{
    try
    {
        var notes = (await resolver.DatabaseFor(tenant)).GetCollection<BsonDocument>("Notes");
        await notes.InsertOneAsync(new BsonDocument { ["_id"] = Guid.NewGuid().ToString(), ["Text"] = $"own client, {tenant}" });
        Console.WriteLine($"{tenant}: {await notes.CountDocumentsAsync(FilterDefinition<BsonDocument>.Empty)} notes");
    }
    catch (HttpRequestException exception)
    {
        Console.WriteLine($"{tenant}: refused ({(int?)exception.StatusCode})");
    }
}

record Identity(string UserName, string Password);
record Resolved(string Database, Identity Identity, DateTimeOffset ExpiresAt);

class TenantConnections(Uri endpoint, string apiKey)
{
    const string Server = "mongodb://localhost:27017/?authSource=admin&directConnection=true";

    readonly HttpClient _http = new() { DefaultRequestHeaders = { { "X-Api-Key", apiKey } } };
    readonly ConcurrentDictionary<string, Resolved> _cache = new();

    public async Task<IMongoDatabase> DatabaseFor(string tenant)
    {
        if (!_cache.TryGetValue(tenant, out var resolved) || resolved.ExpiresAt < DateTimeOffset.UtcNow.AddMinutes(1))
        {
            var response = await _http.PostAsJsonAsync(endpoint, new { storage = "MongoDB", purpose = "Runtime", scope = new { tenant } });
            response.EnsureSuccessStatusCode();
            resolved = _cache[tenant] = (await response.Content.ReadFromJsonAsync<Resolved>())!;
        }

        var settings = MongoClientSettings.FromConnectionString(Server);
        settings.Credential = MongoCredential.CreateCredential("admin", resolved.Identity.UserName, resolved.Identity.Password);
        return new MongoClient(settings).GetDatabase(resolved.Database);
    }
}

acme: 2 notes
globex: 2 notes
initech: refused (403)

It sees the notes Arc wrote, since they’re in the same database, and initech is refused by the same endpoint for the same reason. The code isn’t production code, and the difference between it and Arc is what Arc is for. Arc builds the client and the database from the resolution for each request scope, so the IMongoCollection<Note> in a handler is already the right tenant’s. It caches the way the contract says and drops the cached answer when a login fails, so a rotated credential is picked up on the next attempt. It refreshes an access token when the MongoDB driver asks for one. And one application-wide configuration serves every storage Arc integrates with, so you set it once.

If you’re on Kotlin, TypeScript, Elixir or anything else, the contract is the thing to hold on to, not Arc’s class names. A client in another language posts the same JSON and builds a connection with the answer, and the endpoint doesn’t know the difference. Chronicle itself, whichever client you use, resolves its own storage on the kernel side as in the Compose file, so a tenant’s events are placed the same way no matter who appends them.

What this doesn’t do

It doesn’t authorize anyone. The initech row is the example. A tenant header or tenant id selects a destination, and checking membership is your job before any tenant-scoped work.
It doesn’t move data. Changing the resolution of an existing database points Chronicle or Arc at a new place, and the old data stays where it was. In Arc, a resolved Database replaces the default {Database}+{tenant} naming entirely, including for the default tenant, so switching is a data migration.
It doesn’t make secrets safe by itself. The endpoint’s answer holds credentials: serve it over HTTPS, authenticate the caller, and prefer short-lived access tokens with an expiresAt over long-lived passwords. The example uses plain HTTP and a key in a header because it runs on one machine.
It doesn’t replace the rest of your isolation. Arc’s tenant isolation is a separate concern from where a connection goes, and the Arc tenancy docs keep the two apart.

What to take from this

If your platform already knows where each tenant lives, you no longer have to bend Chronicle’s and Arc’s naming around that. Start with what you can say in configuration. A template covers a naming rule, and it needs no code on either side. Add an endpoint when you need a per-tenant login or a lookup, and write the endpoint once, because the contract is the same for MongoDB and SQL storage.

Then decide how much of the client you want to own. Arc gives you the caching, the scoping and the pooling for free. A hand-written client gives you the same placement in a few dozen lines and with whatever driver you already use.

The pages to read next are Arc’s connection resolution, the MongoDB page, Chronicle’s storage connection resolution and the contract. Tell me where it’s still confusing on Discord.

DCB, but not DCB

Fri, 16 Oct 2026 00:00:00 GMT

TL;DR

Dynamic Consistency Boundary (DCB) is a good idea with an awkward name. What I care about is smaller and easier to explain: model your events however the business needs, make it obvious which one thing owns the events it produces, and let that owner state, per command, what has to hold when it decides. Chronicle and Arc give you a tool for each, and Arc’s new read protection (Arc 22.106, with Chronicle 19.71) makes the most common one a lot less ceremony. Chronicle’s own documentation is upfront that it isn’t a DCB event store, and that points at a better vocabulary.

The C# in this post uses .NET 10, Chronicle 19.73.1 and Arc 22.109.0.

Why I’m retiring the acronym

In March I wrote about Dynamic Consistency Boundaries and how Chronicle fits, on my own blog. The core of the idea is good: a command reads the events it needs, remembers the position of the last one it saw, and appends only if nothing relevant has arrived since. The consistency boundary comes from what the decision used, not from an object you drew up front. The DCB specification builds an event store around that, with tags on events as the way to say what an event concerns.

Chronicle doesn’t do it that way, and the docs say so plainly: Chronicle “supports DCB-style decision models and append conditions within its event-source model. It is not a DCB event store.” Each event has exactly one event source id, and tags you add yourself are labels and filters, not part of the consistency check. A fact about two entities is usually written as two events in one atomic append.

That’s the reason for this post. I’m not asking anyone to stop reading about DCB. The spec is worth knowing, and my constraints post from last week leaned on it. I’m asking us to stop using it as the name for what Chronicle does, because the name needs a footnote every time. “DCB” has a second problem too: it sounds like a theory you need to subscribe to before you can write a command. You don’t. What you need is three things, and each of them has a plain name.

Three things worth naming. None of them needs the acronym.

This post takes them in turn, shows what Chronicle and Arc give you for each, and ends with where the Decider pattern fits and where it doesn’t. The mechanisms themselves, constraints, scopes, decision reads and aggregates, are covered in depth in Part 5 of the Script to stage series, and the Decisions that hold series takes read protection one rule at a time. This one is about how they fit together and why.

Flexibility in modeling

The point of drawing the consistency boundary at decision time, and not at design time, is that you don’t have to guess your access patterns in advance. The classic aggregate root asks you to decide up front which facts belong together. Get it wrong and you either serialize things that never needed it or protect too little. Chronicle gives you smaller pieces to build the boundary from.

An event belongs to an event source, identified by an EventSourceId (or a typed EventSourceId<T>, so a book isn’t a member in the type system either). On top of that you can add formalized, single-valued stream metadata: an event source type, an event stream type and an event stream id. A concurrency scope can filter on any of those, plus event types, and it can narrow or widen without touching the events themselves. Those four are different from custom tags: custom tags are stored and filterable, but they don’t take part in consistency.

You can declare that structure once with an event source definition, which every client in the table below supports and which needs a Chronicle 19.30 kernel. Here an account has streams, and each stream says which dimensions an append to it is checked on. In C# Onboarding is one stream, and Transactions is one stream per month, so the month is part of what an append is checked against. The other tabs are the published declarations from each client’s docs, with their own stream names:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSources;

[EventType]
public record MoneyDeposited(decimal Amount);

[EventSource("Account", Description = "A customer's bank account", Concurrency = ConcurrencyDimensions.EventSourceId)]
[EventStream("Onboarding", Description = "Opening the account and verifying the customer")]
[EventStream(
    "Transactions",
    Description = "Deposits and withdrawals, one stream per month",
    Concurrency = ConcurrencyDimensions.EventSourceId | ConcurrencyDimensions.EventStreamType | ConcurrencyDimensions.EventStreamId)]
public class AccountEventSource : IEventSource;

public static class Deposits
{
    public static Task<AppendResult> Deposit(IEventLog eventLog, EventSourceId accountId, decimal amount, string month) =>
        eventLog.Append<AccountEventSource>(
            accountId,
            new MoneyDeposited(amount),
            eventStream: "Transactions",
            eventStreamId: month);
}

import io.cratis.chronicle.eventSources.ConcurrencyDimension
import io.cratis.chronicle.eventSources.EventSource
import io.cratis.chronicle.eventSources.EventStream

@EventSource(
    name = "Account",
    description = "A customer account",
    concurrency = [ConcurrencyDimension.EventSourceId],
    streams = [
        EventStream(
            name = "Transactions",
            description = "Money in and out",
            concurrency = [
                ConcurrencyDimension.EventSourceId,
                ConcurrencyDimension.EventStreamType
            ]
        ),
        EventStream("Settings")
    ]
)
class AccountEventSource

import io.cratis.chronicle.eventSources.ConcurrencyDimension;
import io.cratis.chronicle.eventSources.EventSource;
import io.cratis.chronicle.eventSources.EventStream;

@EventSource(
    name = "Account",
    description = "A customer account",
    concurrency = ConcurrencyDimension.EventSourceId,
    streams = {
        @EventStream(
            name = "Transactions",
            description = "Money in and out",
            concurrency = {
                ConcurrencyDimension.EventSourceId,
                ConcurrencyDimension.EventStreamType
            }),
        @EventStream(name = "Settings")
    })
class AccountEventSource {
}

import { ConcurrencyDimensions, eventSource, eventStream } from '@cratis/chronicle';

@eventSource({ name: 'Account', description: 'A bank account', concurrency: ConcurrencyDimensions.eventSourceId })
@eventStream('Transactions', { description: 'Money movements' })
class AccountEventSource {}

defmodule MyApp.AccountEventSource do
  use Chronicle.EventSources.EventSource,
    name: "Account",
    description: "A bank account",
    concurrency: [:event_source_id]

  stream "Transactions",
    description: "Money movements",
    concurrency: [:event_source_id, :event_stream_id]
end

A deposit in April and a deposit in May don’t contend. The guard is asymmetric, though: a deposit doesn’t look at onboarding events, but an onboarding append is checked against every event of the account, deposits included. The first deposit into a brand-new month has nothing to compare against, so by default it isn’t checked at all; you opt in with CheckFirstAppendIntoAScope or ExpectingNoMatchingEvent() (withExpectsNoMatchingEvent() in Kotlin and Java, EventSequenceNumber.beforeFirst in TypeScript, check_first_append or ConcurrencyScope.expecting_no_matching_event/1 in Elixir). Nobody had to restructure an aggregate to get this shape, and you can change which dimensions guard an append by editing the declaration. Events that are already stored keep the stream names they were written with. The event source docs show the full conflict table.

One identity, several streams. Each stream’s guard covers the dimensions it declares.

You can also build a scope by hand when you need one. It states what an append expects about the history it was decided on: a position, plus the event source, stream and event types that matter. Narrower scopes mean fewer false conflicts. Each tab builds a scope from a position and a stream type, and the C#, TypeScript and Elixir ones also name the event types it watches. The 15 stands for the tail position you captured before reading:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;

[EventType]
public record ConcurrencyMoneyDeposited(decimal Amount);

[EventType]
public record ConcurrencyMoneyWithdrawn(decimal Amount);

public class ConcurrencyAccountTransactionService(IEventLog eventLog)
{
    public async Task ProcessTransaction(EventSourceId accountId, decimal amount)
    {
        var concurrencyScope = new ConcurrencyScopeBuilder()
            .WithEventSourceId(accountId)
            .WithSequenceNumber(15)
            .WithEventStreamType("Transactions")
            .WithEventType<ConcurrencyMoneyDeposited>()
            .WithEventType<ConcurrencyMoneyWithdrawn>()
            .Build();

        await eventLog.Append(
            accountId,
            new ConcurrencyMoneyDeposited(amount),
            concurrencyScope: concurrencyScope);
    }
}

import io.cratis.chronicle.IEventStore
import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.eventSequences.AppendOptions
import io.cratis.chronicle.eventSequences.EventSequenceNumber
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder

@EventType
data class ConcurrencyMoneyDeposited(val amount: Double = 0.0)

suspend fun processTransaction(store: IEventStore, accountId: String, amount: Double) {
    val concurrencyScope = ConcurrencyScopeBuilder()
        .withEventSourceId()
        .withSequenceNumber(EventSequenceNumber(15))
        .withEventStreamType("Transactions")
        .build()

    store.eventLog.append(
        accountId,
        ConcurrencyMoneyDeposited(amount),
        AppendOptions(eventStreamType = "Transactions", concurrencyScope = concurrencyScope)
    )
}

import io.cratis.chronicle.EventStore;
import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.eventSequences.AppendOptions;
import io.cratis.chronicle.eventSequences.AppendResult;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScope;
import io.cratis.chronicle.eventSequences.concurrency.ConcurrencyScopeBuilder;

import io.cratis.chronicle.java.AppendOptionsBuilder;
import io.cratis.chronicle.java.ConcurrencyScopeBuilderJavaBridge;
import io.cratis.chronicle.java.EventLogJavaBridge;

@EventType
record ConcurrencyMoneyDeposited(double amount) {}

class EventsConcurrencyBuilder {
    AppendResult processTransaction(EventStore store, String accountId, double amount) {
        ConcurrencyScope concurrencyScope = ConcurrencyScopeBuilderJavaBridge
            .withSequenceNumber(new ConcurrencyScopeBuilder(), 15)
            .withEventSourceId()
            .withEventStreamType("Transactions")
            .build();

        AppendOptions options = new AppendOptionsBuilder()
            .eventStreamType("Transactions")
            .concurrencyScope(concurrencyScope)
            .build();

        return EventLogJavaBridge.append(store.getEventLog(), accountId, new ConcurrencyMoneyDeposited(amount), options);
    }
}

import { eventType, getEventTypeFor, IEventLog } from '@cratis/chronicle';
import { field } from '@cratis/fundamentals';

@eventType()
class ConcurrencyMoneyDeposited {
    @field(Number) readonly amount: number;

    constructor(amount: number) {
        this.amount = amount;
    }
}

@eventType()
class ConcurrencyMoneyWithdrawn {
    @field(Number) readonly amount: number;

    constructor(amount: number) {
        this.amount = amount;
    }
}

class ConcurrencyAccountTransactionService {
    constructor(private readonly eventLog: IEventLog) {}

    async processTransaction(accountId: string, amount: number): Promise<void> {
        await this.eventLog.append(accountId, new ConcurrencyMoneyDeposited(amount), {
            concurrencyScope: {
                sequenceNumber: 15n,
                eventStreamType: 'Transactions',
                eventTypes: [getEventTypeFor(ConcurrencyMoneyDeposited), getEventTypeFor(ConcurrencyMoneyWithdrawn)]
            }
        });
    }
}

defmodule MyApp.Events.ConcurrencyMoneyDeposited do
  use Chronicle.Events.EventType, id: "concurrency-money-deposited"

  defstruct [:amount]
end

defmodule MyApp.Events.ConcurrencyMoneyWithdrawn do
  use Chronicle.Events.EventType, id: "concurrency-money-withdrawn"

  defstruct [:amount]
end

defmodule MyApp.ConcurrencyAccountTransactionService do
  alias Chronicle.Events.ConcurrencyScope
  alias MyApp.Events.{ConcurrencyMoneyDeposited, ConcurrencyMoneyWithdrawn}

  def process_transaction(account_id, amount) do
    # Pipe-able builder helpers compose a scope step by step.
    scope =
      15
      |> ConcurrencyScope.new()
      |> ConcurrencyScope.with_event_source()
      |> ConcurrencyScope.with_event_stream_type("Transactions")
      |> ConcurrencyScope.with_event_types([ConcurrencyMoneyDeposited, ConcurrencyMoneyWithdrawn])

    Chronicle.append(account_id, %ConcurrencyMoneyDeposited{amount: amount},
      concurrency_scope: scope
    )
  end
end

The default differs by client, and that matters more than the syntax. The .NET client checks the window between its tail read and the write unless you say otherwise. The Kotlin, Java, TypeScript and Elixir clients send no check unless you give the append a scope. In .NET, a scope you build yourself from a stream that had no events yet, so there was no position to capture, is checked as “no matching event yet” since Chronicle 19.68 instead of being skipped; ConcurrencyOptions.SkipIncompleteExplicitScopes restores the old skip. The client differences page has the details. Even in .NET, that default only covers the short window at commit. It doesn’t bind a decision to the state you read before it, which is the whole subject of the third section.

One clear owner for every event

Flexibility on its own turns into a mess. Once events can be shaped any way you like, the question that keeps a codebase understandable is who is allowed to say that this happened.

My answer is one owner: the command that produces an event, with the event source deciding which stream the event joins. Every event type belongs to the slice that produces it, and the rules for producing it live there too. In a Cratis application that’s a house convention (the event type is declared in the slice that appends it), and Chronicle’s event source model backs it up from the other side: an event has exactly one event source id, so there’s exactly one stream whose history it becomes part of.

That’s a deliberate limit, and it has a cost. A fact about two entities, say a member taking a loan that affects both the member and the book, is usually two events, one for each event source, appended together in one atomic AppendMany. That’s fine when each is a fact in its own entity’s story, a loan on the member and a copy taken from the book. DCB’s tags would let you write one event and tag it with both, and this is the one place where Chronicle gives that up. When it’s really the same fact twice, the Chronicle docs suggest looking for one event on one source with a decision read over the other. In practice the limit keeps ownership readable. You never have to ask which of three concepts an event “really” belongs to.

In Arc the owner is the command, and the command’s return value is the proof. Handle() returns the events, Arc appends them in the command’s transaction, and if you return several EventForEventSourceId values they commit together or not at all. There’s no IEventLog injected into the middle of business logic. The same goes for an Arc aggregate root, which is an owner with explicit state: it rehydrates from its own entity’s stream and commits what it applied. Same idea, different amount of ceremony.

Rules that belong to the command

This is where most of the confusion sits, so I’ll slow down. The question isn’t which feature to use. It’s what kind of rule you have, because different rules need different guards, and the wrong tool fails silently. The command runs, nobody sees an error, and the rule is broken anyway.

The rule decides the tool. Chronicle’s choosing guide and Arc’s consistency page carry the full matrix.

Uniqueness belongs to the store

A value that must be unique, a username or an email or an ISBN, is the one rule that’s best not decided in a command at all. A constraint is checked by the Chronicle kernel when the event is appended, for every writer, and an append that would break it is rejected. It’s a cheap check, every client in the table below has constraints, and it’s why they sit first on every list. I wrote about them in Invariants at write time, and Part 5 shows the declaration in each client. This is what it looks like on an event in C#:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Events.Constraints;
using Cratis.Concepts;

public record ProjectName(string Value) : ConceptAs<string>(Value);

public record ProjectDescription(string Value) : ConceptAs<string>(Value);

[EventType]
public record ProjectCreated([property: Unique] ProjectName Name, ProjectDescription Description);

A rule over state: the read you decide from

Everything else that depends on state needs a read, and here’s the trap. A read model is an answer to “what does this look like now?” It was never promised to be the state a decision was made on. A materialized read model can lag. A passive one is fresh at the moment you read it, but it doesn’t remember where the log was, so an event that lands between your read and your append goes unnoticed. Arc’s validators page lays out the sequence: two members borrow the last copy at the same time, both validators read one available, both pass, both events are appended.

This is the part my March post got wrong, and I’d rather fix it in public. It showed a validator reading a read model to enforce a business rule and presented that as the DCB way. In Chronicle and Arc as they were then, that guarded nothing, and the post also described the default append check incorrectly. Since then Arc has changed what that pattern can mean, which I’ll get to in a moment. A read model is still the right thing for a hint on screen. By default it’s still the wrong thing to decide from.

The difference is the position. A decision read notes where the log was before it read.

A decision read folds a flat projection from the log in a fresh session and notes the log position first. The append it guards is then rejected if a matching event arrived after that position. An absent model is guarded too, so a concurrent creation conflicts. Decision reads need Chronicle 19.9 or later, and in Arc you opt a command in with [ProtectedDecision] from Arc 22.39, take the state as DecisionRead<T>, and return the event, or a Result that declines:

using Cratis.Arc.Chronicle.ReadModels;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Arc.Validation;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections.ModelBound;
using Cratis.Chronicle.ReadModels;
using Cratis.Concepts;
using Cratis.Monads;

public record MemberId(Guid Value) : ConceptAs<Guid>(Value);

[EventType]
public record CopyAdded();

[EventType]
public record BookBorrowed(MemberId MemberId);

[EventType]
public record BookReturned();

public record BookStock(
    EventSourceId Id,
    [Increment<CopyAdded>, Decrement<BookBorrowed>, Increment<BookReturned>] int Available);

[Command]
[ProtectedDecision]
public record BorrowBook(EventSourceId BookId, MemberId MemberId)
{
    public Result<BookBorrowed, ValidationResult> Handle(DecisionRead<BookStock> stock) =>
        stock.Instance is not { Available: > 0 }
            ? ValidationResult.Error("No copies of this book are available.")
            : new BookBorrowed(MemberId);
}

Arc for Elixir doesn’t exist. With the Chronicle Elixir client, Chronicle.decide/2 runs the read and the guarded append in one unit of work:

Chronicle.decide(fn _unit_of_work ->
  {:ok, read} = Chronicle.ReadModels.DecisionReads.get(MyApp.ReadModels.Seat, "seat-5")

  if read.instance == nil do
    Chronicle.EventSequences.EventLog.append("seat-5", %SeatBooked{by: "alice"})
  end
end)

If two members race for the last copy, the second one gets a validation result with the reason concurrencyViolation. Nothing is appended, and Arc and Chronicle don’t re-run the command. The caller reads again and resubmits. That cost is real: a decision read folds the key’s whole history on every attempt, and the docs advise keeping keys short-lived (a key per period, per order, per booking) and flat. It guards the event log for the keys it reads. Revisions, redactions, other event sequences and data from outside Chronicle aren’t covered. When the rule is about one routed stream of raw events, Arc’s stream decisions do the same job without folding a projection.

Read protection: the same guard, without the ceremony

Arc 22.106 added a second way to get the same guard, and for most commands it’s the one I’d reach for first. With read protection switched on, a read model you take as a parameter of a command or its validator is read the way a decision read is: fresh, with the log position noted first. If anything it read changed before the commit, nothing is written and the caller gets a 400 with the same concurrencyViolation, the detail ReadChanged, and a message saying which read model changed: “BookStock ‘isbn-1’ changed after BorrowBook read it. Nothing from this command was written; submit it again.” It needs Chronicle 19.71 or later, and it’s off by default, so nothing changes until you ask. New applications from the Cratis templates start with it On. You turn it on for the whole assembly with <CratisReadProtection>On</CratisReadProtection>, or for one command with [ReadProtection(ReadProtectionMode.On)]. There’s a Measure mode that changes no behavior and reports what On would guard or refuse, which is how I’d adopt it in an existing application.

The practical difference is where the rule lives. With a protected decision it’s in Handle(). With read protection the rule can sit in an ordinary CommandValidator<T>, the read model arrives as a constructor parameter, and Handle() only says what happens:

using Cratis.Arc.Commands;
using Cratis.Arc.Commands.ModelBound;
using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections.ModelBound;
using Cratis.Concepts;
using FluentValidation;

public record Isbn(string Value) : EventSourceId(Value);

public record MemberId(Guid Value) : ConceptAs<Guid>(Value);

[EventType]
public record CopyAdded();

[EventType]
public record BookBorrowed(MemberId Member);

[EventType]
public record BookReturned(MemberId Member);

[ReadModel]
public record BookStock(
    Isbn Id,
    [Increment<CopyAdded>, Decrement<BookBorrowed>, Increment<BookReturned>] int Available);

[Command, ReadProtection(ReadProtectionMode.On)]
public record BorrowBook(Isbn Isbn, MemberId Member)
{
    public BookBorrowed Handle() => new(Member);
}

public class BorrowBookValidator : CommandValidator<BorrowBook>
{
    public BorrowBookValidator(BookStock? stock) =>
        RuleFor(command => command.Isbn)
            .Must(_ => stock is { Available: > 0 })
            .WithMessage("No copies of this book are available.");
}

BookStock? is nullable because a book with no events has no read model yet; a non-nullable parameter refuses the command before any rule runs. Let convention discovery register the validator: under On, one you register by hand as scoped, as a singleton, through a factory or as an instance is refused.

That’s the March pattern, and under On it holds. The same code under the default Off is a plain read again, which is why I’d rather the mode be visible on the command than hidden in a build property you forget about. When a read is meant as a hint, [Unprotected("why")] says so, and under On reads Arc can’t protect, such as a raw event log read, are refused with a message that says why. From Arc 22.108, a command declared On also blocks on validator errors whatever severity the caller asks to allow with X-Allowed-Severity; under Off and Measure a caller can drop them unless the command declares [BlockOnValidationSeverity(ValidationResultSeverity.Error)]. [ProtectedDecision] and DecisionRead<T> keep working, but under On you don’t need them.

It’s .NET only, like [ProtectedDecision]. The Arc getting started guide walks through it and adopting read protection covers Measure. The cost is the one decision reads have: the read folds the history it covers on every attempt, and nothing re-runs the command for you.

Chronicle 19.71 also fixed the cost problem I mentioned for long histories. A read model can declare the one stream that defines its state with [EventStream<TSource>(stream)], say a month of withdrawals. Taken as a plain parameter, it’s read from the stream the command’s route points to, so October’s withdrawals don’t make November’s command conflict. That’s the “key per period” advice, without inventing a key. Arc’s one stream scenario has the monthly-limit example.

Validators check the input, and with read protection a bit more

Validation is the one most people already know, and it keeps its job. A validator checks the shape of the input, and a shape check has no state to race. Arc 22.106 adds one thing: under read protection On, a validator that takes a read model also guards that read, which the section above shows. In C# that’s CommandValidator<T> and ConceptValidator<T> with FluentValidation rules, which Arc also maps into the generated TypeScript proxies so the browser can check the same thing. Arc for Kotlin and Java has a CommandValidator and its own validators, and Arc’s frontend core has a ruleFor API that mirrors the common rules. The rule of thumb is the same in all of them:

using Cratis.Arc.Commands;
using FluentValidation;

public class BorrowBookValidator : CommandValidator<BorrowBook>
{
    public BorrowBookValidator() =>
        RuleFor(command => command.MemberId)
            .NotEmpty()
            .WithMessage("A member is required.");
}

@Component
class CreateTaskValidator : CommandValidator<CreateTask> {
    override val commandType = CreateTask::class.java

    override suspend fun validate(command: CreateTask, context: CommandContext): List<ValidationResult> =
        if (command.title.isBlank()) {
            listOf(ValidationResult.error("A task title is required.", listOf("title")))
        } else {
            emptyList()
        }
}

public class CreateTaskValidator implements BlockingCommandValidator<CreateTask> {
    @Override
    public Class<CreateTask> getCommandType() {
        return CreateTask.class;
    }

    @Override
    public List<ValidationResult> validate(CreateTask command, CommandContext context) {
        if (command.title().isBlank()) {
            return List.of(ValidationResult.error("A task title is required.", List.of("title")));
        }
        return List.of();
    }
}

@Configuration
class ValidationConfiguration {
    @Bean
    CommandValidator<CreateTask> createTaskValidator() {
        return new BlockingCommandValidatorAdapter<>(new CreateTaskValidator());
    }
}

class CreateUserCommandValidator extends CommandValidator<ICreateUserCommand> {
    constructor() {
        super();
        this.ruleFor(c => c.email).notEmpty().emailAddress();
        this.ruleFor(c => c.age).greaterThanOrEqual(18);
        this.ruleFor(c => c.name).minLength(2).maxLength(50);
    }
}

A validator can take a read model as a constructor dependency, and it’ll run. Whether it guards anything depends on the mode. Under read protection On it does, as above. Under the default Off, and under Measure, it doesn’t, and outside On a [ProtectedDecision] command only accepts validators with a single parameterless constructor, refusing the rest when the command runs. So the split is clean for a protected decision: the validator says whether the input is well formed, Provide() fetches data, and Handle() decides, returning events or a Result<TEvent, ValidationResult> that declines whatever severity the caller allows. With read protection you can instead put the state-dependent rule in the validator. The Arc page on validators and consistency has the full table.

Aggregates are one owner with its own state

I haven’t forgotten aggregate roots. Arc has them, for .NET only, and the docs treat them as a legitimate choice for rich behavior: many rules over one lifecycle, where “withdraw 200” has to be checked against this account’s own history. An aggregate root rehydrates from its entity’s events, applies new facts under its own rules, and commits them as one unit.

using Cratis.Arc.Chronicle.Aggregates;
using Cratis.Chronicle.Events;
using Cratis.Concepts;

public record OrderId(Guid Value) : EventSourceId<Guid>(Value)
{
    public static readonly OrderId NotSet = new(Guid.Empty);

    public static OrderId New() => new(Guid.NewGuid());
    public static implicit operator OrderId(Guid value) => new(value);
}

public record ProductId(Guid Value) : EventSourceId<Guid>(Value)
{
    public static readonly ProductId NotSet = new(Guid.Empty);

    public static ProductId New() => new(Guid.NewGuid());
    public static implicit operator ProductId(Guid value) => new(value);
}

public record Quantity(int Value) : ConceptAs<int>(Value)
{
    public static readonly Quantity NotSet = new(0);

    public static implicit operator Quantity(int value) => new(value);
}

public class Order : AggregateRoot
{
    int _quantity;

    public async Task AddItem(ProductId productId, Quantity quantity)
    {
        if (quantity <= 0 || quantity > 100 - _quantity)
        {
            Failed("Quantity must be positive and the order total must not exceed 100.");
            return;
        }

        await Apply(new ItemAdded(productId, quantity));
    }

    public void OnItemAdded(ItemAdded @event) => _quantity += @event.Quantity;
}

[EventType]
public record ItemAdded(ProductId ProductId, Quantity Quantity);

Arc takes the stream’s position when it rehydrates and guards the commit with a scope built from it, so an aggregate rests on scopes, not on decision reads. It’s a good fit when the rules belong together on one key. It’s more than you need when one counter rule would do, and the docs say as much. They also say you can’t mix an aggregate with [ProtectedDecision] on the same command. Under read protection On, a command can take an aggregate and a read model of a different source; a read of the aggregate’s own source is refused.

Where the Decider fits

If you know Jérémie Chassaing’s Decider pattern, here’s where I’d place all this. A decider is a decide function from a command and a state to events, an evolve function from a state and an event to a new state, an initial state, and a way to tell when the process is finished. Nothing in the Cratis docs calls Chronicle or Arc a decider, so this mapping is mine, and I’d say a protected-decision command reminds me of one more than it implements one.

Where the four parts of a decider land. The fit is loose, and the gaps matter.

decide is Handle(), with the state coming in as DecisionRead<T> and the events going out as the return value. With read protection it can also be a validator over a read-model parameter plus a Handle() that says what happens, which is a looser fit. evolve is the projection that builds the state, or an aggregate’s On methods. The initial state is the absent model: Instance is null, and an absent model is guarded too. The nearest thing to a terminal state is closing a stream, which the kernel enforces as a constraint.

The differences matter. A decider composes: you can combine two and map over them. Chronicle doesn’t offer that, and a decision read refuses projections that join entities, so a rule over two keys is two decision reads (with read protection, two read-model parameters with [LookUpBy]) and one or two events in one AppendMany. The guard lives in the store as the append condition and not in the decider’s type. Uniqueness, which a decider can’t express without the whole set of values as its state, sits outside it entirely as a constraint. And a decision read folds the key’s history from the log on every attempt, where a decider’s state is just whatever you carried forward. So if “decider” helps you design a command, use it. I wouldn’t promise anyone the whole pattern.

What each client has

The three capabilities don’t arrive at the same time in every language. This is what’s in the released clients and Arc ports named here:

Capability	.NET	Kotlin / Java	TypeScript	Elixir
Constraints (`unique`)	Yes	Yes	Yes	Yes
Concurrency scopes	Yes	Yes	Yes	Yes
Default append check	Optimistic tail read	None	None	None
Event source definitions	Yes	Yes	Yes	Yes
Decision reads	Yes	No	No	Yes
Closing-stream constraint	Yes	No	No	Yes
Read protection (`[ReadProtection]`, Arc 22.106)	Arc for .NET	No	No	No Arc
`[ProtectedDecision]`, aggregate roots	Arc for .NET	No	No	No Arc
Command validators	`CommandValidator<T>`, `ConceptValidator<T>`	`CommandValidator`, `ConceptValidator`	Arc’s frontend core only	No Arc

If you’re not on .NET, the practical advice is the same one the docs give: use constraints for uniqueness, pass an explicit scope built from a position you captured before you read, and keep rules that need a decision read in a .NET service for now. Plainly: the clients aren’t interchangeable, and the decision capabilities haven’t reached all of them yet.

What to do on Monday

You don’t need to adopt anything to use this. For the next command you write, ask three questions.

Who owns this? Which slice produces the event, and is it the only one? If a fact concerns two entities, are you ready to write two events in one append?
What has to hold when it’s decided? Name the rule. Is it a unique value, a rule over one key’s history, a conflict between two people editing, or something that’s fine to repair afterward?
Which row of Arc’s decision matrix is that? Constraint, decision read, stream decision, explicit scope, aggregate or a repair. If your answer is “I read a read model first”, either turn on read protection for that command or accept that you’re shipping a hint and calling it a rule.

From there, Part 5 goes deep on each mechanism, the consistency page in Arc’s docs has the decision matrix and the list of failures that are silent, and the Chronicle DCB page is the place to start if you want the original idea. Tell me where this is still confusing on Discord.

Inside Cratis Studio: built on the platform it's for

Fri, 16 Oct 2026 00:00:00 GMT

TL;DR

Cratis Studio is a handful of services in front of a Chronicle event store: an edge (AuthProxy) that signs you in and works out which organization you belong to, a lobby (Ante) that handles invitations, and the Studio application itself. Core, the lobby, the admin console and the catalog each keep their own event store, and they pass each other facts. Studio is built with Chronicle, Arc, Components and the rest of the platform.

Why show the architecture

Cratis Studio is a collaborative workspace where people and AI agents design, visualize and edit the same event model. That post is about what you can do with it. This one is about what’s behind it, because Studio is also a real application built on the same packages you’d install, and I think showing how it’s put together is the most honest way to show what those packages are for.

I’ll keep this at the level of shapes and responsibilities.

The shape of it

The edge sits in front of the product. Chronicle is where the facts live.

The services, and what each one is for:

Service	What it does
Core	The product: the event-model board and canvas, projects and domains, live collaboration, the AI agents, Play and code generation, and the people in an organization.
Lobby	Ante as a published image. Invitations and the acceptance of legal terms.
AuthProxy	The edge. Sign-in, organization and identity for the services behind it.
MCP	The MCP server Studio offers external AI agents to read and change an organization’s event models and brainstorming boards.
Admin	Internal tooling for running Studio.
Catalog	The product catalog.
Viewer	A read-only viewer of an event model.
GitHub integration	Connects Studio to GitHub.

There’s no separate “workers” service. The background work runs inside Core.

Studio doesn’t ship a language model. Cratis Studio’s AI agents can generate modules, features and slices from a prompt, explain a domain, feature or module, and answer in chat on the model. They run on a model provider your organization configures, and AI stays off until one is set up.

The request path

One path in, one namespace out.

A request arrives over TLS at the ingress and is handed to AuthProxy. AuthProxy does the work every service would otherwise repeat: it signs the user in through the identity provider, works out which organization they’re working in, and forwards the request with the identity and the tenant attached. The AuthProxy post explains how that works and what it asks of the services behind it, and multi-tenancy and identity end to end, Part 10 of the series, follows the same request all the way down.

What matters for the architecture is what happens next. Studio maps the tenant to a Chronicle namespace, so an organization, a tenant and a namespace are the same thing. Each Chronicle namespace has its own events, observers and read models, so Studio keeps each organization’s events in its own namespace.

Authorization stays in the application. AuthProxy establishes who you are and which organization you’re in. Core decides what you’re allowed to do, with Arc command and query filters, because the edge doesn’t know the rules of the domain and shouldn’t.

Four event stores, and facts between them

Each service owns its store. Facts cross the boundary as events.

Studio doesn’t have one big event store with every service poking at it. Core, the lobby, the admin console and the catalog each have their own, and they talk the way a reactor reacts inside one store: something happened, and somebody else cares. Chronicle’s outbox and inbox carry a fact from one store to another. It means each store’s history is about one thing. The cost of that split is the usual one: the owner of a fact has to decide to publish it, and the consumer has to cope with it arriving later.

The lobby, and one invitation end to end

Every hand-off in this flow is an event.

The lobby is where a person who isn’t in an organization yet ends up. Studio runs Ante for this, which was extracted from Studio’s lobby and is published as its own image: it signs invitations, hosts the acceptance screens, and coordinates through events. Walking an invitation through shows how the pieces cooperate.

An organization member invites someone. Core handles InviteUser and records UserInvitedToJoinOrganization. The email address in that event is personal data, handled the way personal data in an event log describes. A unique constraint on the email is checked when the event is appended, so a second invitation to the same address is rejected. A reactor in Core then appends a fact for the lobby’s inbox, Ante signs the invitation link and answers with another fact, and Core sends the email. The invitee opens the link, signs in through AuthProxy, and the lobby records that the invitation was accepted. A reactor in Core listens for that and provisions the user inside the organization’s namespace, with a role.

Between Core and the lobby, every hand-off in that story is an event, and every step is something you could replay or look at in the log.

Built on the platform it’s for

The published packages Studio is built with.

Studio is built with Chronicle, Arc, Components, Fundamentals, AuthProxy and Ante, and its Play and code generation features use Stage, Screenplay and Scene.

Here’s what a small slice looks like. This is registering a project, trimmed down: a command that returns a fact, a constraint that keeps names unique, and a read model that fills itself from the events and exposes a live query.

using Cratis.Arc.Commands.ModelBound;
using Cratis.Arc.Queries.ModelBound;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.Events.Constraints;
using Cratis.Chronicle.Projections.ModelBound;
using Cratis.Chronicle.Keys;
using Cratis.Concepts;
using MongoDB.Driver;
using System.Reactive.Subjects;

public record ProjectId(Guid Value) : EventSourceId<Guid>(Value)
{
    public static ProjectId New() => new(Guid.NewGuid());
    public static implicit operator ProjectId(Guid value) => new(value);
}

public record ProjectName(string Value) : ConceptAs<string>(Value)
{
    public static implicit operator ProjectName(string value) => new(value);
}

public record ProjectDescription(string Value) : ConceptAs<string>(Value)
{
    public static implicit operator ProjectDescription(string value) => new(value);
}

[EventType]
public record ProjectRegistered(ProjectName Name, ProjectDescription Description);

[EventType]
public record ProjectRemoved();

[Command]
public record RegisterProject(ProjectName Name, ProjectDescription Description)
{
    public (ProjectId, IEnumerable<EventForEventSourceId>) Handle()
    {
        var projectId = ProjectId.New();
        return (projectId, [new(projectId, new ProjectRegistered(Name, Description))]);
    }
}

public class UniqueProjectNameConstraint : IConstraint
{
    public void Define(IConstraintBuilder builder) => builder
        .Unique(unique => unique
            .WithName("UniqueProjectName")
            .On<ProjectRegistered>(@event => @event.Name)
            .RemovedWith<ProjectRemoved>()
            .WithMessage("A project with this name already exists."));
}

[ReadModel]
[FromEvent<ProjectRegistered>]
[RemovedWith<ProjectRemoved>]
public record Project(ProjectId Id, ProjectName Name, ProjectDescription Description)
{
    public static ISubject<IEnumerable<Project>> AllProjects(IMongoCollection<Project> collection) =>
        collection.Observe();

    public static ISubject<Project> ProjectById([Key] ProjectId id, IMongoCollection<Project> collection) =>
        collection.ObserveById(id);
}

The slice targets .NET 10 and the Cratis metapackage 22.101.0. That’s the whole slice. The command says what happened and nothing else. The name rule is checked by the kernel when the event is appended, not in the command. The read model is built from the events and pushed to the browser as an observable query, which is how the project tree stays current while someone else is editing. Arc generates a TypeScript proxy for the command and the query, and the React side uses it. The post on read models and live UIs with Arc go through each piece.

A few other places the platform shows up:

Concepts, not primitives. ProjectName isn’t a string. Fundamentals’ ConceptAs<T> keeps a project name from being a description by accident, in the command, the event and the read model.
Reactors for everything that follows. Provisioning a user after an acceptance and emailing a link are each a reactor reacting to a fact, the way Part 4 describes.
Reducers where the fold is easier as code. A few read models build their state from events in a method instead of a declaration, for the cases where a reducer reads better than a projection.
Orleans. The services that need it co-host an Orleans silo, using the shared Cratis Orleans packages.

What the architecture carries

Three features sit on top of all this.

In Cratis Studio a team brainstorms events on a shared board, models commands, events and read models on one canvas, and sees everyone’s cursor as they work. The model itself arrives the way every read model in Studio does, as an observable query.

Cratis Studio has an MCP server that lets external AI agents read and change an organization’s event models and brainstorming boards. Studio’s own agents go through the same surface, so there’s one way in to the model, whether the caller is a person’s assistant or Studio’s.

A Cratis Studio event model can be exported as Screenplay text, Mermaid or JSON and imported back from Screenplay with a preview. Slices can carry Given/When/Then specifications, and Play runs the model in a disposable Stage session.

Where it runs

From merged pull request to running service.

Studio runs on a managed Kubernetes cluster, built from container images, one per service. The infrastructure is code, written with Pulumi in C#.

The Chronicle kernel is the public cratis/chronicle image running as a deployment, with MongoDB behind it for storage. The running Chronicle in production post covers that setup, and personal data in an event log covers how personal data is encrypted and erased. Telemetry flows out through OpenTelemetry.

What I’d take from it

You don’t need Studio’s size to use any of this. The parts that travel are small:

Make the organization a namespace. If your tenant is a Chronicle namespace, each tenant’s events, observers and read models live in their own namespace.
Give each service its own event store. The history of the lobby should be about invitations, and the history of Core about the product. Let facts cross the line, and decide who owns each one.
Put the repeated work at the edge, keep the decisions in the service. AuthProxy signs people in and finds their organization. The application decides what they can do.
Let slices be small. A command, an event, a constraint and a read model fit in one file, and most of Studio is that.

If you want to see the result, Cratis Studio is the place to start. The parts you can use yourself are documented at cratis.io: Chronicle, Arc and AuthProxy. Come and say hello on Discord if something here made you want to know more.

Stop filtering on status

Tue, 13 Oct 2026 09:30:00 GMT

Almost every read model starts out innocent. A work item has a title, so you add a Title. Then it needs to know whether it’s still a backlog entry or has become a pull request, so you add a Status. Then pull requests have a URL, and builds have a result, and suddenly you have a record where half the properties are nullable and every query begins with “first, filter on status, then you can trust the rest”.

Let’s face it, that’s the shape of the data fighting the shape of the model. A backlog entry and a pull request are different things an entity is at different times, and often they have different properties. Sometimes they hardly differ at all, and the Status filter is still the cost you pay on every query. I wrote about the declarative side of projections in Keep the projection out of the model. This post is about a feature that works in both styles, and that I like a lot: variants.

TL;DR

A variant group is a set of read models for the same logical entity, where the entity is in exactly one of them at a time.
Each variant has the properties its stage needs. No Status, no nullable leftovers. Stages can differ a lot or hardly at all.
When an entity enters one variant, Chronicle removes it from the others. You don’t write the removal.
Only the variant’s entering event can create it. Any other event it listens to can only update an instance that already exists, so a late or replayed event can’t resurrect something that has moved on.
It works with model-bound attributes and with the fluent builder. The fluent one has no equivalent of [GlobalFor<T>].
Each variant is its own collection or table, and nothing queries across the group for you.

One entity, several shapes

The documentation uses a work item that is a backlog entry until a pull request exists for it, and then a pull request. Modeled as one read model, you get the Status problem from the intro. With variants, you declare one read model per stage instead.

Two things make that work. First, every variant points at the same identity type, which is what ties them into a group. Second, each variant names the event that enters it. Here it is with model-bound attributes. As in the last post, the tabs are synced, so pick your language once.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;

[EventType]
public record IssueCreated(string Title);

[EventType]
public record PullRequestCreated(string PullRequestUrl);

/// <summary>
/// Anchors the logical identity shared by every variant. It does not need to be a
/// read model itself, and it does not need a common CLR base type with any of the variants.
/// </summary>
public class WorkItem;

[VariantOf<WorkItem>]
[EntersOn<IssueCreated>]
public record BacklogItem([property: Key] Guid Id, string Title);

[VariantOf<WorkItem>]
[EntersOn<PullRequestCreated>]
public record PullRequestItem([property: Key] Guid Id, [property: SetFrom<PullRequestCreated>] string PullRequestUrl);

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.EntersOn
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.FromEventSourceId
import io.cratis.chronicle.projections.SetFrom
import io.cratis.chronicle.projections.VariantOf
import io.cratis.chronicle.readModels.ReadModel

@EventType
data class IssueCreated(val title: String)

@EventType
data class PullRequestCreated(val pullRequestUrl: String)

/**
 * Anchors the logical identity shared by every variant. It does not need to be a read model
 * itself, and it does not need a common supertype with any of the variants.
 */
class WorkItem

@ReadModel
@VariantOf(WorkItem::class, key = "id")
@EntersOn(IssueCreated::class)
@FromEvent(IssueCreated::class)
data class BacklogItem(
    @FromEventSourceId
    val id: String = "",

    @SetFrom("title", IssueCreated::class)
    val title: String = ""
)

@ReadModel
@VariantOf(WorkItem::class, key = "id")
@EntersOn(PullRequestCreated::class)
@FromEvent(PullRequestCreated::class)
data class PullRequestItem(
    @FromEventSourceId
    val id: String = "",

    @SetFrom("pullRequestUrl", PullRequestCreated::class)
    val pullRequestUrl: String = ""
)

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.projections.EntersOn;
import io.cratis.chronicle.projections.FromEvent;
import io.cratis.chronicle.projections.FromEventSourceId;
import io.cratis.chronicle.projections.SetFrom;
import io.cratis.chronicle.projections.VariantOf;
import io.cratis.chronicle.readModels.ReadModel;

@EventType
record IssueCreated(String title) {}

@EventType
record PullRequestCreated(String pullRequestUrl) {}

/**
 * Anchors the logical identity shared by every variant. It does not need to be a read model
 * itself, and it does not need a common supertype with any of the variants.
 */
class WorkItem {}

@ReadModel
@VariantOf(identity = WorkItem.class, key = "id")
@EntersOn(eventType = IssueCreated.class)
@FromEvent(eventType = IssueCreated.class)
class BacklogItem {
    @FromEventSourceId
    public String id = "";

    @SetFrom(propertyPath = "title", eventType = IssueCreated.class)
    public String title = "";
}

@ReadModel
@VariantOf(identity = WorkItem.class, key = "id")
@EntersOn(eventType = PullRequestCreated.class)
@FromEvent(eventType = PullRequestCreated.class)
class PullRequestItem {
    @FromEventSourceId
    public String id = "";

    @SetFrom(propertyPath = "pullRequestUrl", eventType = PullRequestCreated.class)
    public String pullRequestUrl = "";
}

defmodule MyApp.Events.IssueCreated do
  use Chronicle.Events.EventType, id: "issue-created-v1"

  defstruct [:title]
end

defmodule MyApp.Events.PullRequestCreated do
  use Chronicle.Events.EventType, id: "pull-request-created-v1"

  defstruct [:pull_request_url]
end

# Anchors the logical identity shared by every variant. It does not need to be a read model
# itself, and it does not need a common shape with any of the variants.
defmodule MyApp.ReadModels.WorkItem do
end

defmodule MyApp.ReadModels.BacklogItem do
  use Chronicle.ReadModels.ReadModel

  alias MyApp.Events.IssueCreated
  alias MyApp.ReadModels.WorkItem

  defstruct [:id, :title]

  variant_of WorkItem, key: :id
  enters_on IssueCreated

  from IssueCreated,
    set: [id: :event_source_id, title: :title]
end

defmodule MyApp.ReadModels.PullRequestItem do
  use Chronicle.ReadModels.ReadModel

  alias MyApp.Events.PullRequestCreated
  alias MyApp.ReadModels.WorkItem

  defstruct [:id, :pull_request_url]

  variant_of WorkItem, key: :id
  enters_on PullRequestCreated

  from PullRequestCreated,
    set: [id: :event_source_id, pull_request_url: :pull_request_url]
end

import { entersOn, eventType, fromEvent, setFrom, variantOf } from '@cratis/chronicle';

@eventType()
export class IssueCreated {
    title = '';
}

@eventType()
export class PullRequestCreated {
    pullRequestUrl = '';
}

/**
 * Anchors the logical identity shared by every variant. It does not need to be a read model
 * itself, and it does not need a common shape with any of the variants.
 */
export class WorkItem {}

@variantOf(WorkItem, 'id')
@entersOn(IssueCreated)
@fromEvent(IssueCreated)
export class BacklogItem {
    id = '';

    @setFrom(IssueCreated, 'title')
    title = '';
}

@variantOf(WorkItem, 'id')
@entersOn(PullRequestCreated)
@fromEvent(PullRequestCreated)
export class PullRequestItem {
    id = '';

    @setFrom(PullRequestCreated, 'pullRequestUrl')
    pullRequestUrl = '';
}

WorkItem is only an anchor. It doesn’t have to be a read model, and it doesn’t need a common base type with the variants. Its job is to be the shared type that every variant in the group points at, which is why the docs suggest choosing one that means something on its own, rather than a marker with no purpose beyond grouping.

Now follow an entity through it. When IssueCreated is processed, a BacklogItem is created, and Title maps by convention just like in any other projection. When PullRequestCreated is processed for the same entity, a PullRequestItem is created and the BacklogItem for that entity is removed. There’s no RemovedWith anywhere. The group takes care of it. Variants aren’t required to be entered in any particular order, only to be mutually exclusive once entered, so a PullRequestCreated for an entity that was never a backlog item still creates a PullRequestItem.

A third variant for a later stage, say a closed work item, would be declared the same way, with its own entering event.

Here is what that says in specifications. First, an issue makes a backlog item:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Testing.ReadModels;
using Cratis.Specifications;
using Xunit;

public class when_an_issue_is_created : Specification
{
    readonly EventSourceId _workItemId = EventSourceId.New();
    readonly ReadModelScenario<BacklogItem> _backlog = new();

    Task Because() => _backlog.Given.ForEventSource(_workItemId).Events(new IssueCreated("Fix the login redirect"));

    [Fact] void should_be_in_the_backlog() => _backlog.Instance!.Title.ShouldEqual("Fix the login redirect");
}

Then a pull request for the same work item, with one ReadModelScenario per variant fed the same history:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Testing.ReadModels;
using Cratis.Specifications;
using Xunit;

public class when_a_pull_request_is_created_for_a_backlog_item : Specification
{
    readonly EventSourceId _workItemId = EventSourceId.New();
    readonly ReadModelScenario<BacklogItem> _backlog = new();
    readonly ReadModelScenario<PullRequestItem> _pullRequest = new();

    async Task Because()
    {
        object[] history = [new IssueCreated("Fix the login redirect"), new PullRequestCreated("https://example.com/pull/42")];

        await _backlog.Given.ForEventSource(_workItemId).Events(history);
        await _pullRequest.Given.ForEventSource(_workItemId).Events(history);
    }

    [Fact] void should_no_longer_be_in_the_backlog() => (_backlog.Instance is null).ShouldBeTrue();
    [Fact] void should_be_a_pull_request() => _pullRequest.Instance!.PullRequestUrl.ShouldEqual("https://example.com/pull/42");
}

There’s a nice property hiding in how this is built. Each variant compiles to an ordinary, independent projection definition, and the release that introduced variants made no kernel, wire or storage changes. So there’s nothing new to operate. A variant is a projection like any other, and the engine does the exclusion.

Only the entering event can create a variant

Variants rarely listen to one event. A pull request also wants to know how its build went. You declare that exactly as you would on any projection, with SetFrom in the model-bound case. The one difference is what that mapping is allowed to do: it can update a variant that already exists, but it can never create one.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;

[EventType]
public record PullRequestCreated(string PullRequestUrl);

[EventType]
public record BuildCompleted(string BuildStatus);

public class WorkItem;

/// <summary>
/// BuildStatus is mapped from BuildCompleted - an event that is NOT this
/// variant's entering event, so it is automatically reclassified into an update-only join. It can bring
/// an already-active instance up to date, but it can never create one on its own.
/// </summary>
[VariantOf<WorkItem>]
[EntersOn<PullRequestCreated>]
public record PullRequestItem(
    [property: Key] Guid Id,
    [property: SetFrom<PullRequestCreated>] string PullRequestUrl,
    [property: SetFrom<BuildCompleted>] string BuildStatus);

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.EntersOn
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.FromEventSourceId
import io.cratis.chronicle.projections.SetFrom
import io.cratis.chronicle.projections.VariantOf
import io.cratis.chronicle.readModels.ReadModel

@EventType
data class PullRequestCreated(val pullRequestUrl: String)

@EventType
data class BuildCompleted(val buildStatus: String)

class WorkItem

/**
 * buildStatus is mapped from BuildCompleted - an event that is NOT this variant's
 * entering event, so it is automatically reclassified into an update-only join. It can bring an
 * already-active instance up to date, but it can never create one on its own.
 */
@ReadModel
@VariantOf(WorkItem::class, key = "id")
@EntersOn(PullRequestCreated::class)
@FromEvent(PullRequestCreated::class)
@FromEvent(BuildCompleted::class)
data class PullRequestItem(
    @FromEventSourceId
    val id: String = "",

    @SetFrom("pullRequestUrl", PullRequestCreated::class)
    val pullRequestUrl: String = "",

    @SetFrom("buildStatus", BuildCompleted::class)
    val buildStatus: String = ""
)

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.projections.EntersOn;
import io.cratis.chronicle.projections.FromEvent;
import io.cratis.chronicle.projections.FromEventSourceId;
import io.cratis.chronicle.projections.SetFrom;
import io.cratis.chronicle.projections.VariantOf;
import io.cratis.chronicle.readModels.ReadModel;

@EventType
record PullRequestCreated(String pullRequestUrl) {}

@EventType
record BuildCompleted(String buildStatus) {}

class WorkItem {}

/**
 * buildStatus is mapped from BuildCompleted - an event that is NOT this variant's
 * entering event, so it is automatically reclassified into an update-only join. It can bring an
 * already-active instance up to date, but it can never create one on its own.
 */
@ReadModel
@VariantOf(identity = WorkItem.class, key = "id")
@EntersOn(eventType = PullRequestCreated.class)
@FromEvent(eventType = PullRequestCreated.class)
@FromEvent(eventType = BuildCompleted.class)
class PullRequestItem {
    @FromEventSourceId
    public String id = "";

    @SetFrom(propertyPath = "pullRequestUrl", eventType = PullRequestCreated.class)
    public String pullRequestUrl = "";

    @SetFrom(propertyPath = "buildStatus", eventType = BuildCompleted.class)
    public String buildStatus = "";
}

defmodule MyApp.Events.PullRequestCreated do
  use Chronicle.Events.EventType, id: "pull-request-created-v1"

  defstruct [:pull_request_url]
end

defmodule MyApp.Events.BuildCompleted do
  use Chronicle.Events.EventType, id: "build-completed-v1"

  defstruct [:build_status]
end

defmodule MyApp.ReadModels.WorkItem do
end

# build_status is mapped from BuildCompleted - an event that is NOT this
# variant's entering event, so it is automatically reclassified into an update-only join. It can
# bring an already-active instance up to date, but it can never create one on its own.
defmodule MyApp.ReadModels.PullRequestItem do
  use Chronicle.ReadModels.ReadModel

  alias MyApp.Events.{PullRequestCreated, BuildCompleted}
  alias MyApp.ReadModels.WorkItem

  defstruct [:id, :pull_request_url, :build_status]

  variant_of WorkItem, key: :id
  enters_on PullRequestCreated

  from PullRequestCreated,
    set: [id: :event_source_id, pull_request_url: :pull_request_url]

  from BuildCompleted,
    set: [build_status: :build_status]
end

import { entersOn, eventType, fromEvent, setFrom, variantOf } from '@cratis/chronicle';

@eventType()
export class PullRequestCreated {
    pullRequestUrl = '';
}

@eventType()
export class BuildCompleted {
    buildStatus = '';
}

export class WorkItem {}

/**
 * buildStatus is mapped from BuildCompleted - an event that is NOT this variant's
 * entering event, so it is automatically reclassified into an update-only join. It can bring an
 * already-active instance up to date, but it can never create one on its own.
 */
@variantOf(WorkItem, 'id')
@entersOn(PullRequestCreated)
@fromEvent(PullRequestCreated)
@fromEvent(BuildCompleted)
export class PullRequestItem {
    id = '';

    @setFrom(PullRequestCreated, 'pullRequestUrl')
    pullRequestUrl = '';

    @setFrom(BuildCompleted, 'buildStatus')
    buildStatus = '';
}

BuildStatus is mapped from BuildCompleted, which isn’t the event named in EntersOn. Chronicle reclassifies that mapping into an update-only join on the variant’s own key before it ever reaches the projection engine. The entering event stays the only door in.

The docs explain why this matters, and it’s the part of the feature I find most convincing. Without that reclassification, a BuildCompleted that arrives out of order, or is replayed, could resurrect a PullRequestItem for an entity that has since moved on to another variant, or one that was never a pull request at all. That’s exactly the bug a status column invites, and here it’s structurally impossible. You don’t have to reason about event ordering to get the guarantee. Declaring the entering event gives it to you.

You can see that in specifications too. A build for something that never became a pull request creates nothing:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Testing.ReadModels;
using Cratis.Specifications;
using Xunit;

public class when_a_build_completes_for_something_that_is_not_a_pull_request : Specification
{
    readonly EventSourceId _workItemId = EventSourceId.New();
    readonly ReadModelScenario<PullRequestItem> _pullRequest = new();

    Task Because() => _pullRequest.Given.ForEventSource(_workItemId).Events(new BuildCompleted("passed"));

    [Fact] void should_not_create_a_pull_request() => (_pullRequest.Instance is null).ShouldBeTrue();
}

And when the pull request exists, the build status lands on it:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Testing.ReadModels;
using Cratis.Specifications;
using Xunit;

public class when_a_build_completes_after_the_pull_request_was_created : Specification
{
    readonly EventSourceId _workItemId = EventSourceId.New();
    readonly ReadModelScenario<PullRequestItem> _pullRequest = new();

    Task Because() => _pullRequest.Given.ForEventSource(_workItemId).Events(
        new PullRequestCreated("https://example.com/pull/42"),
        new BuildCompleted("passed"));

    [Fact] void should_report_the_build_status() => _pullRequest.Instance!.BuildStatus.ShouldEqual("passed");
}

So what about a build that finishes before the pull request exists? The first spec says it creates nothing, and that holds. What happens once the pull request does arrive is more interesting. BuildStatus is mapped through a join, and joins are re-resolved against the last stored event of the joined stream whenever the projection handles one of the read model’s own events. So the earlier BuildCompleted is picked up the moment PullRequestCreated creates the variant:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Testing.ReadModels;
using Cratis.Specifications;
using Xunit;

public class when_a_build_completes_before_the_pull_request_was_created : Specification
{
    readonly EventSourceId _workItemId = EventSourceId.New();
    readonly ReadModelScenario<PullRequestItem> _pullRequest = new();

    Task Because() => _pullRequest.Given.ForEventSource(_workItemId).Events(
        new BuildCompleted("passed"),
        new PullRequestCreated("https://example.com/pull/42"));

    [Fact] void should_still_create_the_pull_request() => _pullRequest.Instance!.PullRequestUrl.ShouldEqual("https://example.com/pull/42");
    [Fact] void should_pick_up_the_build_status_reported_before_entering() => _pullRequest.Instance!.BuildStatus.ShouldEqual("passed");
}

If your build can really finish before the pull request exists, that’s still worth a thought about your events, but the projection won’t lose the result.

Some properties every stage wants. A title is the obvious one. Repeating the mapping on each variant gets old, so model-bound projections have [GlobalFor<TIdentity>]: declare the mapping once, and it’s merged into every variant in the group. Each client spells it its own way, and the model-bound variants page has all five.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;

[EventType]
public record IssueCreated(string Title);


[EventType]
public record PullRequestCreated(string PullRequestUrl);


[EventType]
public record TitleChanged(string Title);


public class WorkItem;


[VariantOf<WorkItem>]
[EntersOn<IssueCreated>]
public record BacklogItem([property: Key] Guid Id, string Title);


[VariantOf<WorkItem>]
[EntersOn<PullRequestCreated>]
public record PullRequestItem(
    [property: Key] Guid Id,
    string Title,
    [property: SetFrom<PullRequestCreated>] string PullRequestUrl);


/// <summary>
/// Declares a mapping every variant of WorkItem shares. Every variant must have a
/// Title member - one that does not is a declaration error, not a silently skipped mapping.
/// </summary>
/// <param name="Title">The title every variant carrying one keeps up to date.</param>
[GlobalFor<WorkItem>]
public record SharedHandlers([property: SetFrom<TitleChanged>] string Title);

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.EntersOn
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.FromEventSourceId
import io.cratis.chronicle.projections.GlobalFor
import io.cratis.chronicle.projections.SetFrom
import io.cratis.chronicle.projections.VariantOf
import io.cratis.chronicle.readModels.ReadModel


@EventType
data class IssueCreated(val title: String)


@EventType
data class PullRequestCreated(val pullRequestUrl: String)


@EventType
data class TitleChanged(val title: String)


class WorkItem


@ReadModel
@VariantOf(WorkItem::class, key = "id")
@EntersOn(IssueCreated::class)
@FromEvent(IssueCreated::class)
data class BacklogItem(
    @FromEventSourceId
    val id: String = "",
    val title: String = ""
)


@ReadModel
@VariantOf(WorkItem::class, key = "id")
@EntersOn(PullRequestCreated::class)
@FromEvent(PullRequestCreated::class)
data class PullRequestItem(
    @FromEventSourceId
    val id: String = "",
    val title: String = "",


    @SetFrom("pullRequestUrl", PullRequestCreated::class)
    val pullRequestUrl: String = ""
)


/**
 * Declares a mapping every variant of WorkItem shares. Every variant must have a
 * title member - one that does not is a declaration error, not a silently skipped mapping.
 */
@GlobalFor(WorkItem::class)
@FromEvent(TitleChanged::class)
data class SharedHandlers(
    @SetFrom("title", TitleChanged::class)
    val title: String = ""
)

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.projections.EntersOn;
import io.cratis.chronicle.projections.FromEvent;
import io.cratis.chronicle.projections.FromEventSourceId;
import io.cratis.chronicle.projections.GlobalFor;
import io.cratis.chronicle.projections.SetFrom;
import io.cratis.chronicle.projections.VariantOf;
import io.cratis.chronicle.readModels.ReadModel;


@EventType
record IssueCreated(String title) {}


@EventType
record PullRequestCreated(String pullRequestUrl) {}


@EventType
record TitleChanged(String title) {}


class WorkItem {}


@ReadModel
@VariantOf(identity = WorkItem.class, key = "id")
@EntersOn(eventType = IssueCreated.class)
@FromEvent(eventType = IssueCreated.class)
class BacklogItem {
    @FromEventSourceId
    public String id = "";
    public String title = "";
}


@ReadModel
@VariantOf(identity = WorkItem.class, key = "id")
@EntersOn(eventType = PullRequestCreated.class)
@FromEvent(eventType = PullRequestCreated.class)
class PullRequestItem {
    @FromEventSourceId
    public String id = "";
    public String title = "";


    @SetFrom(propertyPath = "pullRequestUrl", eventType = PullRequestCreated.class)
    public String pullRequestUrl = "";
}


/**
 * Declares a mapping every variant of WorkItem shares. Every variant must have a
 * title member - one that does not is a declaration error, not a silently skipped mapping.
 */
@GlobalFor(identity = WorkItem.class)
@FromEvent(eventType = TitleChanged.class)
class SharedHandlers {
    @SetFrom(propertyPath = "title", eventType = TitleChanged.class)
    public String title = "";
}

defmodule MyApp.Events.IssueCreated do
  use Chronicle.Events.EventType, id: "issue-created-v1"


  defstruct [:title]
end


defmodule MyApp.Events.PullRequestCreated do
  use Chronicle.Events.EventType, id: "pull-request-created-v1"


  defstruct [:pull_request_url]
end


defmodule MyApp.Events.TitleChanged do
  use Chronicle.Events.EventType, id: "title-changed-v1"


  defstruct [:title]
end


defmodule MyApp.ReadModels.WorkItem do
end


defmodule MyApp.ReadModels.BacklogItem do
  use Chronicle.ReadModels.ReadModel


  alias MyApp.Events.IssueCreated
  alias MyApp.ReadModels.WorkItem


  defstruct [:id, :title]


  variant_of WorkItem, key: :id
  enters_on IssueCreated


  from IssueCreated,
    set: [id: :event_source_id]
end


defmodule MyApp.ReadModels.PullRequestItem do
  use Chronicle.ReadModels.ReadModel


  alias MyApp.Events.PullRequestCreated
  alias MyApp.ReadModels.WorkItem


  defstruct [:id, :title, :pull_request_url]


  variant_of WorkItem, key: :id
  enters_on PullRequestCreated


  from PullRequestCreated,
    set: [id: :event_source_id, pull_request_url: :pull_request_url]
end


# Declares a mapping every variant of WorkItem shares. Every variant must have a
# title member - one that does not is a declaration error, not a silently skipped mapping. Never
# registered as a projection on its own.
defmodule MyApp.Projections.SharedHandlers do
  use Chronicle.Projections.GlobalHandler, identity: MyApp.ReadModels.WorkItem


  alias MyApp.Events.TitleChanged


  from TitleChanged,
    set: [title: :title]
end

import { entersOn, eventType, fromEvent, globalFor, setFrom, variantOf } from '@cratis/chronicle';


@eventType()
export class IssueCreated {
    title = '';
}


@eventType()
export class PullRequestCreated {
    pullRequestUrl = '';
}


@eventType()
export class TitleChanged {
    title = '';
}


export class WorkItem {}


@variantOf(WorkItem, 'id')
@entersOn(IssueCreated)
@fromEvent(IssueCreated)
export class BacklogItem {
    id = '';
    title = '';
}


@variantOf(WorkItem, 'id')
@entersOn(PullRequestCreated)
@fromEvent(PullRequestCreated)
export class PullRequestItem {
    id = '';
    title = '';


    @setFrom(PullRequestCreated, 'pullRequestUrl')
    pullRequestUrl = '';
}


/**
 * Declares a mapping every variant of WorkItem shares. Every variant must have a
 * title member - one that does not is a declaration error, not a silently skipped mapping. Never
 * registered as a projection on its own.
 */
@globalFor(WorkItem)
export class SharedHandlers {
    @setFrom(TitleChanged, 'title')
    title = '';
}

This block is its own small example, with a fresh set of events. SharedHandlers is not a read model and no variant inherits from it. It only carries the mapping, and TitleChanged now updates the title on whichever variant the work item is in:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Testing.ReadModels;
using Cratis.Specifications;
using Xunit;

public class when_the_title_changes_after_the_pull_request_was_created : Specification
{
    readonly EventSourceId _workItemId = EventSourceId.New();
    readonly ReadModelScenario<PullRequestItem> _pullRequest = new();

    Task Because() => _pullRequest.Given.ForEventSource(_workItemId).Events(
        new IssueCreated("Fix login"),
        new PullRequestCreated("https://example.com/pull/42"),
        new TitleChanged("Fix the login redirect"));

    [Fact] void should_have_the_new_title() => _pullRequest.Instance!.Title.ShouldEqual("Fix the login redirect");
}

Like any other non-entering mapping, a shared one can only update an active variant, so it’s safe to share across stages that begin at different times. And every variant must have the member a shared mapping targets. A variant without it is a declaration error, caught when the projection is discovered, not an unpredictable surprise when a shared event finally shows up.

The same thing, fluent

Everything above is also available in the declarative style, and this is where the two styles from the last post line up one to one.

The read models are plain records, the projections say which group and which entering event, and the identity type is declared exactly as before.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections;

[EventType]
public record IssueCreated(string Title);

[EventType]
public record PullRequestCreated(string PullRequestUrl);

/// <summary>
/// Anchors the logical identity shared by BacklogItem and PullRequestItem.
/// Deliberately not a read model itself, and does not need a common CLR base type with either variant.
/// </summary>
public class WorkItem;

public record BacklogItem(Guid Id, string Title);

public record PullRequestItem(Guid Id, string PullRequestUrl);

public class BacklogItemProjection : IProjectionFor<BacklogItem>
{
    public void Define(IProjectionBuilderFor<BacklogItem> builder) => builder
        .VariantOf<WorkItem>(_ => _.Id)
        .EntersOn<IssueCreated>();
}

public class PullRequestItemProjection : IProjectionFor<PullRequestItem>
{
    public void Define(IProjectionBuilderFor<PullRequestItem> builder) => builder
        .VariantOf<WorkItem>(_ => _.Id)
        .EntersOn<PullRequestCreated>();
}

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.IProjectionBuilderFor
import io.cratis.chronicle.projections.IProjectionFor

@EventType
data class IssueCreated(val title: String)

@EventType
data class PullRequestCreated(val pullRequestUrl: String)

/**
 * Anchors the logical identity shared by BacklogItem and PullRequestItem.
 * Deliberately not a read model itself, and does not need a common supertype with either variant.
 */
class WorkItem

data class BacklogItem(val id: String = "", val title: String = "")

data class PullRequestItem(val id: String = "", val pullRequestUrl: String = "")

class BacklogItemProjection : IProjectionFor<BacklogItem> {
    override fun define(builder: IProjectionBuilderFor<BacklogItem>) {
        builder
            .variantOf(WorkItem::class, BacklogItem::id)
            .entersOn(IssueCreated::class)
    }
}

class PullRequestItemProjection : IProjectionFor<PullRequestItem> {
    override fun define(builder: IProjectionBuilderFor<PullRequestItem>) {
        builder
            .variantOf(WorkItem::class, PullRequestItem::id)
            .entersOn(PullRequestCreated::class)
    }
}

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.projections.IProjectionBuilderFor;
import io.cratis.chronicle.projections.IProjectionFor;

@EventType
record IssueCreated(String title) {}

@EventType
record PullRequestCreated(String pullRequestUrl) {}

/**
 * Anchors the logical identity shared by BacklogItem and PullRequestItem.
 * Deliberately not a read model itself, and does not need a common supertype with either variant.
 */
class WorkItem {}

class BacklogItem {
    public String id = "";
    public String title = "";
}

class PullRequestItem {
    public String id = "";
    public String pullRequestUrl = "";
}

class BacklogItemProjection implements IProjectionFor<BacklogItem> {
    @Override
    public void define(IProjectionBuilderFor<BacklogItem> builder) {
        builder
            .variantOf(WorkItem.class, "id")
            .entersOn(IssueCreated.class);
    }
}

class PullRequestItemProjection implements IProjectionFor<PullRequestItem> {
    @Override
    public void define(IProjectionBuilderFor<PullRequestItem> builder) {
        builder
            .variantOf(WorkItem.class, "id")
            .entersOn(PullRequestCreated.class);
    }
}

defmodule MyApp.Events.IssueCreated do
  use Chronicle.Events.EventType, id: "dec-variant-issue-created-v1"

  defstruct [:title]
end

defmodule MyApp.Events.PullRequestCreated do
  use Chronicle.Events.EventType, id: "dec-variant-pull-request-created-v1"

  defstruct [:pull_request_url]
end

# Anchors the logical identity shared by BacklogItem and PullRequestItem.
# Deliberately not a read model itself, and does not need a common shape with either variant.
defmodule MyApp.ReadModels.WorkItem do
end

defmodule MyApp.ReadModels.BacklogItem do
  use Chronicle.ReadModels.ReadModel

  defstruct [:id, :title]
end

defmodule MyApp.ReadModels.PullRequestItem do
  use Chronicle.ReadModels.ReadModel

  defstruct [:id, :pull_request_url]
end

defmodule MyApp.Projections.BacklogItemProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.BacklogItem

  alias MyApp.Events.IssueCreated
  alias MyApp.ReadModels.WorkItem

  variant_of WorkItem, key: :id
  enters_on IssueCreated

  from IssueCreated,
    set: [id: :event_source_id, title: :title]
end

defmodule MyApp.Projections.PullRequestItemProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.PullRequestItem

  alias MyApp.Events.PullRequestCreated
  alias MyApp.ReadModels.WorkItem

  variant_of WorkItem, key: :id
  enters_on PullRequestCreated

  from PullRequestCreated,
    set: [id: :event_source_id, pull_request_url: :pull_request_url]
end

import { eventType } from '@cratis/chronicle';
import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
class IssueCreated {
    title = '';
}

@eventType()
class PullRequestCreated {
    pullRequestUrl = '';
}

/**
 * Anchors the logical identity shared by BacklogItem and PullRequestItem.
 * Deliberately not a read model itself, and does not need a common shape with either variant.
 */
class WorkItem {}

class BacklogItem {
    id = '';
    title = '';
}

class PullRequestItem {
    id = '';
    pullRequestUrl = '';
}

@projection()
class BacklogItemProjection implements IProjectionFor<BacklogItem> {
    define(builder: IProjectionBuilderFor<BacklogItem>): void {
        builder
            .variantOf(WorkItem, m => m.id)
            .entersOn(IssueCreated);
    }
}

@projection()
class PullRequestItemProjection implements IProjectionFor<PullRequestItem> {
    define(builder: IProjectionBuilderFor<PullRequestItem>): void {
        builder
            .variantOf(WorkItem, m => m.id)
            .entersOn(PullRequestCreated);
    }
}

VariantOf takes the identity type and a key accessor, and EntersOn names the entering event. Auto-mapping is on as in any fluent projection, so Title and PullRequestUrl map by name without a Set. Entering PullRequestItem removes the BacklogItem, again with no removal call, because the group is cross-wired automatically once every variant in it has been discovered.

An additional event is an ordinary From, and it gets the same reclassification as SetFrom did:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Projections;

[EventType]
public record PullRequestCreated(string PullRequestUrl);

[EventType]
public record BuildCompleted(string BuildStatus);

public class WorkItem;

public record PullRequestItem(Guid Id, string PullRequestUrl, string BuildStatus);

/// <summary>
/// From&lt;BuildCompleted&gt; is declared exactly like an ordinary multi-event
/// projection. Because that event is NOT the one named with EntersOn, the builder automatically
/// reclassifies it into an update-only join on the variant's own key when the definition is built - it
/// can bring an already-active instance up to date, but it can never create one on its own.
/// </summary>
public class PullRequestItemProjection : IProjectionFor<PullRequestItem>
{
    public void Define(IProjectionBuilderFor<PullRequestItem> builder) => builder
        .VariantOf<WorkItem>(_ => _.Id)
        .EntersOn<PullRequestCreated>()
        .From<BuildCompleted>();
}

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.IProjectionBuilderFor
import io.cratis.chronicle.projections.IProjectionFor

@EventType
data class PullRequestCreated(val pullRequestUrl: String)

@EventType
data class BuildCompleted(val buildStatus: String)

class WorkItem

data class PullRequestItem(val id: String = "", val pullRequestUrl: String = "", val buildStatus: String = "")

/**
 * from(BuildCompleted::class) is declared exactly like an ordinary multi-event
 * projection. Because that event is NOT the one named with entersOn, the builder automatically
 * reclassifies it into an update-only join on the variant's own key when the definition is built -
 * it can bring an already-active instance up to date, but it can never create one on its own.
 */
class PullRequestItemProjection : IProjectionFor<PullRequestItem> {
    override fun define(builder: IProjectionBuilderFor<PullRequestItem>) {
        builder
            .variantOf(WorkItem::class, PullRequestItem::id)
            .entersOn(PullRequestCreated::class)
            .from(BuildCompleted::class)
    }
}

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.projections.IProjectionBuilderFor;
import io.cratis.chronicle.projections.IProjectionFor;

@EventType
record PullRequestCreated(String pullRequestUrl) {}

@EventType
record BuildCompleted(String buildStatus) {}

class WorkItem {}

class PullRequestItem {
    public String id = "";
    public String pullRequestUrl = "";
    public String buildStatus = "";
}

/**
 * from(BuildCompleted.class) is declared exactly like an ordinary multi-event
 * projection. Because that event is NOT the one named with entersOn, the builder automatically
 * reclassifies it into an update-only join on the variant's own key when the definition is built -
 * it can bring an already-active instance up to date, but it can never create one on its own.
 */
class PullRequestItemProjection implements IProjectionFor<PullRequestItem> {
    @Override
    public void define(IProjectionBuilderFor<PullRequestItem> builder) {
        builder
            .variantOf(WorkItem.class, "id")
            .entersOn(PullRequestCreated.class)
            .from(BuildCompleted.class);
    }
}

defmodule MyApp.Events.PullRequestCreated do
  use Chronicle.Events.EventType, id: "dec-variant-updating-pull-request-created-v1"

  defstruct [:pull_request_url]
end

defmodule MyApp.Events.BuildCompleted do
  use Chronicle.Events.EventType, id: "dec-variant-updating-build-completed-v1"

  defstruct [:build_status]
end

defmodule MyApp.ReadModels.WorkItem do
end

defmodule MyApp.ReadModels.PullRequestItem do
  use Chronicle.ReadModels.ReadModel

  defstruct [:id, :pull_request_url, :build_status]
end

# `from BuildCompleted` is declared exactly like an ordinary multi-event
# projection. Because that event is NOT the one named with enters_on, it is automatically
# reclassified into an update-only join on the variant's own key when the definition is built -
# it can bring an already-active instance up to date, but it can never create one on its own.
defmodule MyApp.Projections.PullRequestItemProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.PullRequestItem

  alias MyApp.Events.{PullRequestCreated, BuildCompleted}
  alias MyApp.ReadModels.WorkItem

  variant_of WorkItem, key: :id
  enters_on PullRequestCreated

  from PullRequestCreated,
    set: [id: :event_source_id, pull_request_url: :pull_request_url]

  from BuildCompleted,
    set: [build_status: :build_status]
end

import { eventType, IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

@eventType()
class PullRequestCreated {
    pullRequestUrl = '';
}

@eventType()
class BuildCompleted {
    buildStatus = '';
}

class WorkItem {}

class PullRequestItem {
    id = '';
    pullRequestUrl = '';
    buildStatus = '';
}

/**
 * .from(BuildCompleted) is declared exactly like an ordinary multi-event
 * projection. Because that event is NOT the one named with entersOn, the builder automatically
 * reclassifies it into an update-only join on the variant's own key when the definition is built -
 * it can bring an already-active instance up to date, but it can never create one on its own.
 */
@projection()
class PullRequestItemProjection implements IProjectionFor<PullRequestItem> {
    define(builder: IProjectionBuilderFor<PullRequestItem>): void {
        builder
            .variantOf(WorkItem, m => m.id)
            .entersOn(PullRequestCreated)
            .from(BuildCompleted);
    }
}

From<BuildCompleted>() looks like any other subscription. Because it isn’t the entering event, the builder turns it into an update-only join keyed on the same property VariantOf named, before the definition reaches the engine. Same guarantee, spelled differently.

The one real difference is sharing. Fluent projections have no equivalent of [GlobalFor<T>]. Each projection is its own class with its own definition, so a mapping every variant needs is a .From<TEvent>() on each builder. The docs’ own advice is that if you end up repeating one often enough for it to hurt, that repetition is a reason to use model-bound variants for that group.

The first specification in this post, with the same history and the same assertions against FluentBacklogItem and FluentPullRequestItem, passes for the fluent version too. A ReadModelScenario discovers the other variants of the group, model-bound or fluent, so entering one variant removes the entity from the others there as it does on a server.

What it costs

Be honest with yourself about the trade, because there is one.

Each variant is its own collection. There’s no built-in query that spans the group. If a caller needs “this entity, whichever stage it’s in”, it asks each variant explicitly. That’s by design, and it’s also something you have to build.
The shapes don’t have to differ. Variants fit entities whose stages really are different things, but they fit just as well when the stages share nearly the same shape. In Direct, the journey information shown for an item is much the same across stages, and that is by design: each stage is its own collection, so a query reads only that stage and there’s no Status to filter on or index. Both uses are valid and they aren’t mutually exclusive.
It’s a projection feature. Variants are declared on model-bound and fluent projections. A reducer builds the state of one read model, so it’s not where this lives. If you’re deciding between a projection and a reducer, the previous post and From event to read model cover the difference.

And what do you get for it? The fastest thing that can possibly work, as I like to put it. A query for the backlog reads the backlog. There’s no Status to filter on, so there’s none to index just to keep that lookup quick, and the rows you don’t want aren’t in the way. That’s the design bet. I haven’t benchmarked it for this post, so don’t take it as a number. Take it as the reason the shape exists.

Wrapping up

The next time you reach for a Status column, ask whether each stage deserves its own read model, either because it’s a different thing or because you’d rather not filter on status for every query. If so, give it its own read model, name the event that makes an entity become it, and let Chronicle do the moving. That’s a few attributes, or a few builder calls, and a status filter you never write.

The full reference is in the docs, for both model-bound variants and fluent variants, and the guide to choosing a read-model style is a good companion if you’re still deciding between the ways to build one. How a read model gets queried afterwards, and how a live list learns about changes, is in From event to read model.

Variants need Chronicle 19.1.0 or later, and the scenario behavior described here needs 19.57.1 or later.

Keep the projection out of the model

Tue, 13 Oct 2026 09:00:00 GMT

Model-bound projections get most of the attention, and I get it. You put an attribute on a property, the read model says where its data comes from, and there’s nothing else to go looking for. That cohesion is a big part of why it’s where we tell people to start.

But it wasn’t the first thing we built. The fluent, declarative IProjectionFor<T> was. And to be honest, I think it gets undersold now. The trade-off model-bound makes is real: everything ends up in the same place. The read model, the events it listens to, the keys, the children, the removals. For a small read model that’s lovely. For a bigger one it turns into a pile of attributes that a human has to decode, and let’s face it, a projection gets read a lot more often than it gets written.

So this post is about the other option: what it is, when it earns its keep, and how it differs from the thing people most often confuse it with, the reducer.

TL;DR

Model-bound and fluent are two ways to write the same kind of projection. Chronicle stores a projection definition either way and its projection engine runs it.
Model-bound gives you cohesion. Fluent gives you separation: a plain read model and a mapping you can read on its own.
In Kotlin and Java, fluent is also the way to express a mapping the annotations can’t, such as toggling a flag per event type.
A reducer is not a third spelling of the same idea. It’s your code, running in your application, that takes an event and the current state and returns the next state.
Start with model-bound. Reach for fluent when the attributes stop being readable or you want a read model without Chronicle attributes on it. Reach for a reducer when the logic reads better as code.

Two places for the same mapping

Every projection answers the same question: given these events, what does the read model look like? The two styles only disagree on where you write the answer.

With model-bound projections the answer is attributes on the read model itself. With declarative projections the read model is an ordinary type, and a separate class implementing IProjectionFor<TReadModel> uses a builder to say how events map onto it.

What happens next is identical. From event to read model walks through how all the ways of writing a projection converge: the client turns what you wrote into a projection definition, the kernel stores it, and the projection engine applies it to events and writes the result to the sink. The engine never knows which style you picked. Which means the choice is about you, and the people who’ll read this code later.

The same book, both ways

Chronicle’s documentation has a deliberately small example in its guide to choosing a read-model style: a book is registered, borrowed and returned. These are the three events. The tabs on this page stay in sync, so pick your language once.

using Cratis.Chronicle.Events;

[EventType]
public record BookRegistered(string Title, string Isbn);

[EventType]
public record BookBorrowed(string MemberName);

[EventType]
public record BookReturned;

import io.cratis.chronicle.events.EventType

@EventType
data class BookRegistered(val title: String, val isbn: String)

@EventType
data class BookBorrowed(val memberName: String)

@EventType
class BookReturned

import io.cratis.chronicle.events.EventType;

@EventType
record BookRegistered(String title, String isbn) {}

@EventType
record BookBorrowed(String memberName) {}

@EventType
record BookReturned() {}

defmodule MyApp.Events.BookRegistered do
  use Chronicle.Events.EventType, id: "choosing-style-book-registered"

  defstruct [:title, :isbn]
end

defmodule MyApp.Events.BookBorrowed do
  use Chronicle.Events.EventType, id: "choosing-style-book-borrowed"

  defstruct [:member_name]
end

defmodule MyApp.Events.BookReturned do
  use Chronicle.Events.EventType, id: "choosing-style-book-returned"

  defstruct []
end

import { eventType } from '@cratis/chronicle';

@eventType()
class BookRegistered {
    title = '';
    isbn = '';
}

@eventType()
class BookBorrowed {
    memberName = '';
}

@eventType()
class BookReturned {
}

First the model-bound version. The mapping lives on the properties:

using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;

public record BookStatusModelBound(
    [Key] string Id,

    [SetFrom<BookRegistered>] string Title,
    [SetFrom<BookRegistered>] string Isbn,

    [SetValue<BookBorrowed>(true)]
    [SetValue<BookReturned>(false)]
    bool IsBorrowed,

    [SetFrom<BookBorrowed>(nameof(BookBorrowed.MemberName))]
    [SetValue<BookReturned>(null!)] // null! - SetValue's constructor takes non-nullable object
    string? BorrowedBy);

Kotlin does not support this workflow yet. The model-bound @SetFrom annotation maps a property from an event, but there is no equivalent to C#’s [SetValue<TEvent>(...)] for assigning a constant value — so a flag like isBorrowed cannot be toggled per event type through model-bound attributes alone. Track the client SDK issue, or use a reducer instead.

Java does not support this workflow yet. The model-bound @SetFrom annotation maps a property from an event, but there is no equivalent to C#’s [SetValue<TEvent>(...)] for assigning a constant value — so a flag like isBorrowed cannot be toggled per event type through model-bound attributes alone. Track the client SDK issue, or use a reducer instead.

defmodule MyApp.ReadModels.BookStatusModelBound do
  use Chronicle.ReadModels.ReadModel

  defstruct id: "", title: "", isbn: "", is_borrowed: false, borrowed_by: nil

  from MyApp.Events.BookRegistered,
    set: [id: :event_source_id, title: :title, isbn: :isbn, is_borrowed: false, borrowed_by: nil]

  from MyApp.Events.BookBorrowed,
    set: [is_borrowed: true, borrowed_by: :member_name]

  from MyApp.Events.BookReturned,
    set: [is_borrowed: false, borrowed_by: nil]
end

import { setFrom, setValue } from '@cratis/chronicle';
import { field } from '@cratis/fundamentals';

export class BookStatusModelBound {
    id = '';

    @setFrom(BookRegistered, 'title')
    title = '';

    @setFrom(BookRegistered, 'isbn')
    isbn = '';

    @setValue(BookBorrowed, true)
    @setValue(BookReturned, false)
    isBorrowed = false;

    @setFrom(BookBorrowed, 'memberName')
    @setValue(BookReturned, null)
    @field(String) borrowedBy: string | null = null;
}

Then the fluent version. The read model has no mapping on it at all, and a projection class says what each event does:

using Cratis.Chronicle.Projections;

public record BookStatusFluent(
    string Id,
    string Title,
    string Isbn,
    bool IsBorrowed,
    string? BorrowedBy);

public class BookStatusProjection : IProjectionFor<BookStatusFluent>
{
    public void Define(IProjectionBuilderFor<BookStatusFluent> builder) => builder
        .From<BookRegistered>(_ => _
            .Set(m => m.Id).ToEventSourceId()
            .Set(m => m.IsBorrowed).ToValue(false)
            .Clear(m => m.BorrowedBy))
        .From<BookBorrowed>(_ => _
            .Set(m => m.IsBorrowed).ToValue(true)
            .Set(m => m.BorrowedBy).To(e => e.MemberName))
        .From<BookReturned>(_ => _
            .Set(m => m.IsBorrowed).ToValue(false)
            .Clear(m => m.BorrowedBy));
}

// Requires io.cratis:chronicle 6.5.0 or later.
import io.cratis.chronicle.projections.IProjectionBuilderFor
import io.cratis.chronicle.projections.IProjectionFor

data class BookStatus(
    val id: String = "",
    val title: String = "",
    val isbn: String = "",
    val isBorrowed: Boolean = false,
    val borrowedBy: String? = null
)

class BookStatusProjection : IProjectionFor<BookStatus> {
    override fun define(builder: IProjectionBuilderFor<BookStatus>) {
        builder
            .from(BookRegistered::class) {
                it.set(BookStatus::id).toEventSourceId()
                it.set(BookStatus::title).toProperty("title")
                it.set(BookStatus::isbn).toProperty("isbn")
                it.set(BookStatus::isBorrowed).toValue(false)
                it.set(BookStatus::borrowedBy).toValue(null)
            }
            .from(BookBorrowed::class) {
                it.set(BookStatus::isBorrowed).toValue(true)
                it.set(BookStatus::borrowedBy).toProperty("memberName")
            }
            .from(BookReturned::class) {
                it.set(BookStatus::isBorrowed).toValue(false)
                it.set(BookStatus::borrowedBy).toValue(null)
            }
    }
}

// Requires io.cratis:chronicle 6.5.0 or later.
import io.cratis.chronicle.projections.IProjectionBuilderFor;
import io.cratis.chronicle.projections.IProjectionFor;

class BookStatus {
    public String id = "";
    public String title = "";
    public String isbn = "";
    public boolean isBorrowed = false;
    public String borrowedBy = null;
}

class BookStatusProjection implements IProjectionFor<BookStatus> {
    @Override
    public void define(IProjectionBuilderFor<BookStatus> builder) {
        builder
            .from(BookRegistered.class, fb -> {
                fb.<String>set("id").toEventSourceId();
                fb.<String>set("title").toProperty("title");
                fb.<String>set("isbn").toProperty("isbn");
                fb.<Boolean>set("isBorrowed").toValue(false);
                fb.<String>set("borrowedBy").toValue(null);
            })
            .from(BookBorrowed.class, fb -> {
                fb.<Boolean>set("isBorrowed").toValue(true);
                fb.<String>set("borrowedBy").toProperty("memberName");
            })
            .from(BookReturned.class, fb -> {
                fb.<Boolean>set("isBorrowed").toValue(false);
                fb.<String>set("borrowedBy").toValue(null);
            });
    }
}

defmodule MyApp.ReadModels.BookStatusFluent do
  use Chronicle.ReadModels.ReadModel

  defstruct id: "", title: "", isbn: "", is_borrowed: false, borrowed_by: nil
end

defmodule MyApp.Projections.BookStatusProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.BookStatusFluent

  from MyApp.Events.BookRegistered,
    set: [id: :event_source_id, title: :title, isbn: :isbn, is_borrowed: false, borrowed_by: nil]

  from MyApp.Events.BookBorrowed,
    set: [is_borrowed: true, borrowed_by: :member_name]

  from MyApp.Events.BookReturned,
    set: [is_borrowed: false, borrowed_by: nil]
end

import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

class BookStatusFluent {
    id = '';
    title = '';
    isbn = '';
    isBorrowed = false;
    borrowedBy: string | null = null;
}

@projection()
class BookStatusProjection implements IProjectionFor<BookStatusFluent> {
    define(builder: IProjectionBuilderFor<BookStatusFluent>): void {
        builder
            .from(BookRegistered, _ => _
                .set(m => m.id).toEventSourceId()
                .set(m => m.title).to(e => e.title)
                .set(m => m.isbn).to(e => e.isbn)
                .set(m => m.isBorrowed).toValue(false)
                .set(m => m.borrowedBy).toValue(null))
            .from(BookBorrowed, _ => _
                .set(m => m.isBorrowed).toValue(true)
                .set(m => m.borrowedBy).to(e => e.memberName))
            .from(BookReturned, _ => _
                .set(m => m.isBorrowed).toValue(false)
                .set(m => m.borrowedBy).toValue(null));
    }
}

Same events, same documents come out. Read the two next to each other and notice where your eyes go. In the model-bound version you read the model and learn the mapping as a side effect. In the fluent version you read one event at a time: when a book is borrowed, set IsBorrowed to true and BorrowedBy to the member. It’s a bit more code, and for this tiny model I’d happily take the attributes.

Now look at the Kotlin and Java tabs of the model-bound example. That’s not me skipping something. Chronicle’s docs say the model-bound @SetFrom annotation has no equivalent to C#’s [SetValue<TEvent>(...)], so a flag like isBorrowed can’t be toggled per event type through annotations alone. The note in the docs suggests tracking the client SDK issue or using a reducer instead, and the fluent example on the same page does it with toValue(true). So in those clients, fluent isn’t just a matter of taste.

When the attributes pile up

The book is a gentle example. Here is one where the attributes start to hurt: an order with line items that get added, adjusted and removed. This is the model-bound version, adapted from the children documentation.

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Projections.ModelBound;

[EventType]
public record OrderCreated(string CustomerName);

[EventType]
public record LineItemAdded(Guid ItemId, string ProductName, int InitialQuantity, decimal UnitPrice);

[EventType]
public record QuantityAdjusted(Guid ItemId, int NewQuantity);

[EventType]
public record LineItemRemoved(Guid ItemId);

public record Order(
    [Key] Guid Id,

    [SetFrom<OrderCreated>(nameof(OrderCreated.CustomerName))]
    string Customer,

    [ChildrenFrom<LineItemAdded>(key: nameof(LineItemAdded.ItemId))]
    [RemovedWith<LineItemRemoved>(key: nameof(LineItemRemoved.ItemId))]
    IEnumerable<OrderLine> Lines);

[FromEvent<QuantityAdjusted>(key: nameof(QuantityAdjusted.ItemId))]
public record OrderLine(
    [Key] Guid Id,

    [SetFrom<LineItemAdded>(nameof(LineItemAdded.ProductName))]
    string Product,

    [SetFrom<LineItemAdded>(nameof(LineItemAdded.InitialQuantity))]
    [SetFrom<QuantityAdjusted>(nameof(QuantityAdjusted.NewQuantity))]
    int Quantity,

    [SetFrom<LineItemAdded>(nameof(LineItemAdded.UnitPrice))]
    decimal UnitPrice);

import io.cratis.chronicle.events.EventType
import io.cratis.chronicle.projections.ChildrenFrom
import io.cratis.chronicle.projections.FromEvent
import io.cratis.chronicle.projections.RemovedWith
import io.cratis.chronicle.projections.SetFrom
import io.cratis.chronicle.readModels.ReadModel


// Events
@EventType
data class OrderCreated(val customerName: String)


@EventType
data class LineItemAdded(
    val itemId: String,
    val productName: String,
    val initialQuantity: Int,
    val unitPrice: Double
)


@EventType
data class QuantityAdjusted(val itemId: String, val newQuantity: Int)


@EventType
data class LineItemRemoved(val itemId: String)


// Read Models
@ReadModel
@FromEvent(OrderCreated::class)
data class Order(
    @SetFrom("customerName", OrderCreated::class)
    val customer: String = "",


    @ChildrenFrom(LineItemAdded::class, key = "itemId", identifiedBy = "itemId")
    @ChildrenFrom(QuantityAdjusted::class, key = "itemId", identifiedBy = "itemId")
    @RemovedWith(LineItemRemoved::class, key = "itemId")
    val lines: List<OrderLine> = emptyList()
)


data class OrderLine(
    val itemId: String = "",


    @SetFrom("productName", LineItemAdded::class)
    val product: String = "",


    @SetFrom("initialQuantity", LineItemAdded::class)
    @SetFrom("newQuantity", QuantityAdjusted::class)
    val quantity: Int = 0,


    @SetFrom("unitPrice", LineItemAdded::class)
    val unitPrice: Double = 0.0
)

import io.cratis.chronicle.events.EventType;
import io.cratis.chronicle.projections.ChildrenFrom;
import io.cratis.chronicle.projections.FromEvent;
import io.cratis.chronicle.projections.RemovedWith;
import io.cratis.chronicle.projections.SetFrom;
import io.cratis.chronicle.readModels.ReadModel;


import java.util.Collections;
import java.util.List;


// Events
@EventType
record OrderCreated(String customerName) {}


@EventType
record LineItemAdded(
    String itemId,
    String productName,
    int initialQuantity,
    double unitPrice) {}


@EventType
record QuantityAdjusted(String itemId, int newQuantity) {}


@EventType
record LineItemRemoved(String itemId) {}


// Read Models
@ReadModel
@FromEvent(eventType = OrderCreated.class)
class Order {
    @SetFrom(propertyPath = "customerName", eventType = OrderCreated.class)
    public String customer = "";


    @ChildrenFrom(eventType = LineItemAdded.class, key = "itemId", identifiedBy = "itemId")
    @ChildrenFrom(eventType = QuantityAdjusted.class, key = "itemId", identifiedBy = "itemId")
    @RemovedWith(eventType = LineItemRemoved.class, key = "itemId")
    public List<OrderLine> lines = Collections.emptyList();
}


class OrderLine {
    public String itemId = "";


    @SetFrom(propertyPath = "productName", eventType = LineItemAdded.class)
    public String product = "";


    @SetFrom(propertyPath = "initialQuantity", eventType = LineItemAdded.class)
    @SetFrom(propertyPath = "newQuantity", eventType = QuantityAdjusted.class)
    public int quantity = 0;


    @SetFrom(propertyPath = "unitPrice", eventType = LineItemAdded.class)
    public double unitPrice = 0.0;
}

defmodule MyApp.Events.OrderCreated do
  use Chronicle.Events.EventType, id: "order-created"

  defstruct customer_name: ""
end

defmodule MyApp.Events.LineItemAdded do
  use Chronicle.Events.EventType, id: "line-item-added"

  defstruct item_id: "", product_name: "", initial_quantity: 0, unit_price: 0.0
end

defmodule MyApp.Events.QuantityAdjusted do
  use Chronicle.Events.EventType, id: "quantity-adjusted"

  defstruct item_id: "", new_quantity: 0
end

defmodule MyApp.Events.LineItemRemoved do
  use Chronicle.Events.EventType, id: "line-item-removed"

  defstruct item_id: ""
end

defmodule MyApp.ReadModels.OrderLine do
  defstruct item_id: "", product: "", quantity: 0, unit_price: 0.0
end

defmodule MyApp.ReadModels.Order do
  use Chronicle.ReadModels.ReadModel,
    types: [lines: {:list, MyApp.ReadModels.OrderLine}]

  alias MyApp.Events.{LineItemAdded, LineItemRemoved, OrderCreated, QuantityAdjusted}

  defstruct order_id: "", customer: "", lines: []

  from OrderCreated, set: [order_id: :event_source_id, customer: :customer_name]

  children :lines, identified_by: :item_id do
    from LineItemAdded,
      key: :item_id,
      set: [
        item_id: :item_id,
        product: :product_name,
        quantity: :initial_quantity,
        unit_price: :unit_price
      ]

    from QuantityAdjusted, key: :item_id, set: [quantity: :new_quantity]

    removed_with LineItemRemoved, key: :item_id
  end
end

import { childrenFrom, eventType, Guid, removedWith, setFrom } from '@cratis/chronicle';
import { field } from '@cratis/fundamentals';


// Events
@eventType()
export class OrderCreated {
    customerName = '';
}


@eventType()
export class LineItemAdded {
    itemId: Guid = Guid.empty;
    productName = '';
    initialQuantity = 0;
    unitPrice = 0;
}


@eventType()
export class QuantityAdjusted {
    itemId: Guid = Guid.empty;
    newQuantity = 0;
}


@eventType()
export class LineItemRemoved {
    itemId: Guid = Guid.empty;
}


// Read Models
export class OrderLine {
    id: Guid = Guid.empty;


    @setFrom(LineItemAdded, 'productName')
    product = '';


    @setFrom(LineItemAdded, 'initialQuantity')
    @setFrom(QuantityAdjusted, 'newQuantity')
    quantity = 0;


    @setFrom(LineItemAdded, 'unitPrice')
    unitPrice = 0;
}


export class Order {
    id: Guid = Guid.empty;


    @setFrom(OrderCreated, 'customerName')
    customer = '';


    @childrenFrom(LineItemAdded, 'itemId')
    @removedWith(LineItemRemoved, 'itemId')
    @field(Array, { genericArguments: [OrderLine] }) lines: OrderLine[] = [];
}

It works, and I’d argue it’s readable as long as you already know the attribute vocabulary. But look at Quantity. Two different events set it, so the story of that one property is spread over two attributes. The story of the line is spread over an attribute on the class and attributes on its members, and the story of the removal is up on the parent. To answer “what happens when an item is removed?” you read the whole thing.

Here is the same read model as a fluent projection, with a plain read model next to it:

using Cratis.Chronicle.Projections;

public record OrderSummary(Guid Id, string Customer, IEnumerable<OrderSummaryLine> Lines);

public record OrderSummaryLine(Guid Id, string Product, int Quantity, decimal UnitPrice);

public class OrderSummaryProjection : IProjectionFor<OrderSummary>
{
    public void Define(IProjectionBuilderFor<OrderSummary> builder) => builder
        .From<OrderCreated>(_ => _
            .Set(m => m.Customer).To(e => e.CustomerName))
        .Children(m => m.Lines, children => children
            .IdentifiedBy(l => l.Id)
            .From<LineItemAdded>(_ => _
                .UsingKey(e => e.ItemId)
                .Set(l => l.Product).To(e => e.ProductName)
                .Set(l => l.Quantity).To(e => e.InitialQuantity))
            .From<QuantityAdjusted>(_ => _
                .UsingKey(e => e.ItemId)
                .Set(l => l.Quantity).To(e => e.NewQuantity))
            .RemovedWith<LineItemRemoved>(_ => _
                .UsingKey(e => e.ItemId)));
}

Kotlin does not support this workflow yet. The fluent children builder has no removedWith-equivalent method, so the line removal in this example can only be expressed with the model-bound @RemovedWith on a @ChildrenFrom property, as in the model-bound example above.

Java does not support this workflow yet. The fluent children builder has no removedWith-equivalent method, so the line removal in this example can only be expressed with the model-bound @RemovedWith on a @ChildrenFrom property, as in the model-bound example above.

defmodule MyApp.ReadModels.OrderSummaryLine do
  defstruct item_id: "", product: "", quantity: 0, unit_price: 0.0
end

defmodule MyApp.ReadModels.OrderSummary do
  use Chronicle.ReadModels.ReadModel,
    types: [lines: {:list, MyApp.ReadModels.OrderSummaryLine}]

  defstruct order_id: "", customer: "", lines: []
end

defmodule MyApp.Projections.OrderSummaryProjection do
  use Chronicle.Projections.Projection, model: MyApp.ReadModels.OrderSummary

  alias MyApp.Events.{LineItemAdded, LineItemRemoved, OrderCreated, QuantityAdjusted}

  from OrderCreated, set: [order_id: :event_source_id, customer: :customer_name]

  children :lines, identified_by: :item_id do
    from LineItemAdded,
      key: :item_id,
      set: [
        item_id: :item_id,
        product: :product_name,
        quantity: :initial_quantity,
        unit_price: :unit_price
      ]

    from QuantityAdjusted, key: :item_id, set: [quantity: :new_quantity]

    removed_with LineItemRemoved, key: :item_id
  end
end

import { IProjectionBuilderFor, IProjectionFor, projection } from '@cratis/chronicle';

class OrderSummaryLine {
    id: Guid = Guid.empty;
    product = '';
    quantity = 0;
    unitPrice = 0;
}

class OrderSummary {
    id: Guid = Guid.empty;
    customer = '';
    lines: OrderSummaryLine[] = [];
}

@projection()
class OrderSummaryProjection implements IProjectionFor<OrderSummary> {
    define(builder: IProjectionBuilderFor<OrderSummary>): void {
        builder
            .from(OrderCreated, _ => _
                .set(m => m.customer).to(e => e.customerName))
            .children<OrderSummaryLine>(m => m.lines, children => children
                .identifiedBy(l => l.id)
                .from(LineItemAdded, _ => _
                    .usingKey(e => e.itemId)
                    .set(l => l.product).to(e => e.productName)
                    .set(l => l.quantity).to(e => e.initialQuantity))
                .from(QuantityAdjusted, _ => _
                    .usingKey(e => e.itemId)
                    .set(l => l.quantity).to(e => e.newQuantity))
                .removedWith(LineItemRemoved, _ => _
                    .usingKey(e => e.itemId)));
    }
}

It isn’t shorter, and I won’t pretend it is. What changed is the shape of the reading. The two records at the top are the read model, and you can take them in at a glance, with no Chronicle attributes on them. The projection reads top to bottom as a description of the order’s life: created, line added, quantity adjusted, line removed. The question “what happens when an item is removed?” has one line to point at.

Notice what’s missing, too. UnitPrice has no mapping. Auto-mapping is on by default in fluent projections, so a property whose name matches an event property is mapped for you, and only Product, Quantity and Customer need an explicit Set because their event properties are named differently. Same rule as in model-bound, just not written down anywhere you have to look at.

What you get by pulling them apart

A read model you can read. A plain record that says what a screen or an API will see, and nothing about how it was built. The docs call this out as the point of the fluent style: the read model stays free of Chronicle attributes.
Room for the harder parts. Joins, nested children, event context and transformations all have a home in the builder, and the docs recommend declarative projections for exactly those shapes.
A projection you can share. The docs list sharing one projection definition across several read models as a reason to go declarative.
The same tests. A ReadModelScenario discovers a model-bound projection, an IProjectionFor<T> or a reducer for the read model type on its own, so switching styles doesn’t mean rewriting the specification.

What it costs

It’s more code, and the docs say so plainly. There’s also a price the attributes don’t charge: two things have to agree. The read model lives in one file, the mapping in another, and renaming a property means you have to remember there’s a second place that cares. The compiler helps, since the builder uses lambdas over your properties and a rename shows up as a build error. But a reader now has to hold two files in their head, which is, funnily enough, the exact thing model-bound saves you from.

That’s the whole trade. Cohesion on one side, readability and a clean read model on the other. Neither is the grown-up option.

Projection or reducer?

This is the one I most want to get straight, because “fluent” and “reducer” both sound like “write some code that builds the read model”, and they’re not the same thing at all.

A fluent projection is still a declaration. You describe what each event does to the read model, and Chronicle runs that description for you in the projection engine, inside the kernel. The operations on offer are a short list: set, add, subtract, increment, decrement, count and clear.

A reducer is code. It’s an IReducerFor<TModel> in your application with one method per event. Chronicle sends it the event and the current state, and it returns the next state. The kernel streams events to it and stores whatever it returns. Here is the same book once more, this time as a reducer:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Reducers;

public record BookStatusReducerModel(
    string Id,
    string Title,
    string Isbn,
    bool IsBorrowed,
    string? BorrowedBy);

public class BookStatusReducer : IReducerFor<BookStatusReducerModel>
{
    public BookStatusReducerModel OnBookRegistered(
        BookRegistered @event,
        BookStatusReducerModel? current,
        EventContext context) =>
        new(
            Id: context.EventSourceId.Value,
            Title: @event.Title,
            Isbn: @event.Isbn,
            IsBorrowed: false,
            BorrowedBy: null);

    public BookStatusReducerModel OnBookBorrowed(
        BookBorrowed @event,
        BookStatusReducerModel? current,
        EventContext context) =>
        current! with
        {
            IsBorrowed = true,
            BorrowedBy = @event.MemberName
        };

    public BookStatusReducerModel OnBookReturned(
        BookReturned @event,
        BookStatusReducerModel? current,
        EventContext context) =>
        current! with
        {
            IsBorrowed = false,
            BorrowedBy = null
        };
}

import io.cratis.chronicle.observation.Reducer

data class BookStatusReducerModel(
    val title: String = "",
    val isbn: String = "",
    val isBorrowed: Boolean = false,
    val borrowedBy: String? = null
)

@Reducer
class BookStatusReducer {
    fun choosingStyleBookRegistered(event: BookRegistered): BookStatusReducerModel =
        BookStatusReducerModel(
            title = event.title,
            isbn = event.isbn,
            isBorrowed = false,
            borrowedBy = null
        )

    fun choosingStyleBookBorrowed(
        event: BookBorrowed,
        current: BookStatusReducerModel
    ): BookStatusReducerModel =
        current.copy(isBorrowed = true, borrowedBy = event.memberName)

    fun choosingStyleBookReturned(
        event: BookReturned,
        current: BookStatusReducerModel
    ): BookStatusReducerModel =
        current.copy(isBorrowed = false, borrowedBy = null)
}

import io.cratis.chronicle.observation.Reducer;

record BookStatusReducerModel(
    String title,
    String isbn,
    boolean isBorrowed,
    String borrowedBy) {}

@Reducer
class BookStatusReducer {
    BookStatusReducerModel choosingStyleBookRegistered(BookRegistered event) {
        return new BookStatusReducerModel(event.title(), event.isbn(), false, null);
    }

    BookStatusReducerModel choosingStyleBookBorrowed(
        BookBorrowed event,
        BookStatusReducerModel current) {
        return new BookStatusReducerModel(
            current.title(), current.isbn(), true, event.memberName());
    }

    BookStatusReducerModel choosingStyleBookReturned(
        BookReturned event,
        BookStatusReducerModel current) {
        return new BookStatusReducerModel(
            current.title(), current.isbn(), false, null);
    }
}

defmodule MyApp.ReadModels.BookStatusReducerModel do
  defstruct title: "", isbn: "", is_borrowed: false, borrowed_by: nil
end

defmodule MyApp.Reducers.BookStatusReducer do
  use Chronicle.Reducers.Reducer, model: MyApp.ReadModels.BookStatusReducerModel

  alias MyApp.Events.{
    BookBorrowed,
    BookRegistered,
    BookReturned
  }

  @handles BookRegistered
  @handles BookBorrowed
  @handles BookReturned

  @impl true
  def reduce(%BookRegistered{} = event, _model, _context) do
    %MyApp.ReadModels.BookStatusReducerModel{
      title: event.title,
      isbn: event.isbn,
      is_borrowed: false,
      borrowed_by: nil
    }
  end

  def reduce(%BookBorrowed{} = event, model, _context) do
    %{model | is_borrowed: true, borrowed_by: event.member_name}
  end

  def reduce(%BookReturned{}, model, _context) do
    %{model | is_borrowed: false, borrowed_by: nil}
  end
end

import { reducer } from '@cratis/chronicle';

class BookStatusReducerModel {
    title = '';
    isbn = '';
    isBorrowed = false;
    borrowedBy: string | null = null;
}

// Handler methods receive the event, the current state, and an optional EventContext
// as a third argument; this reducer does not need the context.
// The method name must be the exact camelCase of the event's class name -
// Chronicle discovers handlers by name, not by parameter type.
@reducer('', undefined, BookStatusReducerModel)
class BookStatusReducer {
    choosingStyleBookRegistered(
        event: BookRegistered,
        current: BookStatusReducerModel | undefined
    ): BookStatusReducerModel {
        return {
            title: event.title,
            isbn: event.isbn,
            isBorrowed: false,
            borrowedBy: null
        };
    }

    choosingStyleBookBorrowed(
        event: BookBorrowed,
        current: BookStatusReducerModel
    ): BookStatusReducerModel {
        return { ...current, isBorrowed: true, borrowedBy: event.memberName };
    }

    choosingStyleBookReturned(
        event: BookReturned,
        current: BookStatusReducerModel
    ): BookStatusReducerModel {
        return { ...current, isBorrowed: false, borrowedBy: null };
    }
}

For the TypeScript reducer, handler methods only receive the event and the current state, with no event context, so that example leaves out Id. Everything else is the same idea: a fold over state instead of a definition of a mapping.

Three differences matter in practice:

Where it runs, and what it can express. A projection runs in the kernel and is limited to the operations above. A reducer runs in your app, so branching, derived values, totals with guard logic and temporal state are all just code. current has to be nullable, because the first event for an instance arrives before there’s any state, and it’s on you to keep the method free of side effects.
What a change costs. The kernel can look at a changed projection definition and, in some cases, replay only part of it. A changed reducer implementation needs a full replay. From event to read model has the details of how Chronicle classifies those changes.
How you test it. A reducer is a plain method, so the easiest test is to call it with an event and a state. A projection you’d run through a scenario. Both work with ReadModelScenario, as the next section shows.

The practical rule is the one the docs give: use the simplest style that keeps the intent obvious. And a reducer builds state, just like a projection does. If what you want is for something to happen when an event arrives, an email or a follow-up event, that’s a reactor, and Reacting to facts is about those.

Choosing

I’d put it in that order and I’d follow it honestly. Model-bound first. If you catch yourself scrolling to work out where a property comes from, or you want the read model free of attributes, move the mapping into a fluent projection. If the thing you’re describing is really a calculation, write the reducer.

And it isn’t a one-way door. Here is the book as a model-bound read model, a fluent one and a reducer, fed the same history through the same scenario:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Testing.ReadModels;
using Cratis.Specifications;
using Xunit;

public class when_a_book_is_borrowed : Specification
{
    readonly EventSourceId _bookId = EventSourceId.New();
    readonly ReadModelScenario<BookStatusModelBound> _modelBound = new();
    readonly ReadModelScenario<BookStatusFluent> _fluent = new();
    readonly ReadModelScenario<BookStatusReducerModel> _reducer = new();

    async Task Because()
    {
        object[] history = [new BookRegistered("Dune", "9780441013593"), new BookBorrowed("Ada")];

        await _modelBound.Given.ForEventSource(_bookId).Events(history);
        await _fluent.Given.ForEventSource(_bookId).Events(history);
        await _reducer.Given.ForEventSource(_bookId).Events(history);
    }

    [Fact] void should_flag_the_model_bound_book_as_borrowed() => _modelBound.Instance!.IsBorrowed.ShouldBeTrue();
    [Fact] void should_flag_the_fluent_book_as_borrowed() => _fluent.Instance!.IsBorrowed.ShouldBeTrue();
    [Fact] void should_flag_the_reduced_book_as_borrowed() => _reducer.Instance!.IsBorrowed.ShouldBeTrue();
    [Fact] void should_name_the_member_in_the_model_bound_book() => _modelBound.Instance!.BorrowedBy.ShouldEqual("Ada");
    [Fact] void should_name_the_member_in_the_fluent_book() => _fluent.Instance!.BorrowedBy.ShouldEqual("Ada");
    [Fact] void should_name_the_member_in_the_reduced_book() => _reducer.Instance!.BorrowedBy.ShouldEqual("Ada");
}

The same goes for the order from earlier. Feed the model-bound Order and the fluent OrderSummary one history, with a quantity adjusted and a line removed, and they have to agree:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.Keys;
using Cratis.Chronicle.Testing.ReadModels;
using Cratis.Specifications;
using Xunit;

public class when_a_line_is_adjusted_and_another_is_removed : Specification
{
    readonly EventSourceId _orderId = EventSourceId.New();
    readonly Guid _pen = Guid.NewGuid();
    readonly Guid _ink = Guid.NewGuid();
    readonly ReadModelScenario<Order> _modelBound = new();
    readonly ReadModelScenario<OrderSummary> _fluent = new();

    async Task Because()
    {
        object[] history =
        [
            new OrderCreated("Ada"),
            new LineItemAdded(_pen, "Pen", 2, 1.5m),
            new LineItemAdded(_ink, "Ink", 1, 4m),
            new QuantityAdjusted(_pen, 5),
            new LineItemRemoved(_ink)
        ];

        await _modelBound.Given.ForEventSource(_orderId).Events(history);
        await _fluent.Given.ForEventSource(_orderId).Events(history);
    }

    [Fact] void should_keep_one_line_in_the_model_bound_order() => _modelBound.Instance!.Lines.Count().ShouldEqual(1);
    [Fact] void should_keep_one_line_in_the_fluent_order() => _fluent.Instance!.Lines.Count().ShouldEqual(1);
    [Fact] void should_adjust_the_quantity_in_the_model_bound_order() => _modelBound.Instance!.Lines.Single().Quantity.ShouldEqual(5);
    [Fact] void should_adjust_the_quantity_in_the_fluent_order() => _fluent.Instance!.Lines.Single().Quantity.ShouldEqual(5);
    [Fact] void should_map_the_price_by_name_in_the_fluent_order() => _fluent.Instance!.Lines.Single().UnitPrice.ShouldEqual(1.5m);
}

That’s what makes the choice cheap. Start with attributes. If it stops reading well, move the mapping out, keep the events and the expected state, and let the specification tell you whether you changed behavior. Testing with Arc and Chronicle covers the scenarios in more depth.

Wrapping up

Model-bound and fluent aren’t rivals. They’re the same engine with the mapping in two different places, and the right one is whichever leaves the next person able to read the read model, or the mapping, without a detour. I said fluent gets undersold. More precisely, it’s what you reach for when cohesion has stopped paying for itself.

If you want the full reference, the docs have a page for declarative projections and one for model-bound projections. The next post, Stop filtering on status, takes the same two styles into a feature that works in both: projection variants.

AuthProxy: the edge your services shouldn't have to build

Sun, 11 Oct 2026 12:00:00 GMT

TL;DR

AuthProxy is a container you configure and put in front of your services, at the ingress. It authenticates the request, resolves the tenant, enriches the identity and forwards it all as headers, so each service can assume it’s looking at an authenticated, tenant-scoped request. It doesn’t care what your services are written in. There’s a nice Aspire integration for those who run Aspire, but at its core it’s a container with configuration. Doing this at the edge is also a security win: one place for sign-in, claims checked before anything is forwarded, spoofed headers removed, and a default that fails closed. The price is a trust boundary, because your services believe the proxy. It works with Arc through Arc’s /.cratis/me endpoint, and with Ante, the invitation and onboarding lobby, when someone is signed in but doesn’t belong anywhere yet.

The same chores in every service

Let’s face it, nobody wants to write the sign-in handshake twice. Every application grows the same crop of edge concerns: who is this user, which tenant are they in, where does this request go, and how do you bring in somebody who’s been invited but has no account yet. Without a gateway, every service re-implements them, and the copies drift. An OpenID Connect flow here, a tenant lookup there, an invite-acceptance flow in the third one.

AuthProxy is the gateway that owns those edges. It’s a reverse proxy built on YARP, and there’s no code to write. You configure it in the Cratis:AuthProxy section of appsettings.json, or with Cratis__AuthProxy__ environment variables, and run it as a container in front of your services. It’s standalone: it pairs naturally with Arc, but it will sit in front of any backend and frontend you point it at.

Everything about who the caller is gets settled at the edge.

A container you configure

I want to get one thing across before anything else. AuthProxy is a container, the cratis/authproxy image, and it doesn’t care what your stack looks like. You configure it, and you put it in front of your services at the ingress level, which is the same place you’d put any other reverse proxy.

Everything it knows about your system is configuration. A service is a base URL for a backend, a frontend or both, and the proxy sends /api/** to the backend and everything else to the frontend. This is the quickstart from the repository, with Microsoft Entra ID sign-in and the tenant taken from the host:

{
  "Cratis": {
    "AuthProxy": {
      "Authentication": {
        "OidcProviders": [
          {
            "Name": "Microsoft",
            "Type": "Microsoft",
            "Authority": "https://login.microsoftonline.com/<tenant-id>/v2.0",
            "ClientId": "<client-id>",
            "ClientSecret": "<client-secret>"
          }
        ]
      },
      "TenantResolutions": [
        {
          "Strategy": "Host"
        }
      ],
      "Services": {
        "main": {
          "Backend": {
            "BaseUrl": "http://backend:8080/"
          },
          "Frontend": {
            "BaseUrl": "http://frontend:3000/"
          }
        }
      }
    }
  }
}

That’s all of it. Nothing in there says what the backend is written in, because it doesn’t matter.

A configured container at the front. Behind it, whatever you already run.

A backend only has to speak HTTP. If it answers GET /.cratis/me, the proxy uses that to enrich the identity and to decide who may enter, and Arc answers it for you. If your service doesn’t, you set ResolveIdentityDetails to false for that service and the proxy never calls it. A frontend is any single-page app or static site.

So where does Aspire come in? If you run Aspire, there’s a Cratis.AuthProxy.Aspire package that wires the container into your AppHost with a fluent API, so you don’t set the environment variables by hand. That’s a convenience for that world. It’s not a requirement, and it’s not how the product works. The docs also have guides for running it on Azure and for Aspire.

Here’s what it handles, in the order a request meets it:

Authentication. OpenID Connect and OAuth 2.0, with one provider or several, plus JWT bearer. An unauthenticated request is challenged or sent to a provider-selection page.
Authorization. You can require a claim, such as a role, a group, or a GitHub organization or team, before anything is forwarded. Authenticating everyone is not the same as letting everyone in.
Multi-tenancy. The tenant is resolved per request, from the host, a subdomain, a claim, the route or a fixed value. Part 10 of the series follows that tenant hop by hop through Arc and Chronicle, so I won’t repeat it here.
Identity enrichment. The proxy calls an endpoint on your service and attaches the answer to the forwarded request.
Invitations and the lobby. Invite-based onboarding with signed tokens, and a lobby for users who aren’t assigned to a tenant yet.

What putting it at the edge buys you

Sign-in and authorization are the part of an application where one copy beats ten. Doing them in a proxy at the ingress gives you things that are hard to get by convention:

Six things you get from one well-placed container.

Sign-in is done once. One OpenID Connect handshake in one place, with Microsoft Entra ID, Google, GitHub, Apple or any other OIDC provider, instead of a copy in every service that slowly drifts.
Claims are checked before anything is forwarded. Require a role, a group, or a GitHub organization or team, and a request without it never reaches your code.
Spoofed headers don’t get through. The proxy removes inbound identity and tenant headers before it sets its own, so a caller can’t hand your service an identity of their own.
It fails closed. Identity verification is required by default, which means only an explicit yes admits a user. More on that below.
It only believes the peers you name. The client address and scheme come from forwarded headers, and the proxy trusts them only from the proxies you declare. That’s what the sign-in notifications and the Secure flag on cookies depend on.
Sessions and tokens are encrypted. The authentication cookie, the sign-in cookies and the tokens it issues are all encrypted, with keys from a key store you choose. If you run more than one replica, they need a shared key store (the file system, Azure Blob or Redis), or users get signed out at random.
It can stay quiet. The sign-in surface is public by default, because people have to reach it to sign in. A deployment that shouldn’t be discoverable can use capability-only admission, where nothing answers anyone without a valid capability, and everyone else gets a plain 404.

None of that makes it a firewall, and it doesn’t replace your own authorization. It does move the hardest-to-get-right code to one place, and it means your services start from a request that has already been vetted.

Services trust the proxy

I want to be upfront about the trade-off, because it’s the thing that makes the rest work. The identity and tenant reach your services as ordinary HTTP headers. Nothing in them is signed. A service believes them because of where they came from, not because of what they contain.

That puts the guarantee in your topology. AuthProxy removes any inbound copies of the identity and tenant headers before it sets its own, so a caller can’t smuggle a principal through the proxy. But a backend that can be reached some other way has no such protection. Arc is built around that. By default it doesn’t trust the forwarded identity headers, and requests stay anonymous, until you opt in. The docs on generating a principal put the rule plainly: accept these headers only from a trusted authenticated ingress that strips and replaces them, with no bypass route to the backend.

The same thinking applies to the proxy’s own surroundings. It almost never sees a browser. It sees an ingress controller, a load balancer or a CDN edge, and everything it knows about the client address and scheme comes from the forwarded headers those write. You tell it which peers are allowed to speak for someone else, because nobody else can.

Here’s the backend side for a service that uses Arc. The proxy doesn’t care how a service is built, this is just the Arc flavor of one behind it:

using Cratis.Arc;
using Cratis.Arc.Identity;

var builder = WebApplication.CreateBuilder(args);
builder.AddCratisArc(options => options.TrustForwardedIdentityHeaders = true);
builder.Services.AddMicrosoftIdentityPlatformIdentityAuthentication();
builder.Services.AddAuthorization();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.UseCratisArc();
await app.RunAsync();

public record LibraryIdentity(string DisplayName);

public class LibraryIdentityProvider : IProvideIdentityDetails
{
    public Task<IdentityDetails> Provide(IdentityProviderContext context) =>
        Task.FromResult(new IdentityDetails(context.Name != "blocked", new LibraryIdentity(context.Name)));
}

The first line of the registration is the opt-in. The provider at the bottom is the enrichment, which brings me to how the proxy and Arc talk.

How AuthProxy talks to Arc

Arc has a place for “details about the signed-in user that the token doesn’t carry”: an identity details provider. You implement IProvideIdentityDetails, and Arc serves what you return at /.cratis/me. AuthProxy calls that endpoint on your service and attaches the result to the request it forwards. You write the provider once, and every service behind the ingress benefits.

The endpoint is also a gate. IsUserAuthorized in the provider’s result decides whether the user may enter the application at all. Here’s what the endpoint above returns for a signed-in user, for one the provider turns away, and for a request with no principal (some headers left out):

GET /.cratis/me  (principal: Jane)
HTTP/1.1 200 OK
Cache-Control: no-store, private
{"id":"user-1","name":"Jane","isAuthenticated":true,"isAuthorized":true,"roles":["anonymous","authenticated"],"details":{"displayName":"Jane"}}

GET /.cratis/me  (principal: blocked)
HTTP/1.1 403 Forbidden

GET /.cratis/me  (no principal)
HTTP/1.1 401 Unauthorized

Only an explicit yes gets through.

That last sentence is a deliberate change. AuthProxy’s identity verification for a service now defaults to Required, where it used to be best effort. Under the old behavior, only a 403 refused a caller, so an unreachable service, a timeout or an unreadable answer let the request through, which meant the gateway was at its most permissive exactly when it knew the least. Now only an explicit "isAuthorized": true admits. The upgrade note has the full table, and it names the opt-out for a service that needs the old behavior. A service whose identity endpoint is down stops being served, and that’s the intent.

One caution that’s easy to miss. The identity is presentation data. It tells the frontend who’s here, and it can keep a user out of the application, but it doesn’t authorize your commands and queries. Those are protected by Arc’s own authorization, on the server, whatever the frontend shows. The identity docs are blunt about it, and I agree with them.

Arc is available for the JVM and TypeScript as well, with the same /.cratis/me idea. The details of each are in the docs and in Part 10.

Invitations, and where Ante fits

Authentication tells you who someone is. It doesn’t tell you they belong. A user who has signed in but has no tenant needs somewhere to go, and that’s what the lobby is for. AuthProxy handles three onboarding outcomes: inviting a user into an existing organization, inviting a user to create a new one, and letting a user register on their own.

The invitation flow uses a bootstrap path, /invite/<token>. The proxy validates the signed token, stages the invitation with the lobby before the user authenticates, sends them to sign in, and then checks again after they come back, so a browser can carry the values but can’t author them. By default, if the invitation’s tenant matches the tenant resolved for the request, the user continues straight into the application. If it doesn’t, they’re sent to the lobby, when one is configured.

From an invitation to a user in the right place.

The other end of that is Ante. It’s Cratis’ invitation and onboarding lobby. It signs the tokens for invitations your application issues, records when an invitee accepts or registers on their own, and publishes those facts for your application to act on. It’s built on Chronicle, so those facts are events. What it deliberately doesn’t do is own the rest: your application decides who to invite, delivers the link, runs the authenticating proxy and provisions the tenant or the membership. Ante saying “accepted” means it published the fact, not that your system has finished setting anyone up.

I should be honest about where Ante is. Its own documentation says there is no verified standalone walkthrough yet, with a host, Chronicle, MongoDB and a validating proxy wired together, and it asks you to read its security notes before you deploy. So treat the flow above as a description of how the pieces are meant to fit, and the Ante docs as the source for what it supports today.

Where it stops

AuthProxy isn’t an identity provider. It signs users in with the providers you configure. It’s also not a firewall or a replacement for network controls.
It doesn’t replace authorization in your services. It decides who gets in and with what identity, and your commands and queries still decide what they may do.
The guarantee is a network one. If a service can be reached without going through the proxy, its trust in the headers is misplaced.
It’s configuration, not code, which is the point, but it also means the details live in the configuration reference, and it’s worth reading before you run it for real.

Try it

The Arc half is easy to try on its own. Create a web project, add the Cratis.Arc package, and use the registration above. Then send a request to /.cratis/me with the three headers the proxy would send: x-ms-client-principal with a base64-encoded client principal, plus x-ms-client-principal-id and x-ms-client-principal-name. The docs show how to build a principal for local development. Only do that on a loopback host, never on something reachable from the internet.

For the proxy itself, run the cratis/authproxy container with the quickstart configuration above, pointing Backend and Frontend at your own services, and start from the AuthProxy docs. There are guides for hosting it with Aspire and for running it on Azure with Microsoft Entra ID sign-in.

Cratis Components: why it exists, and what agnostic really means

Sun, 11 Oct 2026 11:00:00 GMT

TL;DR

Cratis Components is the React layer between Arc’s generated proxies and your screens. It owns the plumbing around commands and queries, so you don’t rebuild it for every dialog and table. It’s independent of any UI library in three ways: its interaction internals are private, its look is yours through tokens and stable parts, and optional adapters can swap a small set of primitives for MUI or PrimeReact. It isn’t a promise that every component can be swapped for another library’s, and it’s React in a browser, nothing else.

What sits between the proxy and the pixel

Arc gives you generated TypeScript for your commands and queries, and that’s a great start. But a proxy is not a screen. Between the proxy and what the user sees there’s a lot of work that looks the same in every application: running a command and tracking its state, showing validation where it belongs, a dialog that closes only when the command worked, a table that subscribes to a query and knows what to show when it’s pending or empty.

That’s what Components is for. The docs put it as removing what you’d otherwise build in every application: command execution state, validation display, dialogs, observable subscriptions, paging, selection and empty states.

Arc generates the contracts, you own the screens, and Components is the plumbing in between.

One thing I like about that boundary is what Components doesn’t do. It never fetches, caches or persists your data. Command execution and query results are Arc’s state. And it has no direct dependency on Chronicle, so it behaves the same over an Arc backend that has no event sourcing at all. If you want the walk through a real screen, Part 9 of the series builds the author list and the register dialog with it, and command forms explains the form part.

How it works

You import three stylesheets once, mount one provider inside Arc’s, and then import every component from its own subpath. The package root is setup only. In the cratis template the stylesheets sit in the CSS entry file:

@import '@cratis/components/tokens';
@import '@cratis/components/styles';
@import '@cratis/components/theme';

And the provider goes inside Arc’s:

import 'reflect-metadata';
import { Arc } from '@cratis/arc.react';
import { CratisComponentsProvider } from '@cratis/components';
import { YourApp } from './YourApp';

export const App = () => (
    <Arc>
        <CratisComponentsProvider value={{ locale: 'en-US' }} toaster>
            <YourApp />
        </CratisComponentsProvider>
    </Arc>
);

Components renders its own HTML. Simple controls are semantic native elements, and a few interaction details, such as focus, overlays and dates, come from React Aria inside the package. There’s no UI library you have to install to get a working screen.

That is a change worth being honest about. Components 3 was built on PrimeReact, and installing it brought the PrimeReact dependency tree, its release cadence and its license terms, whether your own code imported PrimeReact or not. Components 4 removes that: its manifest declares no PrimeReact dependency, and a release gate checks that the emitted code has no PrimeReact imports. The reason in the docs is ownership. One token source instead of a translation chain through a third party’s preset, a dependency and license boundary you control, and a public API that evolves on Components’ own cadence.

What “agnostic” actually covers

“Agnostic” is one of those words that promises more than it should, so let me say precisely what it means here. There are three layers, and they’re different.

Independent on the inside, in how it looks, and in a few primitives.

Inside. React Aria does the focus, keyboard and overlay work, and none of its types, class names or DOM are part of what you depend on. If Components swaps it out later, you don’t migrate. That’s all “renderer-independent” means in the docs, and it’s deliberately not more. The accepted decision says the public contract is coupled to React and the browser DOM on purpose, so you get real HTML attributes, refs and form behavior. A framework-neutral target, React Native or a terminal UI isn’t what this is.

Look. Appearance is separated from behavior in three stylesheets: tokens defines the --cratis-* variables, styles is the structure, and theme is an optional baseline with dark mode. A product with its own design system skips the theme and maps its own values onto the tokens:

:root {
    --cratis-primary-color: var(--product-accent);
    --cratis-surface-card: var(--product-surface);
    --cratis-text-color: var(--product-text);
    --cratis-focus-ring: var(--product-focus-ring);
}

For one component, documented parts carry a data-cratis-part attribute and take ordinary HTML attributes through a pt prop. The styling guide covers the cascade, and Part 9 covers the Tailwind trap.

Primitives. This is where MUI and PrimeReact come in. An optional adapter swaps in that library’s version of a small set of primitives. You pick it on the provider:

import { CratisComponentsProvider } from '@cratis/components';
import { muiUiLibrary } from '@cratis/components.mui';

export const Application = () => (
    <CratisComponentsProvider value={{ locale: 'en-US' }} library={muiUiLibrary}>
        <main>Application content</main>
    </CratisComponentsProvider>
);

There are adapters for MUI, for PrimeReact 11 and for PrimeReact 10. If you’ve heard that Components supports PrimeReact and MUI out of the box, this is the current shape: the built-in renderer is the default, and the adapters are optional packages that you install and version together with Components.

What an adapter can’t swap

This is the part I’d most like you to remember. An adapter covers exactly nine slots: button, icon button, text input, text area, checkbox, radio, switch, progress bar and surface. Dialogs, dropdowns, date pickers, tooltips and the table paginator stay with Components, and so do the composites. A DataPage under the MUI adapter is still a DataPage.

Nine primitives can come from another library. The rest is Components.

You can see that boundary in the markup. The same <Button>Save</Button> renders as an element with the class cratis-button by default, and with MUI’s MuiButton-root classes under the adapter. Both keep the same data-cratis-part="root" and data-variant="solid" attributes. A command form behaves the same way: an empty title still gets the message from your C# rule under the right field with either renderer.

That’s what I’d call agnostic without the hand-waving. The behavior is Components’, the primitives can be someone else’s, and the contract in between is stable. If a screen needs something a vendor grid does, the adapter docs point to using that grid next to Components, and not inside it.

When not to use it

Use Components for screens that consume generated commands and queries. For a one-off element with no Cratis behavior, native HTML or your own component is the better answer, and the two mix without a fuss. The tables sort and filter the page that’s loaded, so a filter over a whole result is still a query argument that the server applies. And if you’re not on React in a browser, this isn’t the library.

Where to go next

Start with the Components tutorial, which builds a live list-and-detail screen, and read Part 9 for what the template does with it. If you’re coming from Components 3, the migration guide has the steps. And if you pick an adapter, install it at exactly the same version as @cratis/components, because each adapter release requires its own matching version.

Command forms: link the command, focus on the fields

Sun, 11 Oct 2026 10:00:00 GMT

TL;DR

A command form links a form to a command by its type. Arc’s CommandForm owns one instance of the generated command, and you write the fields that bind to its properties. Validation, errors under the right field and execution state come with it. Cratis Components builds fields, dialogs and steppers on top. Everything is typed from the C# command to the field, which means the compiler tells you when you got it wrong. It checks that a property exists, though, not that the control you picked fits it.

Most of a form isn’t the fields

Let’s face it, the fields are the easy part. A text box for a title, a number box for pages. It’s everything around them that eats your day: state for every input, validation rules that have to match the backend, getting a rejection from the server back to the field it was about, disabling the button while it’s busy, and doing all of that again for the next form.

I’ve always wanted that part to go away. The idea behind a command form is to give you an abstraction where you point at a command by its type and then only care about the input fields. Everything else follows from the command.

Link the command, not the state

Take a command that adds a book to a library. This is the backend, in a project made from the cratis template:

namespace Library.Books.AddBook;

[Command]
public record AddBook(string Title, string Author, int Pages)
{
    public (BookId, BookAdded) Handle() => (BookId.New(), new(Title, Author, Pages));
}

[EventType]
public record BookAdded(string Title, string Author, int Pages);

public class AddBookValidator : CommandValidator<AddBook>
{
    public AddBookValidator()
    {
        RuleFor(c => c.Title).NotEmpty();
        RuleFor(c => c.Pages).GreaterThan(0);
    }
}

A command with three properties and two rules. Nothing about a form in sight. When the project builds, Arc’s proxy generator writes AddBook.ts next to it, with the properties and a TypeScript version of the same rules:

export class AddBookValidator extends CommandValidator<IAddBook> {
    constructor() {
        super();
        this.ruleFor(c => c.pages).greaterThan(0);
        this.ruleFor(c => c.title).notEmpty();
    }
}

Rules defined once in C# end up in the browser. The validation post goes into where a rule can live and which rejections reach a field. Now the form. This is a dialog, built with Cratis Components:

import { CommandDialog } from '@cratis/components/CommandDialog';
import { InputTextField, NumberField } from '@cratis/components/CommandForm';
import { AddBook } from './AddBook';

export const AddBookDialog = () => (
    <CommandDialog
        command={AddBook}
        title='Add book'
        okLabel='Add'
        cancelLabel='Cancel'>
        <InputTextField<AddBook> value={c => c.title} title='Title' />
        <InputTextField<AddBook> value={c => c.author} title='Author' />
        <NumberField<AddBook> value={c => c.pages} title='Pages' />
    </CommandDialog>
);

That’s the whole thing. No state, no onChange, no error handling, no submit handler. CommandDialog creates the command instance, the fields bind to its properties through the accessor, and the dialog runs the command when you confirm. The CommandForm docs describe what a field binds to, and Arc’s own CommandForm is what’s underneath if you want the form without a dialog.

The fields are yours. The rest comes with the command.

Here’s what that buys you. Leave the Title field empty and move on, and the message from your C# rule appears under that field, with the input marked invalid. The Author field next to it is left alone. Type a title and the message goes away. A property that’s still unset keeps the form invalid, and a CommandDialog keeps its confirm button disabled until it’s valid. When the server rejects something instead, the rejection finds its way back to the field it names, and Part 9 of the series follows a taken name all the way back to the Name field.

One more thing I like. Arc isn’t only for .NET. It also runs on Spring Boot on the JVM, and both generate against the same TypeScript packages. The form above would be the same code whichever backend sits behind it.

The type is the guard rail

The accessor c => c.title isn’t a string. It’s a function over the generated AddBook type, so the compiler knows what c is. Misspell the property and you’re told:

error TS2551: Property 'titel' does not exist on type 'AddBook'. Did you mean 'title'?

Forget the type parameter on the field, and c is no longer an AddBook:

error TS18046: 'c' is of type 'unknown'.

That’s why every field in the docs is written InputTextField<AddBook>. The part I care about most is the one that crosses the language boundary. Rename Title to Name in C# and build, and the proxy is regenerated without title. The next TypeScript build fails at exactly the field that used it:

error TS2339: Property 'title' does not exist on type 'AddBook'.

c.title, a typed accessor. An arrow from the field leads to a red card: build fails, the property is gone. A line underneath reads: Rename it in C#, and the build finds the field." loading="lazy" decoding="async" width="3200" height="1500" src="https://blog.cratis.io/_astro/from-csharp-to-the-field.Bce4xhNx_1N1lbn.webp" srcset="">

A rename in C# is a compile error at the field, not a surprise in the browser.

In the age of agentic programming, I think this matters more than it used to. An AI assistant happily writes a plausible property name, and a plausible name is not the same as a name that exists. A compile error with a “did you mean” is a guard rail that doesn’t depend on anyone reading carefully. Good for humans, good for AI.

I want to be straight about how far that guard rail goes, though. It checks that the property exists. It doesn’t check that the control fits it. A NumberField bound to the string property title compiles without complaint, because the accessor only has to return something. Choosing the right control for a type is still on you, or on AutoCommandForm, which picks the control from the property’s type for you.

Pick the shape you need

A form in a dialog is only one way to use it, and Components has a few others on top of Arc’s CommandForm:

Dialogs, steppers and generated forms all sit on the same command form.

CommandStepper and StepperCommandDialog split one command over several named steps, for a multi-step form. And when you don’t want to write a field per property at all, AutoCommandForm generates them from the command’s own properties:

import { AutoCommandForm } from '@cratis/components/CommandForm';
import { AddBook } from './AddBook';

export const AddBookForm = () => (
    <AutoCommandForm
        command={AddBook}
        footer={<button type='submit'>Add</button>}
    />
);

A string gets an InputTextField, a number a NumberField, a boolean a CheckboxField and a date a CalendarField. Fields are the same components you’d write by hand, and you can register your own for other types.

Where it stops

Some honest limits, because a form abstraction that pretends to be everything ends up in the way:

The accessor has to be a simple property access like c => c.title. Binding resolves a property name, not an arbitrary expression.
AutoCommandForm leaves out properties it has no field for, such as nested objects, arrays and enums. If one of those is not optional, you need to seed it, or the form stays invalid. Generated titles come from the property names, and there’s no way to override one except writing that field yourself.
Don’t put an AutoCommandForm inside a CommandDialog. Each creates its own command instance, so what the user types would never reach the command the dialog runs. Write the fields by hand in dialogs and steppers.
Components is a React layer for Arc’s generated contracts. It’s a good fit for screens that run commands and show queries, and it isn’t trying to be a design system for everything else.

Try it

You can see all of this with the official template. Create a project, add the command above as Books/AddBook/AddBook.cs and the dialog as Books/AddBook/AddBookDialog.tsx, then build to generate the proxy:

dotnet new install Cratis.Templates
dotnet new cratis -n Library
cd Library
dotnet build
npm install
npm run build

Then rename a property in the C# command and build again. Watching the frontend build point at the field you forgot is the quickest way I know of to see what “typed all the way” means. If you want to go further, the Components tutorial builds a live list-and-detail screen, and Part 9 covers how the rest of the dialog’s behavior is built.

Cratis Blog

Questions and a decision guide · Decisions that hold, Part 11

The decision guide

Questions about read protection

Does a validator that reads a read model make my rule hold?

How do I turn it on, and why isn’t it on by default?

Do I still need [ProtectedDecision] and DecisionRead<T>?

Does a guard lock anything, and what does it cost?

What does a guard not cover?

Can a caller skip my validator?

Is Measure a safe place to stay?

Questions about refusals

Does Arc retry a command that conflicted?

What should a UI do with ReadChanged and ReadIncomplete?

Why does my command return a 500 under On?

Why was my reducer refused?

What if my read model is keyed by an event property?

Questions about choosing a mechanism

How do I make a value unique?

How do I enforce a rule over two entities?

What’s the difference between a per-stream read model and a stream decision?

Does an event source definition, or concurrency: true, make my rule hold?

Why did my command fail when nothing it decided on changed?

Questions about Chronicle, other languages and DCB

Can I use this from Kotlin, Java, TypeScript or Elixir?

Can I get the same guard without Arc?

Is this the Dynamic Consistency Boundary?

Questions about testing and seeing the guard

How do I test that a rule holds?

How do I see what a commit guarded?

The series

Where the docs are

How a guard is built, merged and widened · Decisions that hold, Part 10

Print the guard first

The parts of a guard

Several reads

An explicit scope beside a read

Declared concurrency on a definition

Aggregates and stream decisions

What a guard cannot see

Testing a decision against a race · Decisions that hold, Part 9

A test that passes once

A competitor between the read and the commit

What the scenario sets up for you

Seed events, not read models

Two keys

One month

Without Arc

What a green race test does not show

The same guard without Arc: decision reads and append conditions · Decisions that hold, Part 8

What Arc was doing for you

A decision read and a guarded append

Inside a request

In DCB terms

When no model fits: tail first

Results you must check

Limits

Where this goes next

Careers that remember: introducing the Cratis Cast

One file, one site

A career is an event stream

A badge the site can’t claim

The directory

Try it

How to join

What’s next

Not every rule needs a guarded read · Decisions that hold, Part 7

Start from the rule, not the tool

A unique value: a constraint

Rich behaviour: an aggregate

Two people editing: an explicit scope

A short raw stream: a stream decision

A rare violation you can repair

A hint

External data

What fails silently

Turning read protection on in an application that already runs · Decisions that hold, Part 6

Why On is not a flag you flip

The path

What Measure does and what it costs

Do I still need `[ProtectedDecision]` and `DecisionRead<T>`?

What should a UI do with `ReadChanged` and `ReadIncomplete`?

Why does my command return a `500` under On?

Does an event source definition, or `concurrency: true`, make my rule hold?