Struct ComponentStateEnvelope 

pub struct ComponentStateEnvelope { /* private fields */ }

The full durable envelope for one committed component-state namespace.

Every identity field is validated, and the checksum is verified against the raw payload bytes, before any application decode or migration step runs.

Implementations

impl ComponentStateEnvelope

pub fn encode<T>( namespace: ComponentStreamIdentity, value: &T, codec: &(impl ComponentStateCodec<T> + ?Sized), limits: StateLimits, ) -> Result<Self, ComponentStateError>

Encodes a current typed value as a bounded inline envelope.

Never falls back to an external reference: an oversized or over-deep candidate fails rather than being silently inlined or silently stored elsewhere. A caller that wants external representation constructs one explicitly with Self::external.

Errors

Returns a redacted codec, bounds, or shape failure.

pub fn external( namespace: ComponentStreamIdentity, schema_id: StateSchemaId, schema_version: StateSchemaVersion, codec_id: CodecId, codec_version: CodecVersion, reference: ExternalStateReference, ) -> Self

Constructs an envelope wrapping an already-stored external reference.

The caller is responsible for having already stored the bytes through an ExternalStateStore and for supplying the identity/version the reference was encoded under.

pub fn from_durable( namespace: ComponentStreamIdentity, schema_id: &str, schema_version: u32, codec_id: &str, codec_version: u32, checksum_algorithm: u16, checksum_algorithm_version: u16, checksum: [u8; 32], payload: ComponentStatePayload, limits: StateLimits, ) -> Result<Self, ComponentStateError>

Validates raw durable columns and reconstructs an undecoded envelope.

The checksum is verified against the raw payload bytes before any JSON parsing, schema/codec compatibility check, or migration step runs. A mismatch never invokes decode, never invokes migration, and never substitutes empty or default state.

Errors

Returns a redacted identity, checksum, bounds, or shape failure.

pub fn decode<T>( &self, codec: &(impl ComponentStateCodec<T> + ?Sized), ) -> Result<T, ComponentStateError>

Decodes the retained inline payload through codec.

Applies the schema-axis migration chain (delegated to the same algorithm crate::Checkpoint/crate::ExecutionContext use) and then the codec-version migration chain, in that order, before calling the codec’s own decode.

Errors

Returns ComponentStateError::ExternalReferenceMissing when the payload is an unresolved external reference (resolve it through an ExternalStateStore and decode the resolved bytes with the component’s own codec instead), or a redacted identity, compatibility, or codec failure.

pub fn validated_for_open<T>( &self, codec: &(impl ComponentStateCodec<T> + ?Sized), ) -> Result<Self, ComponentStateError>

Validates and migrates this envelope to codec’s current schema and codec versions, without decoding to an application type.

This is the pre-open enforcement point (Gate C): the runtime calls this through a registered stream’s StreamStateContract before crate::ItemStream::open ever runs, so an unknown/newer schema or codec, or a migration failure, is rejected before any application code sees the envelope. An external-reference payload has no inline bytes to migrate. Current schema and codec versions are accepted; older external versions fail closed until a resolution/migration capability exists.

Errors

Returns a redacted identity, compatibility, or migration failure without invoking the codec’s own decode step. Older external schema or codec versions report that external migration is unsupported because this method cannot resolve their out-of-band bytes.

pub const fn namespace(&self) -> &ComponentStreamIdentity

Borrows the owner-scoped namespace.

pub const fn schema_id(&self) -> &StateSchemaId

Borrows the validated application schema identifier.

pub const fn schema_version(&self) -> StateSchemaVersion

Returns the retained application schema version.

pub const fn codec_id(&self) -> &CodecId

Borrows the validated codec identifier.

pub const fn codec_version(&self) -> CodecVersion

Returns the retained codec version.

pub const fn is_external(&self) -> bool

Returns whether this envelope’s payload is inline or external.

pub const fn checksum_algorithm(&self) -> u16

Returns the checksum algorithm identifier protecting this envelope.

pub const fn checksum_algorithm_version(&self) -> u16

Returns the checksum algorithm version protecting this envelope.

pub const fn checksum(&self) -> [u8; 32]

Returns the checksum value protecting this envelope.

An authorized persistence adapter uses this alongside Self::checksum_algorithm/Self::checksum_algorithm_version to write the durable checksum column; Self::from_durable recomputes and verifies it from the same inputs on read.

pub fn payload(&self) -> Result<ComponentStatePayload, ComponentStateError>

Returns the bounded payload representation an authorized persistence adapter durably stores.

Errors

Returns a redacted format failure if the retained inline value cannot be serialized. This does not happen for a payload this type itself already validated.

pub fn encoded_len(&self) -> usize

Returns the validated inline payload byte size, or the declared external blob size.

Trait Implementations

impl Clone for ComponentStateEnvelope

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ComponentStateEnvelope

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

Formats the value using the given formatter.

impl Eq for ComponentStateEnvelope

impl PartialEq for ComponentStateEnvelope

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ComponentStateEnvelope