Table of Contents

Class StoredEvent

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

Represents a stored event with persistence metadata.

public sealed record StoredEvent : IEquatable<StoredEvent>
Inheritance
StoredEvent
Implements
Inherited Members

Constructors

StoredEvent(string, string, string, string, byte[]?, byte[]?, long, DateTimeOffset)

Represents a stored event with persistence metadata.

public StoredEvent(string EventId, string AggregateId, string AggregateType, string EventType, byte[]? EventData, byte[]? Metadata, long Version, DateTimeOffset Timestamp)

Parameters

EventId string

The unique event identifier.

AggregateId string

The aggregate identifier.

AggregateType string

The aggregate type name.

EventType string

The event type name.

EventData byte[]

The serialized event data, or null when the payload is not in the hot store. A missing payload must be interpreted using the explicit event type and archive metadata:

  • Erased (the event type is the explicit erasure marker): the payload must not be restored or delivered. An erasure marker can retain an archive timestamp.
  • Archived (not erased, and ArchivedAt has a value): the payload was moved to cold storage. A reader must resolve and validate that payload before delivering the event.

A null payload without an explicit erasure marker is unresolved, including when no archive timestamp is present. It must fail processing rather than silently advance a checkpoint. Archival and erasure preserve the entry's version and global position in the hot stream.

Metadata byte[]

The serialized event metadata.

Version long

The event version within the aggregate.

Timestamp DateTimeOffset

When the event occurred.

Properties

AggregateId

The aggregate identifier.

public string AggregateId { get; init; }

Property Value

string

AggregateType

The aggregate type name.

public string AggregateType { get; init; }

Property Value

string

ArchivedAt

Gets the recorded time this event's payload was moved to cold storage, or null when no archival timestamp is recorded. This value does not establish whether an event was erased.

public DateTimeOffset? ArchivedAt { get; init; }

Property Value

DateTimeOffset?

Remarks

Archival moves the PAYLOAD and leaves the ENTRY. The row, its version and its global position all remain in the hot store. A projection rebuild must resolve archived payloads before replaying those events; an unresolved payload must stop progress. Deleting the row instead would make the archived events invisible to every global-stream consumer while remaining perfectly readable per-aggregate, which is the kind of partial disappearance nothing downstream can detect.

Check the explicit erasure marker before attempting restoration, even if this timestamp remains populated. See EventData for the missing-payload processing rules.

EventData

The serialized event data, or null when the payload is not in the hot store. A missing payload must be interpreted using the explicit event type and archive metadata:

  • Erased (the event type is the explicit erasure marker): the payload must not be restored or delivered. An erasure marker can retain an archive timestamp.
  • Archived (not erased, and ArchivedAt has a value): the payload was moved to cold storage. A reader must resolve and validate that payload before delivering the event.

A null payload without an explicit erasure marker is unresolved, including when no archive timestamp is present. It must fail processing rather than silently advance a checkpoint. Archival and erasure preserve the entry's version and global position in the hot stream.

public byte[]? EventData { get; init; }

Property Value

byte[]

EventId

The unique event identifier.

public string EventId { get; init; }

Property Value

string

EventType

The event type name.

public string EventType { get; init; }

Property Value

string

GlobalPosition

Gets the global stream position: the store-wide, monotonically increasing append ordinal of this event across all aggregates. Used by global-stream consumers to order and checkpoint in global append order.

public long GlobalPosition { get; init; }

Property Value

long

The 1-based global ordinal, or 0 when the provider does not assign one. Distinct from Version, which is the per-aggregate version.

Not every provider assigns a global position. The relational providers (SQL Server, PostgreSQL, Oracle, SQLite) and the in-memory provider allocate it from a position counter inside the appending transaction, so their committed positions are always a contiguous prefix with no holes. The document and key-value providers do not: they report no position for an append and leave this value at 0, so a global-stream ordering over them is not available and must not be inferred from this property. Check the position reported by the append rather than assuming one was assigned.

Metadata

The serialized event metadata.

public byte[]? Metadata { get; init; }

Property Value

byte[]

TenantId

Gets the authoritative tenant term read from the event's owning store, or null when the provider or stored representation does not supply it.

public string? TenantId { get; init; }

Property Value

string

Remarks

Unknown provenance is not an untenanted event. Providers with a tenant column return its explicit tenant term, including the reserved untenanted term for legacy untenanted rows. Cross-tenant readers must not substitute their ambient tenant when this value is unknown. Older serialized events remain readable with an unknown value.

Timestamp

When the event occurred.

public DateTimeOffset Timestamp { get; init; }

Property Value

DateTimeOffset

Version

The event version within the aggregate.

public long Version { get; init; }

Property Value

long