Specify Chronicle occurrence retries and receipts
Use Cratis.Chronicle.Testing to check that a Cratis Chronicle trigger handler recovers from retries and lost replies without appending the same effect twice. Each scenario owns isolated in-memory storage and needs no running kernel. You control recording, delivery and time separately: advancing time never invokes a handler.
Start with a typed trigger and handler from application triggers. The examples below use Cratis.Chronicle.Testing, .Events and .Occurrences, together with Cratis.Chronicle.Occurrences. ImportRequested denotes your attributed trigger and ImportHandler its IOccurrenceHandler<ImportRequested> implementation. Dispose each store and scenario after its specification.
Choose the advertised kernel capabilities
Section titled “Choose the advertised kernel capabilities”An EventStoreForTesting advertises Current() by default, including precise event schemas, occurrences and effect receipts. Its scenarios discover precise schemas rather than the legacy fallback shape. Change the advertised capabilities when you need to check how your code handles an older kernel or an unknown compatibility result.
For example, create using var store = new EventStoreForTesting();, then call store.Capabilities.Old(); before exercising a receipt enrollment. unit.UseEffectReceipt(key) throws EffectReceiptsNotSupported. store.Capabilities.Unknown(); models a skipped or failed compatibility check and also fails closed. store.Capabilities.Current(); restores the current advertisement.
Schema discovery happens during store construction. To choose the advertisement before discovery, create a KernelCapabilitiesForTesting, call Old() or Unknown(), and pass it to new EventStoreForTesting(null, artifacts, null, new ScenarioTime(), capabilities). Changing the switch afterward changes operation admission, not schemas already discovered.
Commit an event and its receipt together
Section titled “Commit an event and its receipt together”A receipt specification should check both the stored outcome and the absence of duplicate events. Use the real unit of work with the scenario’s store. For example:
- Create
using var unit = new UnitOfWork(CorrelationId.New(), _ => { }, store);fromCratis.Chronicle.Transactions. - Enroll
unit.UseEffectReceipt(context.EffectKey("import"));. - Stage an event with
unit.AddEvent(EventSequenceId.Log, "import", new ImportCompleted(), Causation.Unknown());. - Run
await unit.Commit();and inspectunit.IsSuccessandunit.EffectReceipt. - Read
await store.Occurrences.GetEffectReceipt(context.EffectKey("import"));to recover the winning result.
The append and receipt use the real kernel append path and the production in-memory storage’s atomic write. Repeating the effect key in a fresh unit returns AlreadyRecorded and appends no second batch, even when the repeated handler computes different content. Receipt-only operations accept NoEvents or Refused, for example await store.Occurrences.RecordEffectReceipt(key, new NoEvents());.
For a validate-only example, enroll the key, then call unit.AddEvents(EventSequenceId.Log, [], [new("source", new ConcurrencyScope(EventSequenceNumber.BeforeFirst, "source"))]); before committing. The empty batch validates that source’s scope and records NoEvents only if it still matches. A conflicting append writes no receipt. Explicit scopes use Cratis.Chronicle.EventSequences.Concurrency; protected decisions use their normal owning completion capability.
Record and deliver a typed trigger
Section titled “Record and deliver a typed trigger”Use an occurrence scenario when you want to exercise delivery as well as the effect’s commit. Create using var scenario = new OccurrenceScenario<ImportHandler>(); and register constructor dependencies in scenario.Services before the first operation. The scenario supplies its own IEventStore, IEventLog and IUnitOfWorkManager.
Record with var recorded = await scenario.Record(new ImportRequested(), "import-42");, then invoke var outcome = await scenario.DeliverNext();. Successful handling returns Completed. await scenario.StatusOf(recorded.Id) returns the durable snapshot, including attempts, epoch, next attempt and receipts. With nothing claimable, delivery returns NothingDue.
Each attempt activates a fresh handler in a fresh dependency scope. The scenario runs the real occurrence service and delivery policy over in-memory storage, but replaces the Orleans queue’s reminder/timer shell with explicitly driven, serialized calls. There are no background workers or automatic lease renewals. These specifications do not test silo recovery, network transport, production persistence or lifecycle fan-out.
Build an occurrence context
Section titled “Build an occurrence context”For a handler or command specification that needs a context without delivery, use new OccurrenceContextBuilder().For<ImportRequested>().WithIdempotencyId("import-42").BuildDetached().
The builder derives the occurrence identity from the trigger selected when you build the context. Calling WithIdempotencyId before or after For<T>() or ForTrigger(id) therefore gives the same identity. An explicit WithId(id) always wins over the derived identity, whichever is called first.
For<T>() reads the identity from the Trigger attribute on T and throws TriggerNotValid when the attribute is missing; it does not scan assemblies. OccurrenceScenario<THandler> finds its trigger from the single IOccurrenceHandler<TTrigger> the handler implements and the Trigger attribute on that type; it throws TriggerNotValid otherwise.
Use WithId(id), Kind(kind), RecordedAt(instant), DueAt(instant), Attempt(number) and Epoch(number) to select individual metadata values. Attempts and epochs default to one.
A detached context owns no durable lease: receipts still deduplicate, but completing its token returns OccurrenceLeaseLost. For a real lease, use await new OccurrenceContextBuilder(store.Time).For<ImportRequested>().WithIdempotencyId("import-42").RecordAndClaimIn(store) instead. This seeds a synthetic occurrence with an empty payload and claims it; it does not validate a payload or invoke a handler. The trigger queue must be empty. Recorded contexts default to the store’s clock; detached contexts use the builder’s clock.
Advance time and retry explicitly
Section titled “Advance time and retry explicitly”ScenarioTime starts at 2026-01-01T00:00:00Z, or at the instant supplied to its constructor. Now and GetUtcNow() report UTC.
To check retry timing, call await scenario.DeliverNextFailing(new ImportFailed()); with your exception type. This records a failure and normal backoff without invoking the handler; it checks delivery policy, not your handler’s error path. Read the snapshot, then call scenario.Time.AdvanceTo(snapshot.NextAttempt); and await scenario.DeliverNext();. Delivery before the backoff expires returns NothingDue. Exceptions thrown by the handler follow the same failure path; exhausted attempts become quarantined.
Use scenario.Time.Advance(TimeSpan.FromSeconds(60)); to expire a lease. Moving backward through either advance method throws ScenarioTimeCannotMoveBackwards and preserves the current instant.
To share an explicit clock with event scenarios, construct new Defaults(artifacts, null, null, time) and pass those defaults to EventScenario or OccurrenceScenario<ImportHandler>. EventScenario.Time exposes that clock. Event append timestamps and receipt timestamps still use the kernel’s system clock; this driver controls occurrence recording, lease expiry and backoff only.
Lose a reply after commit
Section titled “Lose a reply after commit”A lost reply tests the gap between a durable commit and the handler knowing it succeeded. Queue a fault with scenario.Replies.DropNext(DroppedReply.Append); before delivery. The next successful receipted or keyed append (any append shape) commits, then throws Grpc.Core.RpcException with StatusCode.Unavailable.
For a receipted handler append, the handler attempt fails, but its receipt survives. Retry after backoff with the same effect key and assert that the original outcome wins without duplicate events.
For keyed appends through store.EventLog, queue the same fault with store.Replies.DropNext(DroppedReply.Append);. Retry AppendOnce or AppendManyOnce with the same IdempotencyKey after reply loss; the retry reports AlreadyAppended without duplicating events. The named-tag variants behave the same way.
Other fault points are RecordEffectReceipt, RecordOccurrence, ClaimOccurrences, CompleteOccurrence and FailOccurrence. For example, store.Replies.DropNext(DroppedReply.RecordEffectReceipt, 2); discards two successful receipt-only replies. Dropped counts replies actually discarded, not faults queued. Refused mutations and ordinary appends without a receipt or idempotency key do not consume these faults.
When a reply is lost, inspect durable state or retry with the same identity rather than creating replacement work. A lost claim remains leased until expiry. A repeated completion at the same epoch returns AlreadyCompleted.
To model a worker lost after its effects but before completion, call await scenario.DeliverWithoutCompleting();. It returns Delivered, leaving the successful lease intact. Advance past its expiry and deliver again to check receipt-based recovery.
Assert on collected state
Section titled “Assert on collected state”After delivery, assertions are synchronous:
scenario.ShouldHaveReceipt(context.EffectKey("import"));checks the collected receipt identity.scenario.ShouldHaveAppended<ImportCompleted>();checks events collected from the scenario’s event log; a predicate overload checks their content.scenario.ShouldBeQuarantined(recorded.Id);checks a collected occurrence snapshot.
Delivery collects its occurrence and the event log automatically. After a direct service mutation, await scenario.StatusOf(id) to refresh that occurrence before asserting on it. Assertions perform no hidden asynchronous work and throw OccurrenceScenarioAssertionFailed when an expectation is unmet.
Use integration specifications against a running kernel for restart, clustering and provider durability. See effect receipts for the production commit and recovery contract.