Table of Contents

Interface IColdEventStore

Namespace
Excalibur.EventSourcing
Assembly
Excalibur.EventSourcing.Abstractions.dll

Defines the contract for cold (archive) event storage operations.

public interface IColdEventStore

Remarks

Cold storage is optimized for cost and capacity, not read speed. Events are stored in compressed, immutable batches (e.g., in blob storage).

Used by the TieredEventStoreDecorator for transparent read-through when events are missing from the hot tier, and by EventArchiveService for writing archived events.

Every operation identifies a stream by its case-sensitive tenant, aggregate type and aggregate ID. Reads validate the entire stored batch before version filtering and return ascending versions. Mismatched identities, duplicate events, missing payloads and malformed stored data must fail rather than appear absent or authorize hot deletion. Legacy archives may derive missing tenant provenance from their exact tenant-qualified key. A legacy key occupied by another aggregate type must fail; it must never be treated as the requested stream.

Methods

HasArchivedEventsAsync(KeyedTenantPartition, string, string, CancellationToken)

Checks whether any archived events exist for an aggregate.

Task<bool> HasArchivedEventsAsync(KeyedTenantPartition tenant, string aggregateId, string aggregateType, CancellationToken cancellationToken)

Parameters

tenant KeyedTenantPartition

The tenant partition that owns the events.

aggregateId string

The aggregate identifier.

aggregateType string

The case-sensitive aggregate type belonging to this stream.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<bool>

true if archived events exist; otherwise, false.

ReadAsync(KeyedTenantPartition, string, string, long, CancellationToken)

Reads archived events for an aggregate from a specific version.

Task<IReadOnlyList<StoredEvent>> ReadAsync(KeyedTenantPartition tenant, string aggregateId, string aggregateType, long fromVersion, CancellationToken cancellationToken)

Parameters

tenant KeyedTenantPartition

The tenant partition that owns the events.

aggregateId string

The aggregate identifier.

aggregateType string

The case-sensitive aggregate type belonging to this stream.

fromVersion long

The version to start reading from (exclusive).

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<StoredEvent>>

The archived events from the specified version in order.

ReadAsync(KeyedTenantPartition, string, string, CancellationToken)

Reads all archived events for an aggregate from cold storage.

Task<IReadOnlyList<StoredEvent>> ReadAsync(KeyedTenantPartition tenant, string aggregateId, string aggregateType, CancellationToken cancellationToken)

Parameters

tenant KeyedTenantPartition

The tenant partition that owns the events.

aggregateId string

The aggregate identifier.

aggregateType string

The case-sensitive aggregate type belonging to this stream.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<IReadOnlyList<StoredEvent>>

The archived events in version order.

WriteAsync(KeyedTenantPartition, string, string, IReadOnlyList<StoredEvent>, CancellationToken)

Writes events to cold storage for a specific aggregate and returns the durable low-water mark: the highest version V such that every version <= V for this aggregate is durably committed in cold storage (post-upload/flush/quorum), and therefore safe for the caller to delete from the hot tier.

Task<long> WriteAsync(KeyedTenantPartition tenant, string aggregateId, string aggregateType, IReadOnlyList<StoredEvent> events, CancellationToken cancellationToken)

Parameters

tenant KeyedTenantPartition

The tenant partition that owns the events. Cold storage keys are composed with this term, so events archived under one tenant are unreachable from another tenant's read or watermark check.

aggregateId string

The aggregate identifier.

aggregateType string

The case-sensitive aggregate type belonging to this stream.

events IReadOnlyList<StoredEvent>

The events to archive.

cancellationToken CancellationToken

Cancellation token.

Returns

Task<long>

The durable low-water-mark version safe to delete from the hot tier, or -1 when no contiguous prefix from version zero is proven by this call.

Remarks

The returned value is a contiguous durable prefix, never the merely-submitted maximum. An implementation that persists only part of the batch (or defers a buffered write) MUST return the highest contiguously-durable version, not the highest submitted one — returning the submitted max while the write is not yet durable authorizes the caller to destroy the only other copy of not-yet-archived events. Even an acknowledged atomic upload may return -1 when the durable set does not contain version zero. The prefix must contain every version from zero.

Defined early-return acks: an empty events input returns -1 ("nothing proven by this call; delete nothing"); a batch already fully present returns the confirmed existing contiguous prefix. The caller deletes hot events only up to the returned watermark, so a partial or deferred cold write bounds hot deletion rather than losing data.