Struct ChainEntry 

#[non_exhaustive]
pub struct ChainEntry {
    pub id: ChainEntryId,
    pub scope: String,
    pub sequence: u64,
    pub previous_hash_hex: String,
    pub event: ProvenanceEvent,
    pub recorded_at: DateTime<Utc>,
    pub entry_hash_hex: String,
    pub parent_hashes_hex: Vec<String>,
    pub chain_version: u8,
}

One entry in the append-only chain.

#[non_exhaustive] from klieo-provenance 2.0.0 onwards — new optional fields can land in a minor without forcing struct-literal updates. New callers construct via ProvenanceChain::append (or ProvenanceChain::append_with_parents for v2 multi-parent entries); reading the public fields stays unchanged.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

id: ChainEntryId

Random id for this entry.

scope: String

Free-form scope this chain belongs to.

sequence: u64

0-based monotonic position in the chain.

previous_hash_hex: String

Hex SHA-256 of the prior entry, or GENESIS_HASH_HEX for sequence == 0.

event: ProvenanceEvent

The audit event this entry records.

recorded_at: DateTime<Utc>

Wall-clock at which the entry was minted, rounded to ms precision.

entry_hash_hex: String

Hex SHA-256 of this entry’s canonical inputs.

parent_hashes_hex: Vec<String>

Additional semantic-derivation parents (v2+). Empty for linear chains. Non-empty when an entry derives from multiple prior facts (e.g. M5 PathRAG verbalisation across several path hops). Sorted lexicographically before hashing for determinism (see Self::compute_hash_v2). Legacy v1 JSON deserialises with this field empty via #[serde(default)].

chain_version: u8

Canonicalisation version that produced Self::entry_hash_hex. 1 for entries minted before ADR-037 (legacy JSON has no field; the #[serde(default)] hook supplies 1); 2 for entries minted by ProvenanceChain::append under klieo-provenance 2.0+. Verification dispatches per-entry on this value, so chains may contain a v1 prefix and a v2 suffix and still verify end-to-end.

Implementations

impl ChainEntry

pub fn canonical_timestamp(recorded_at: DateTime<Utc>) -> String

Canonical timestamp form — pinned to ms precision + Z suffix.

pub fn compute_hash_v1( previous_hash_hex: &str, sequence: u64, event: &ProvenanceEvent, recorded_at: DateTime<Utc>, ) -> String

Canonical SHA-256 hash for the legacy v1 entry shape.

Canonical input: prev_hex_bytes || seq_be_bytes || ts_bytes || event_canonical_bytes. Bit-identical to the pre-ADR-037 compute_hash; preserved verbatim so v1 entries serialised before the migration still verify.

pub fn compute_hash_v2( previous_hash_hex: &str, sequence: u64, event: &ProvenanceEvent, recorded_at: DateTime<Utc>, parent_hashes_hex: &[String], ) -> String

Canonical SHA-256 hash for the v2 entry shape (ADR-037).

Canonical input: 0x02 || prev_hex_bytes || seq_be_bytes || ts_bytes || event_canonical_bytes || sorted_parents_separated. parent_hashes_hex is sorted lexicographically before hashing so the call-site order is irrelevant. A null byte separates adjacent parent strings to make parent boundaries unambiguous. The leading 0x02 distinguishes v2 entries from v1 entries with identical payloads and empty parent sets.

pub fn compute_hash_for_version( chain_version: u8, previous_hash_hex: &str, sequence: u64, event: &ProvenanceEvent, recorded_at: DateTime<Utc>, parent_hashes_hex: &[String], ) -> Result<String, ProvenanceError>

Dispatch to the version-specific hash algorithm.

Returns Err(ProvenanceError::UnsupportedChainVersion) for any chain_version outside {1, 2}. Verifiers MUST refuse unknown versions rather than fall back to a default — a chain with an unknown version cannot be cryptographically validated.

Trait Implementations

impl Clone for ChainEntry

fn clone(&self) -> ChainEntry

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ChainEntry

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ChainEntry

fn deserialize<__D>( __deserializer: __D, ) -> Result<ChainEntry, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ChainEntry

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

where __S: Serializer,

Serialize this value into the given Serde serializer.