Struct EventEnvelope 

pub struct EventEnvelope {

    pub event_id: EventId,
    pub stream_id: StreamId,
    pub sequence_number: u64,
    pub timestamp: OffsetDateTime,
    pub correlation_id: CorrelationId,
    pub causation_id: Option<CausationId>,
    pub conversation_id: ConversationId,
    pub process_id: ProcessId,
    pub tenant_id: TenantId,
    pub workflow_id: WorkflowId,
    pub event_type: Box<str>,
    pub schema_version: u32,
    pub payload: Value,
}

A single persisted event, wrapped in engine-level metadata.

The envelope separates infrastructure concerns (identity, ordering, tracing) from domain concerns (the business event payload). The payload is stored as serde_json::Value so the engine remains domain-agnostic.

Sequence numbers

sequence_number is 1-based and monotonically increasing per stream. It is assigned by the EventStore during EventStore::append and must not be set by callers.

Immutability

Once persisted, an envelope is never modified. Corrections are modelled as new events.

Fields

event_id: EventId

Globally unique event instance identifier (assigned by store).

stream_id: StreamId

The stream this event belongs to (e.g. process/xxxxxxxx).

sequence_number: u64

1-based monotonic position within the stream (assigned by store).

timestamp: OffsetDateTime

Wall-clock time at which the event was appended to the store (assigned by store).

correlation_id: CorrelationId

Groups all events that originate from the same root command.

causation_id: Option<CausationId>

The event or command that directly caused this event, if any.

conversation_id: ConversationId

Links events belonging to the same business conversation (e.g. a UTILMD exchange and its APERAK acknowledgement).

process_id: ProcessId

Stable identifier for the MaKo process instance that owns this stream.

tenant_id: TenantId

Tenant that owns this event (market participant or deployment tenant).

workflow_id: WorkflowId

Identifies the workflow definition (name + BDEW format version) that produced this event.

event_type: Box<str>

Stable, human-readable type discriminant for the domain event (e.g. "SupplierChangeInitiated").

Used for projection routing and observability without deserializing the full payload.

schema_version: u32

Schema version of the serialized payload. Increment when the payload structure changes to enable upcasting during replay.

payload: Value

The domain event payload, serialized as JSON.

Implementations

impl EventEnvelope

pub fn decode<T: DeserializeOwned>(&self) -> Result<T, Error>

Deserialize the payload into a typed domain event.

Clones the serde_json::Value payload and deserializes T from it directly. Use EventEnvelope::decode_owned to consume the envelope and avoid the clone when the envelope is no longer needed.

Errors

Returns a serde_json::Error when deserialization fails.

pub fn decode_owned<T: DeserializeOwned>(self) -> Result<T, Error>

Deserialize the payload into a typed domain event, consuming the envelope to avoid an extra clone.

Prefer this over EventEnvelope::decode when you no longer need access to the envelope after decoding (e.g. in one-shot projection handlers that transform each event exactly once).

Errors

Returns a serde_json::Error when deserialization fails.

pub fn from_new( new: NewEvent, stream_id: StreamId, sequence_number: u64, timestamp: OffsetDateTime, ) -> Self

Construct an envelope from a NewEvent with store-assigned fields.

Called internally by EventStore implementations during append.

impl EventEnvelope

pub fn new_caused_event<E: EventPayload>( &self, workflow_id: WorkflowId, event: &E, ) -> Result<NewEvent, EngineError>

Build a NewEvent causally linked to this envelope.

Propagates correlation_id, conversation_id, process_id, and tenant_id from the envelope and sets envelope.event_id as the causation_id of the new event. Useful when generating a follow-up event (e.g. an APERAK trigger event) that must be traceable back to the UTILMD envelope that caused it.

Errors

Returns EngineError::Serialization when the event payload cannot be serialized to JSON.

Example

// After persisting a UTILMD receive event, trigger an APERAK:
let aperak_new = utilmd_envelope.new_caused_event(
    workflow_id,
    &SupplierChangeEvent::AperakDispatched { positive: true, reason: None },
)?;

Trait Implementations

impl Clone for EventEnvelope

fn clone(&self) -> EventEnvelope

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EventEnvelope

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for EventEnvelope

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for EventEnvelope

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.