Log-consistency providers

Microsoft.Orleans.EventSourcing includes three providers:

Provider	Durable representation	RetrieveConfirmedEvents	Scale consideration
State storage	Current state snapshot, version, metadata	No	Reads and writes the complete state record
Log storage	Complete event sequence and metadata in one record	Yes	Reads and writes the complete event sequence
Custom storage	Application-defined	No, through JournaledGrain<T, U>	Determined by the implementation

State storage

LogConsistencyProvider persists a snapshot using a configured IGrainStorage. It stores the state, confirmed version, and metadata used to avoid duplication after failures.

Use it when current state is the durable requirement and the complete event history isn’t needed. Since every update writes the complete snapshot, large states increase serialization, transfer, and storage cost. Event retrieval isn’t available because events aren’t retained.

Log storage

LogConsistencyProvider persists the complete event sequence as one object using IGrainStorage. It keeps the complete sequence in memory and writes the complete sequence on updates.

It supports RetrieveConfirmedEvents, but its cost grows with the full history. Use it for samples, tests, or bounded logs. It isn’t an append-optimized production event store and isn’t suitable for an unbounded event sequence.

Custom storage

LogConsistencyProvider calls the real ICustomStorageInterface<T, U> methods implemented by the grain:

public Task<KeyValuePair<int, AccountState>> ReadStateFromStorage() =>
    throw new NotImplementedException();

public Task<bool> ApplyUpdatesToStorage(
    IReadOnlyList<AccountEvent> updates,
    int expectedVersion) =>
    throw new NotImplementedException();

public Task ClearStoredState() =>
    throw new NotImplementedException();

ReadStateFromStorage returns the confirmed version and state. ApplyUpdatesToStorage must atomically compare expectedVersion and append/apply the supplied sequence. Return false on a version conflict.

ClearStoredState clears the application-owned state when the provider supports destructive log clearing.

The provider retries after exceptions. If storage committed but the response was lost, the same update can be submitted again. The implementation must make retries idempotent or detect duplicate submissions. Returning success before the update is durable violates ConfirmEvents semantics.

Use custom storage to integrate an append-optimized event store, snapshots plus events, retention, or application-specific migration. The implementation owns durability, concurrency, event retrieval, compaction, and schema evolution.