Guarantees and operational APIs
Guarantees at a glance
Section titled “Guarantees at a glance”| Area | Guarantee | Application responsibility |
|---|---|---|
| Append | A batch of events commits atomically with stream versions and tenant offsets. Provider retries within one append never duplicate it, even after a lost commit acknowledgement. | Supply the correct expected version and preserve a command’s append ID when retrying an ambiguous outcome. |
| Aggregate repository | A successful non-idempotent save clears pending events. | Keep aggregate state changes inside Apply methods. |
| Append replay | Reusing the same AppendId in one tenant returns the original append result. |
Keep append IDs unique per tenant and command. |
| Tenant order | Events have consecutive, committed TenantOffset values per tenant. |
Scope checkpoints and background reads to one tenant. |
| Transactional projection | Handler changes and checkpoint commit atomically within the provider transaction. | Use the provider-supplied transaction object (EventStoreDbContext or MongoProjectionTransaction) correctly. |
| Asynchronous projection | At-least-once delivery. | Make every handler idempotent. |
| Outbox publication | Event and message commit together; external publication is at least once. | Deduplicate at the destination with OutboxMessage.MessageId. |
| Worker leases | Fencing tokens increase monotonically across acquire, renew, and release. | Treat a lost lease as a failed ownership claim and reacquire work explicitly. |
| Snapshot | Snapshot failures never modify committed event history; unusable snapshots fall back to replay. | Keep aggregate snapshot methods and upcasters deterministic. |
Provider-neutral storage contract
Section titled “Provider-neutral storage contract”Every storage provider EventLoom supports must:
- make each append atomic;
- enforce optimistic concurrency per stream;
- assign gapless per-tenant offsets that become visible in commit order;
- scope every operation to a tenant;
- fence projection and outbox progress with monotonically increasing lease tokens;
- expose schema bootstrap and compatibility checks through
IStorageSchema.
The shared conformance suite in tests/EventLoom.Storage.Conformance verifies
these rules against every built-in provider.
Ordering and identity
Section titled “Ordering and identity”StreamVersionorders events inside one aggregate stream.TenantOffsetorders committed events inside one tenant and is the position for projections and tenant-log readers.- An event ID is UUIDv7. It is a stable event identity, but not the ordering mechanism.
AppendIdis a caller-owned idempotency key scoped to a tenant. Reusing the same append ID on a different stream in that tenant replays the original append result.- A projection identity is its
ProjectionKey(Nameand positiveVersion). Increment the version for a new read-model contract.
Provider-specific guarantees
Section titled “Provider-specific guarantees”PostgreSQL and SQLite
Section titled “PostgreSQL and SQLite”- Both relational providers use the EF Core implementation.
- Transactional projections implement
IEfProjectionHandler<TEvent>and receiveEventStoreDbContext. - Shared units of work can enlist an application
DbContextthroughunitOfWork.EnlistAsync(...)when both contexts share the same scopedDbConnection. - SQLite is explicitly single-node only.
MongoDB
Section titled “MongoDB”- The provider uses
MongoDB.Driverdirectly, not EF Core. - Transactional projections implement
IMongoProjectionHandler<TEvent>and receiveMongoProjectionTransactionwith.Sessionand.Database. - Inline projections can access the append session through
MongoSessionAccessor. - Shared units of work expose the provider session through
unitOfWork.Session. - A standalone
mongodis incompatible because EventLoom requires multi-document transactions.
Schema and health data
Section titled “Schema and health data”IStorageSchema.ValidateAsync() returns:
CanConnectMissingCountIncompatibleCountIsCompatible
EventLoom health checks surface incompatible storage through the data keys:
missing_object_countincompatible_object_count
Projection administration
Section titled “Projection administration”ProjectionAdministration always requires an explicit tenant and
ProjectionKey.
| Method | Effect | Use it when |
|---|---|---|
GetCheckpointAsync |
Reads the checkpoint and status. | Diagnosing lag or confirming recovery. |
ReadFailuresAsync |
Lists persisted failures; resolved failures are excluded by default. | Investigating a paused projection. |
ResumeAsync |
Makes a paused projection eligible to retry. | The handler, dependency, or data issue is fixed. |
SkipAsync |
Marks one failed event resolved and advances past it. | An authorized operator accepts a permanent read-model gap. |
ReplayAsync |
Resets the checkpoint to offset zero. | Rebuilding a projection version’s read model. |
ReplayAsync never clears a read model. For production rebuilds, deploy a new
projection version that writes to a new or shadow table or collection, let it
catch up, validate it, then switch readers.
Outbox administration
Section titled “Outbox administration”OutboxAdministration.GetAsync(tenantId, messageId) reads one retained
message. ReadAttemptsAsync(tenantId, messageId) reads its delivery history.
Successful messages and attempts are deleted immediately by default; configure a
positive SuccessfulDeliveryRetention to make them inspectable. Pending and
failed messages are never automatically removed.
The durable outbox worker lease name is outbox:publisher.
ASP.NET Core diagnostics boundary
Section titled “ASP.NET Core diagnostics boundary”MapEventLoomAdminDiagnostics(...) intentionally exposes only aggregate schema,
projection, and outbox summaries. It does not expose tenant IDs, event IDs,
payloads, metadata, or repair actions. Keep tenant-scoped inspection and repair
APIs behind your own authenticated and audited application boundary.