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.
Why it exists
Section titled “Why it exists”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; } }}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.
What it does
Section titled “What it does”| 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; } }}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.
The frame and its lifetime
Section titled “The frame and its lifetime”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.
Owner-only completion
Section titled “Owner-only completion”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.
After the commit
Section titled “After the commit”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));}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.
Read allowances
Section titled “Read allowances”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.
Nested invocations
Section titled “Nested invocations”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.
Acquiring a decision read
Section titled “Acquiring a decision read”| 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.
Contributed reads
Section titled “Contributed reads”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); } }}The ConcurrencyScopeOrigin of the contribution is Explicit or Aggregate. Any other origin throws ContributedReadOriginNotValid. Enrollment is atomic and runs before the call returns:
- The target (event store, namespace and sequence) must match the unit, or it throws
ReadDependencyTargetMismatch. - No staged event may match the read’s source, types and dimensions, or it throws
ReadOfSourceWithStagedEvents. - Two different explicit or aggregate scopes on one label throw
ConflictingContributionsOnLabel, orConflictingExplicitScopeswhen a decision read is on that label too. - An aggregate contribution and a decision read on the same event source throw
ReadAndAggregateOnSameSource. - 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.
Append conditions
Section titled “Append conditions”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).
Guarded entry points
Section titled “Guarded entry points”Inside a frame, these raw reads need a read allowance:
IReadModels:GetInstanceById,GetInstances,GetSnapshotsById,Observe,Watch,GetWatcherForIReducers: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.
Refusals at a glance
Section titled “Refusals at a glance”| 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.
Limits
Section titled “Limits”- Revising or redacting an event does not advance the tail, so a read folded before that change is not invalidated. Inside a frame,
ReviseandRedactare 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.
How Arc uses this API
Section titled “How Arc uses this API”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.
Related topics
Section titled “Related topics”- Decision reads — choose a model Chronicle can guard and acquire its value.
- How guards are derived — understand which events can invalidate a read.
- Choosing how a rule holds — decide between read protection and constraints.
- Concurrency scopes — declare explicit expectations for an append.
- Transactions — manage staged events and unit-of-work completion.
- CHR0062: Concurrency applies across event sources — check cross-source concurrency assumptions.