Chronicle event constraints
A constraint is an append-time invariant. Chronicle evaluates it inside the append, against the event store's own index — so it is the only mechanism that holds when two requests race. A command-side pre-check reads state that may already be stale by the time the append lands; a constraint cannot be.
Constraints are discovered automatically. There is no registration call.
A constraint binds every writer, whichever client or service appends, so it is
the mechanism for uniqueness and create-once. It cannot count, sum or test a
predicate: capacity and stock rules need a guarded read (read protection On), a stream decision or an
aggregate. Read choosing how a rule holds
when it is unclear which one a rule needs.
Requires Chronicle 19.82.2 for constraint-index gap repair.
A failed
post-append index update marks a gap: subsequent governed appends repair the
index from the event log or return ConstraintIndexUnavailable in the result's
error collection without writing. Do not remove the constraint or blindly retry an unknown
append outcome; see append outcomes.
Constraints apply per event store namespace and event sequence, so tenants in
different namespaces can claim the same value. A constraint is not re-run when
the kernel retries a duplicate sequence number.
Verified in the tagged kernel sources listed by append outcomes:
Source/Kernel/Core/EventSequences/EventSequence.AppendSettlement.cs and
EventSequence.Validation.cs.
Verified product sources
| Package | Purpose |
|---|---|
Cratis.Chronicle (client) |
uniqueness, stream closing, constraint builders and append results |
Cratis.Chronicle code analysis |
CHR0017, CHR0018, CHR0020 |
Cratis.Chronicle.Testing |
EventScenario and the IAppendResult Should* assertions |
Sources: Source/Clients/DotNET/Events/Constraints/,
EventSequences/IEventSequence.cs and Source/Clients/Testing/.
Reverify against the Chronicle repository before claiming support for another version. Never translate an attribute argument order or an assertion name from memory.
Route near misses
- The rule rejects command input — a range, a format, a cross-field
condition: use
cratis-arc-command-validation. - The rule is state-dependent (a count, a capacity, a status) and needs
concurrency protection: use read protection
Onor stream decision reads withcratis-arc-command-validationandcratis-chronicle-decision-reads. Injected models and validators underOff(the default), andResult<,>alone, remain advisory. - You are creating or changing a read model that the rule reads: use
cratis-chronicle-read-model. - You are writing the specification and want the
EventScenariomechanics in depth: usecratis-chronicle-event-specifications. - An accepted
.playmodel under the model root covers the behavior, or the repository is opted in (pergeneral.md"Model first"; wherecratis-screenplay-modeling-lifecycleis installed, run itsscripts/model-first-status.mjs): change the model first withcratis-screenplay-event-modeling. If the Screenplay skills are not installed, say so and do not author.playfrom memory. Edit code here only for infrastructure, clients, adapters, Screenplay code attachments, or gap-fill scope (cratis-screenplay-render-and-gap-fill); never edit Stage-managed output.
Step 1 — Pick the mechanism
| Situation | Use |
|---|---|
| One event of this type per event source | class-level [Unique] on the event type |
| A property value unique across event sources | property-level [Unique] on that property |
| Release a claimed value when something is removed | [RemoveConstraint("name")] on the removal event |
| The same value must be unique across several event types | IConstraint with one [Unique(name: …)] name, or a fluent Unique(…) |
| Case-insensitive matching, composite keys, or a scoped constraint | IConstraint |
Class-level [Unique] (and Unique<TEvent>()) means "at most one such event
per event source id". Property-level [Unique] (and Unique(unique => unique.On<T>(…)))
means "this value is unique across event sources". Mode tunes property-value
retention, not that distinction: PerEventSource (default) releases the old
value when the source claims a new one; PerValue keeps every value reserved
until a removal releases it. Reclaiming one's own value succeeds in either mode.
Step 2 — [Unique] — the default
// Event-type uniqueness — only one of this event per event source
[EventType]
[Unique(message: "A project with this name already exists.")]
public record ProjectRegistered(ProjectName Name);
// Property uniqueness — the value must be unique across event sources
[EventType]
public record UserRegistered([Unique(name: "UniqueEmail", message: "Email already registered.")] EmailAddress Email, DisplayName Name);
// Release a claimed value on removal — the name must match the [Unique] name exactly
[EventType]
[RemoveConstraint("UniqueEmail")]
public record UserRemoved;
UniqueAttribute's constructor is(string? name = default, string? message = default)— name first, message second. Pass them by name, as above, so a future reader cannot misread the order.- The attribute targets
Class | Property,AllowMultiple = false. - The name defaults to the member or type name when omitted. Give it an
explicit name whenever a removal event or another event type has to refer to
it, because the string in
[RemoveConstraint]must match exactly. RemoveConstraintAttributeis class-only withAllowMultiple = true. Stack several on one removal event to release several claimed values at once.- To enforce the same property across multiple event types, give each its
[Unique(name: "UniqueEmail")]with the same name. - Several removal events may declare the same name; any one releases the claim.
Mode = UniqueConstraintMode.PerValueretains all values. A removal can useProperties = [nameof(RemovalEvent.Value)]to release one value (composite properties in constraint order); emptyPropertiesreleases all values held by the source in the scope.EventSequences = [EventSequenceId.LogId]limits validation/indexing to the event log. Empty means every sequence; when declarations share a name, their sequence sets combine and an unrestricted declaration wins.- Null/missing property values do not claim
""; clearing a default-mode value releases its claim.IgnoreCasingis honored by the kernel.
Step 3 — IConstraint — the advanced form
Reach for IConstraint when uniqueness spans event types with different
property names, needs .IgnoreCasing(), covers a composite of properties, or a
RemovedWith event must release it.
public class UniqueProjectName : IConstraint
{
public void Define(IConstraintBuilder builder) =>
builder.Unique(unique =>
unique
.On<ProjectRegistered>(e => e.Name)
.IgnoreCasing() // case-insensitive — do NOT lowercase inside the lambda
.RemovedWith<ProjectRemoved>()); // omit if there is no remove event
}
IUniqueConstraintBuilder also carries WithName(name), WithMessage(message),
WithMode(UniqueConstraintMode), and an On(EventType, string[]) overload. On<TEvent> is variadic —
On<T>(e => e.Tenant, e => e.Email) constrains the composite of both
properties, not two independent values.
IConstraintBuilder additionally offers PerEventSourceType(),
PerEventStreamType(), and PerEventStreamId() to narrow the scope a
uniqueness claim is keyed by, and a Unique<TEvent>(message, name) overload for
event-type uniqueness. That overload takes the message first and the name
second — the reverse of the [Unique] attribute. Both parameters convert
implicitly from string, so the wrong order compiles and silently swaps them.
Always pass them by name.
ConstraintScope is a record of three optional dimensions, not an enum, and you
never construct it — the three Per… calls select which dimensions participate.
ForEventSequences(...) / ForEventLog() select the sequences to validate and
index. Keep these separate from scope dimensions.
Step 4 — Keep Define declarative
Define builds a rule; it never runs one. Three analyzers enforce that, all at
error severity:
| Id | Rejects |
|---|---|
CHR0017 |
Injecting IEventLog or ICommandPipeline into a constraint |
CHR0018 |
An imperative statement in Define — if, loops, switch, return, throw, a local declaration, an assignment |
CHR0020 |
An expression lambda that is not a pure member-access chain |
CHR0020 is the one that bites: e => e.Email.ToLower() is a method call, so
it is rejected. Use .IgnoreCasing() instead. Suppressing the analyzer does not
make it work — the runtime path extracts an empty property path from a
method call and then fails at startup with PropertyDoesNotExistOnEventType,
which is a much harder failure to read.
Step 5 — Treat a violation as a result, never as an exception
A violated constraint comes back on the append result, not as a throw. On
IAppendResult: IsSuccess, HasConstraintViolations,
HasConcurrencyViolations, HasErrors, ConstraintViolations, and Errors.
Each ConstraintViolation carries ConstraintName, ConstraintType,
Message, Details, the EventTypeId and the SequenceNumber. Arc surfaces
it as a validation error on the command result.
Note the asymmetry: AppendResult exposes a singular nullable
ConcurrencyViolation, while AppendManyResult exposes a plural
ConcurrencyViolations. Only the HasConcurrencyViolations flag is on the
interface.
⚠️ Constraints are evaluated and indexed against the plaintext of a [PII]
property, not its ciphertext — PII encryption is non-deterministic (a fresh key
and nonce per value), so hashing the encrypted form would never detect a
collision. The kernel builds a plaintext copy for the constraint check and
persists only the encrypted event; on reindex it releases (decrypts) stored
content to recompute the hashes, and skips subjects whose key has been erased so
they do not all collide on the hash of an empty value. The index therefore holds
plaintext-derived hashes, not the personal value itself.
Read references/storage-uniqueness.md when upgrading SQL/in-memory constraints or reindexing duplicates: Requires Chronicle 19.59.7 for SQL atomic claim indexes, 19.59.3 for in-memory claim preservation and 19.59.1 for duplicate-tolerant reindex.
Step 6 — Specify the violation
Specify the constraint with EventScenario: seed the conflicting state through
Given, append again, and assert
ShouldHaveConstraintViolationFor(<Module>ConstraintNames.UniqueX) — the
constraint name by default. A message is presentation text and will change
without the behavior changing. Assert exact message text only when that wording
is the specified behavior, and name that behavior in the fact.
The example compiles into the application assembly, so it uses #if DEBUG.
Dedicated spec projects need no wrapper.
#if DEBUG
public class and_the_name_already_exists : Specification
{
EventScenario _scenario;
IAppendResult _result;
async Task Establish()
{
_scenario = new EventScenario();
await _scenario.Given
.ForEventSource(ProjectId.New())
.Events(new ProjectRegistered("Acme"));
}
async Task Because() =>
_result = await _scenario.EventLog.Append(ProjectId.New(), new ProjectRegistered("Acme"));
[Fact] void should_be_failed() => _result.ShouldBeFailed();
[Fact] void should_have_constraint_violation_for_unique_name() =>
_result.ShouldHaveConstraintViolationFor(ProjectConstraintNames.UniqueProjectName);
}
#endif
Use per-test unique values ($"{Guid.NewGuid():N}") so specifications are not
order-dependent. For a release, append the removal event and then assert the
value can be claimed again.
⚠️ The default EventScenario client scope strategy answers ConcurrencyScope.None.
A scenario-only concurrency assertion without a checked scope is vacuous.
The scenario runs the kernel grain/validator, but explicit-scope violations
have not been proven end to end here; use real-client integration for that proof.
Constraints are fully exercisable. Dispose the scenario in Destroy().
Close a stream at its business end
Choose the lifetime with cratis-chronicle-event-modeling, then enforce it at
append time. IEventSequence.CompleteStream(ClosedStreamScope, expectedTailSequenceNumber?) returns Result<EventSequenceNumber, CompleteStreamError>:
EmptyScope, AlreadyCompleted, or ExpectedTailMismatch are not successful
new closures. An append matching a persisted closed scope is refused with
StreamClosed. Unspecified dimensions are wildcards, so name the intended
source/type/stream dimensions precisely.
Prefer an event-owned declaration when closing is a business fact:
[ClosesStream] / IConstraintBuilder.ClosesStreamOn<TEvent>(). The attribute
has Dimensions, EventStreamIdFrom, ReopenedBy, Name and EventSequences;
default dimensions are source id, stream type and stream id. Closing happens in
the same grain turn as append, not crash-atomically with it. Registering
the declaration is not retroactive; reindex rebuilds event-owned closures.
Reopening events remove only their constraint's exact closure, never a manual
operator closure.
Read closing scope and recovery when implementing
"close the books", choosing a scope, specifying the refusal, or repairing a
mistaken manual close. IsStreamCompleted and GetClosedStreams inspect;
Workbench's Closed streams page is read-only. Kernel ReopenStreamScope
requires an authorized operator and records StreamScopeReopened before
removing a manual closure. Closing does not erase history or prevent replay.
What breaks
- The constraint never fires. You used class-level
[Unique]for a value that has to be unique across event sources, or property-level[Unique]for a "one per event source" rule. Re-read Step 1 — the kind is the switch. [RemoveConstraint]releases nothing. It releases attribute constraints ([Unique]on a property or on the event type); on a fluentIConstraintit compiles and does nothing, so use.RemovedWith<T>()there. Otherwise the string does not match the[Unique]name. When[Unique]had no explicit name the real name is the member or type name, which is easy to get wrong; name it explicitly.PropertyDoesNotExistOnEventTypeat startup. A non-member-access lambda reached the builder — theCHR0020case with the analyzer suppressed.MissingNameForUniqueConstraint/NoEventTypesAddedToUniqueConstraint. The fluent builder was built without a name, or without anyOncall.NoUniqueEventTypeConstraintToRemove.IConstraintBuilder.RemovedWith<T>()was called with no precedingUnique<TEvent>(). That method attaches to the last event-type constraint; the fluent one onIUniqueConstraintBuilderis a different method.
Verify
- Every constraint is discovered without a registration call.
[Unique]arguments are passed by name, and every name a removal event refers to is explicit rather than defaulted.Definecontains no imperative statement, no injected effect dependency, and no lambda that is not a pure member-access chain —CHR0017,CHR0018andCHR0020are all clean.- Every constraint has an
EventScenariospecification that seeds the conflict and assertsShouldHaveConstraintViolationFor(<name>)on the name. - Violation message strings are not asserted by default. Exact wording is asserted only when it is the specified behavior, named in the fact.
- Build clean in Debug and Release, and the specifications pass.