Skip to content

Chronicle read protection for .NET hosts

Chronicle read protection enrolls decision reads in a .NET invocation’s unit of work and refuses raw Chronicle reads unless explicitly allowed. Use it when you own the code that begins and completes a unit of work, such as a command pipeline or request host.

A guard checks whether matching events arrived after the read’s captured position before allowing the append. If you only need to guard one append, pass it a decision read instead. For uniqueness, use a constraint.

A read through IReadModels does not by itself protect an append based on that value. Two requests can read the same state and both decide to write. Read protection catches this omission at the read call: inside the protected invocation, the raw read is refused unless you open an advisory or contributed allowance.

using Cratis.Chronicle;
using Cratis.Chronicle.ReadModels;
using Cratis.Chronicle.Transactions;
public static class ProtectedScreenData
{
// Uses ProtectedSeatReservations from the owner-commit example.
// Inside a protected invocation this plain read is refused with ReadRefusedWhileReadsAreProtected,
// because it would feed a decision without guarding it. Opening an advisory allowance says that
// a stale value is acceptable here, and the reason is required.
public static async Task<int> SeatsShownOnScreen(IEventStore eventStore, IUnitOfWork unitOfWork, ReadModelKey flightId)
{
using (unitOfWork.AllowReads(ReadAllowance.Advisory, "Shown on the booking screen. Not used for the decision."))
{
var view = await eventStore.ReadModels.GetInstanceById<ProtectedSeatReservations>(flightId);
return view?.Seats ?? 0;
}
}
}

View C# snippet source on GitHub

In this example, the seat count is for display, not for deciding whether to reserve a seat. The advisory allowance records that reason and permits the raw read without guarding it. A reservation decision needs a decision read instead, as shown below.

Protection costs more than an unprotected read and refuses reads Chronicle cannot guard exactly. See Why protection is opt-in when choosing which invocations to protect.

This is the Chronicle API that a host drives. Cratis Arc is such a host: when read protection is on for an Arc project, Arc begins the frame for each command and resolves read-model parameters through IDecisionReads.GetFor. How Arc uses this API maps Arc’s side to Chronicle’s. Read this page when you use Chronicle directly or write a host like Arc’s.

Inside a protected invocation Result
IDecisionReads.Get<T> and GetFor<T> Fold the model, enroll the read in the unit of work, then return the value
IDecisionReads.GetDetached<T> Refused with DetachedReadWhileReadsAreProtected
Raw reads (IReadModels, IReducers, event sequence reads) Refused with ReadRefusedWhileReadsAreProtected unless a read allowance is open
Immediate appends (Append, AppendMany, prepared and through-event-source variants) Refused with ImmediateAppendWhileReadsAreProtected. Stage events in the unit of work instead
Commit, Rollback and Dispose of the unit Refused unless the owner calls them
Events and reads after the unit completed Refused

Nothing changes outside a protected invocation, and nothing changes for code that never calls EnforceReadProtection().

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;
[EventType]
public record ProtectedSeatReserved(int Seats);
[Passive]
public record ProtectedSeatReservations(
string Id,
[AddFrom<ProtectedSeatReserved>(nameof(ProtectedSeatReserved.Seats))] int Seats);
public static class ProtectedReservation
{
public static async Task<bool> Reserve(IEventStore eventStore, EventSourceId flightId)
{
var unitOfWork = (UnitOfWork)eventStore.UnitOfWorkManager.Begin(CorrelationId.New());
using var frame = unitOfWork.EnforceReadProtection();
var owner = unitOfWork.ClaimDecisionReadCommitOwnership();
try
{
var reservations = await eventStore.GetDecisionReads()
.GetFor<ProtectedSeatReservations>(unitOfWork, flightId.Value);
if ((reservations.Instance?.Seats ?? 0) >= 180)
{
await unitOfWork.RollbackAsOwner(owner);
return false;
}
unitOfWork.AddEvent(EventSequenceId.Log, flightId, new ProtectedSeatReserved(1), Causation.Unknown());
await unitOfWork.CommitAsOwner(owner);
// A changed read is reported as a conflict: nothing was appended. Re-read and decide again.
return !unitOfWork.GetDecisionConflicts().Any() && unitOfWork.GetConcurrencyViolations().Count() == 0;
}
catch
{
if (!unitOfWork.IsCompleted) await unitOfWork.RollbackAsOwner(owner);
throw;
}
}
}

View C# snippet source on GitHub

GetFor enrolls the seat-count read before the reservation code uses it. The code stages a new event and commits as the unit’s owner. If a matching reservation event arrived after the captured read, the commit reports a conflict and appends nothing; read again and make a fresh decision before retrying.

Call IUnitOfWork.EnforceReadProtection() before enrolling any event or read; otherwise it throws ReadProtectionMustBeginBeforeEnrollment. It returns a ReadProtectionFrame that follows the asynchronous flow that created it.

The first call for a unit owns the frame’s lifetime. Later calls on that unit return leases whose disposal does nothing. Dispose the owning frame on success, failure and cancellation, using a using statement as in the example or a finally block.

While the frame is active, enrollment, staging and completion must use its unit. Another unit is refused with ReadProtectionUnitMismatch, even if it was set with UnitOfWorkManager.SetCurrent.

Completing the unit does not end the frame. ReadProtectionFrame.UnitCompleted reports whether the unit was committed or rolled back, but enforcement stays active until the owning frame is disposed. Protected reads after completion throw ReadAfterProtectedCommit; staging throws UnitOfWorkIsCompleted.

A unit implementation that does not support this throws UnitOfWorkReadProtectionNotSupported.

A unit that enforces read protection is completed only by its owner. Claim ownership with ClaimDecisionReadCommitOwnership(), then use CommitAsOwner(owner) or RollbackAsOwner(owner). Calling Commit(), Rollback() or Dispose() on the unit throws ProtectedUnitOfWorkRequiresOwner, so an aggregate-style Commit() in application code cannot complete the unit half-guarded. A commit that is already running throws UnitOfWorkIsCompleting for a rollback.

A successful commit validates every guard atomically with the append. A changed read is a conflict, not an exception: nothing is appended, and GetDecisionConflicts() names the model type, the key and, when the kernel reports it, the first event that changed the read. Check GetConcurrencyViolations() and GetConstraintViolations() for the other outcomes.

With no staged events, the commit still validates a guard that was supplied for validation only. A guard that exists only because a read was enrolled sends nothing, because no write means nothing to protect.

Chronicle refuses CompleteStream inside a protected invocation, even after the commit. To close a stream once the commit succeeded, run it through the owner’s frame:

using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.Transactions;
public static class ProtectedStreamClosing
{
public static Task CloseAfterCommit(ReadProtectionFrame frame, EventStreamType streamType, EventStreamId streamId) =>
frame.RunAfterCommit(sequence => sequence.CompleteStream(streamType, streamId));
}

View C# snippet source on GitHub

RunAfterCommit throws ImmediateAppendWhileReadsAreProtected if the unit did not commit successfully, or if the frame is no longer active. It permits stream completion on the unit’s own event sequence and nothing else: no read and no append.

IUnitOfWork.AllowReads(allowance, reason) opens a flow-local region for raw reads and returns an IDisposable. The reason must be a non-empty explanation; otherwise it throws ReadProtectionAllowanceNotValid. An allowance never permits an immediate append.

ReadAllowance Use it for What you must do
Advisory A read that feeds a screen, a hint or a log, where a stale value is acceptable Nothing. The read guards nothing. GetDetached is also permitted and returns an advisory read
Contributed A read that influences the decision and that you enroll yourself Enroll it with EnrolContributedRead before you use the value

Allowances are not inherited by a reducer that Chronicle runs for a decision read. Code inside the reducer that reads Chronicle meets the guards.

A read region follows the asynchronous flow, so a region opened by an outer invocation also covers any invocation it runs. A host that runs a nested invocation under the same frame, such as a command that executes another command, calls IUnitOfWork.SuspendReadRegions() when the nested invocation starts and disposes the returned scope when it ends.

While the suspension is open, reads are refused as if no region were open. A region opened inside the suspension applies as usual. Disposing the suspension restores the inherited regions. Suspensions nest, and a suspension never ends read protection or removes an enrolled guard. Calling it from a unit that does not own the active invocation throws ReadProtectionUnitMismatch.

Call Under a frame
IDecisionReads.Get<T>(key) Allowed. Enrolls the read in the ambient unit before it returns
IDecisionReads.GetFor<T>(unit, key) Allowed. Enrolls the read in the given unit, which must be the frame’s unit, before it returns. Hosts such as Arc use this
IDecisionReads.GetDetached<T>(key) Refused with DetachedReadWhileReadsAreProtected, unless an Advisory allowance is open

GetDetached exists to hand a read to a chosen append with guardedBy:. Enrolling it silently in the ambient unit would change which commit it guards, so a protected invocation refuses it. Stream-scoped overloads of Get, GetFor and GetDetached follow the same rules.

GetFor and Get also check, before the value is exposed, that no event staged in this unit would have changed the read. If one would, they throw ReadOfSourceWithStagedEvents: the read cannot see events that are staged but not committed. Decide once, then pass the value down.

IDecisionReads.Describe<T>() reports without I/O whether a model can be read, which event types it guards, and whether it uses Pinned generation delivery. See Decision reads.

For a model declaring [EventStream<TSource>(stream)], these same enrollment rules apply, but a key-only read is undefined even outside read protection. DecisionReadRefused.Reason is ReadModelRequiresStreamScope (24) for a key-only decision read or plain read. A decision read with another stream type or event source type, including an omitted source type, refuses with StreamScopeDoesNotMatchReadModel (25). Pass the declared route to Get or GetFor; use the stream-aware plain read only for advisory queries. See Read models scoped to one event stream.

Use a contributed read when a decision depends on events you read yourself, for example an aggregate rebuilt from one event source. Capture the event position that bounds the read first, read the events, then enroll a ContributedRead before using the result:

using Cratis.Chronicle;
using Cratis.Chronicle.Events;
using Cratis.Chronicle.EventSequences;
using Cratis.Chronicle.EventSequences.Concurrency;
using Cratis.Chronicle.Transactions;
[EventType]
public record ProtectedDeposit(decimal Amount);
public static class ProtectedAccountHistory
{
public static async Task<decimal> LoadBalance(IEventStore eventStore, IUnitOfWork unitOfWork, EventSourceId accountId)
{
var deposit = eventStore.EventTypes.GetEventTypeFor(typeof(ProtectedDeposit));
using (unitOfWork.AllowReads(ReadAllowance.Contributed, "Load the account history"))
{
// Capture the boundary before reading, then enroll before the value is used.
var boundary = await eventStore.EventLog.GetTailSequenceNumber();
var events = await eventStore.EventLog.GetForEventSourceIdAndEventTypes(accountId, [deposit]);
unitOfWork.EnrolContributedRead(new ContributedRead(
ConcurrencyScopeOrigin.Explicit,
accountId,
new ConcurrencyScope(boundary, accountId, EventTypes: [deposit]),
eventStore.Name,
eventStore.Namespace,
EventSequenceId.Log,
$"Account history for '{accountId}'"));
return events.Sum(_ => ((ProtectedDeposit)_.Content).Amount);
}
}
}

View C# snippet source on GitHub

The ConcurrencyScopeOrigin of the contribution is Explicit or Aggregate. Any other origin throws ContributedReadOriginNotValid. Enrollment is atomic and runs before the call returns:

  1. The target (event store, namespace and sequence) must match the unit, or it throws ReadDependencyTargetMismatch.
  2. No staged event may match the read’s source, types and dimensions, or it throws ReadOfSourceWithStagedEvents.
  3. Two different explicit or aggregate scopes on one label throw ConflictingContributionsOnLabel, or ConflictingExplicitScopes when a decision read is on that label too.
  4. An aggregate contribution and a decision read on the same event source throw ReadAndAggregateOnSameSource.
  5. A contribution without an event source throws SourceLessReadNotSupported.

IUnitOfWork.AddEventWithOptions(...) stages an event with EventEnrollmentOptions, including the Origin of its scope. The origin of an event may not be DecisionRead; that value is reserved for reads and throws ConcurrencyScopeOriginNotValidForEvents. EventEnrollmentOptions.DeclaredConcurrency and EventForEventSourceId.DeclaredConcurrency ask Chronicle to resolve the concurrency dimensions at commit instead of using a scope you computed.

At commit, Chronicle retains one condition per distinct enrolled predicate, with the earliest position for repeated reads of that predicate. Different streams and event-type filters keep independent conditions, even on the same source label; they are not broadened into one guard. The kernel must advertise concurrency-scope-conjunctions when a label has several conditions. IUnitOfWork.GetAppendConditions() returns the conditions of the last commit as AppendCondition values. Use it in tests and diagnostics to see exactly what a commit guarded.

AppendCondition member Meaning
Label The event source the condition belongs to
EventTypes, EventSourceType, EventStreamType, EventStreamId The narrowing. Empty types or a missing dimension means any
After The retained boundary. An event matching the condition after it is a conflict
ExpectsNoMatchingEvent No matching event may exist at all. This is how an absent model is guarded
Origins Which dependencies supplied the condition (AppendConditionOrigin)
Reads Descriptions of the protected reads behind it

AppendConditionOrigin is ProtectedRead, Explicit, Aggregate, DeclaredRouting or DefaultRouting.

If the commit also carries explicit scopes, each read on that label must be covered by at least one explicit scope whose boundary was captured no later than the read. Otherwise the commit is refused with ExplicitScopeDoesNotCoverReads. A declared-routing condition that the explicit scope does not cover throws DeclaredRoutingNotCoveredByExplicitScope. Scope labels starting with $read-protection/ are reserved (ReservedConcurrencyScopeLabel). Custom concurrency strategies are not supported with read protection (ReadProtectionRequiresTheDefaultConcurrencyStrategy).

Inside a frame, these raw reads need a read allowance:

  • IReadModels: GetInstanceById, GetInstances, GetSnapshotsById, Observe, Watch, GetWatcherFor
  • IReducers: GetInstanceById, GetInstances
  • Materialized read models: GetInstances, ObserveInstances
  • Event sequences: HasEventsFor, GetMetadataAt, GetFromSequenceNumber, GetPage, GetLatest, GetForEventSourceIdAndEventTypes, GetNextSequenceNumber, GetTailSequenceNumber, GetTailSequenceNumberForObserver, IsStreamCompleted, GetClosedStreams, VerifyContent
  • IProjections.Query (an ad-hoc projection over the event log)
  • IEventStore.GetNamespaces

Every public immediate append on an event sequence is refused regardless of allowances, and so are Revise, both Redact overloads and CompleteStream outside RunAfterCommit. Treat a Chronicle read that is not in this list as unguarded.

Exception When
DetachedReadWhileReadsAreProtected GetDetached under a frame without an Advisory allowance
ReadRefusedWhileReadsAreProtected A guarded raw read without an allowance
ImmediateAppendWhileReadsAreProtected An immediate append, Revise or Redact, or CompleteStream outside RunAfterCommit
ReadAfterProtectedCommit A protected read after the unit completed
ReadOfSourceWithStagedEvents A read of a source after events that match it were staged
ReadProtectionUnitMismatch Enrollment, staging or completion on a unit other than the frame’s
ReadProtectionMustBeginBeforeEnrollment EnforceReadProtection() after anything was enrolled
ProtectedUnitOfWorkRequiresOwner Commit, Rollback or Dispose by a caller that is not the owner
UnitOfWorkIsCompleted Staging after the commit began or after rollback
DecisionReadRefused The model cannot be guarded exactly. See Decision reads
ReadAndAggregateOnSameSource, SourceLessReadNotSupported The dependency combination is unsupported
ConflictingContributionsOnLabel, ConflictingExplicitScopes Explicit expectations contradict each other for one predicate, or mix no guard with a guard
ExplicitScopeDoesNotCoverReads, DeclaredRoutingNotCoveredByExplicitScope An explicit scope is narrower than what was read or declared

Use the exception to identify the missing allowance, unsupported read or ownership mismatch. Chronicle refuses a read when it cannot compute an exact guard; changing to a raw read would remove that protection.

  • Revising or redacting an event does not advance the tail, so a read folded before that change is not invalidated. Inside a frame, Revise and Redact are refused; run them as separate administrative operations. Chronicle issue #4900 tracks a kernel check.
  • A classic reducer is admitted only if it has no filters and no constructor dependencies other than ILogger<T>. A self-reducing read model is exempt from the dependency rule. See Decision reads.
  • A projection with Pinned generation delivery is refused with GenerationDeliveryNotSupported.
  • A contributed read must name one event source. Reads over many sources are refused.
  • Guards apply to one event sequence, the event log. A unit of work cannot span sequences.
  • A writer that decides without a guard can still break the rule. Protect every writer whose decision depends on that rule, or enforce it as a constraint.

Cratis Arc manages this lifetime for protected commands. If you use its command pipeline, the table below connects Arc’s command declarations to the Chronicle calls you would otherwise make in a host.

In an Arc command In the Chronicle API
Read protection is on for the project The host calls EnforceReadProtection() for each command and completes the unit as its owner
A read-model parameter that is guarded IDecisionReads.GetFor<T>(unit, key), enrolled in the command’s unit before the value is exposed
A read the command declares unprotected, with a reason AllowReads(ReadAllowance.Advisory, reason) around the read. The read guards nothing
A read the host performs itself and then enrolls AllowReads(ReadAllowance.Contributed, reason), then EnrolContributedRead before the value is used
A read model that cannot be guarded exactly DecisionReadRefused with a typed reason, such as a join, a filtered reducer, a classic reducer with constructor dependencies or a key that is not the event source ID
Events a command returns Staged in the unit and appended by CommitAsOwner. An immediate append is refused with ImmediateAppendWhileReadsAreProtected
A nested command does not inherit its caller’s read allowances SuspendReadRegions() when the nested command starts, disposed when it ends
A lost race A conflict in GetDecisionConflicts(). Nothing was appended

The word “advisory” in this API and “unprotected” in Arc mean the same thing: you accept a stale value and nothing guards it. Chronicle keeps Advisory because it also has Contributed, a read that does guard.