Struct AuditLog 

pub struct AuditLog { /* private fields */ }

A session-scoped, append-only sequence of AuditEntry records that enforces monotonic sequence numbers and hash-chain continuity on every append.

Invariants

• Every entry’s seq equals the previous entry’s seq + 1 (genesis: seq = 0).
• Every entry’s previous_hash equals the preceding entry’s entry_hash (genesis entry uses [0u8; 32]).

Both invariants are checked by AuditLog::push at append time. AuditLog::verify_chain re-validates them across the entire stored log.

Implementations

impl AuditLog

pub fn new(agent_id: AgentId, session_id: SessionId) -> Self

Create a new, empty AuditLog for the given agent and session.

The log starts with next_seq = 0 and last_hash = [0u8; 32] (the genesis previous-hash sentinel).

pub fn entries(&self) -> &[AuditEntry]

Read-only view of all entries in append order.

pub fn len(&self) -> usize

Number of entries currently stored in the log.

pub fn is_empty(&self) -> bool

Returns true if the log contains no entries.

pub fn agent_id(&self) -> AgentId

The agent identifier associated with this log.

pub fn session_id(&self) -> SessionId

The session identifier associated with this log.

pub fn push(&mut self, entry: AuditEntry) -> Result<(), AuditLogError>

Append a pre-built AuditEntry to the log, validating both invariants.

Errors

• AuditLogError::SequenceGap if entry.seq() != self.next_seq.
• AuditLogError::HashChainBroken if entry.previous_hash() != &self.last_hash.

On error the log is not modified.

pub fn next_entry( &mut self, event_type: AuditEventType, timestamp_ns: u64, payload: String, ) -> &AuditEntry

Build and append the next AuditEntry in one atomic step.

seq and previous_hash are derived automatically from the log’s current state, eliminating the risk of caller-side sequencing errors.

Parameters

• event_type — category of the governance event.
• timestamp_ns — nanoseconds since Unix epoch (caller-supplied for no_std compatibility).
• payload — pre-serialized UTF-8 string (JSON in practice).

Returns a reference to the newly appended entry.

pub fn next_entry_with_lineage( &mut self, event_type: AuditEventType, timestamp_ns: u64, payload: String, lineage: Lineage, ) -> &AuditEntry

Build and append the next AuditEntry with lineage fields in one atomic step.

Equivalent to AuditLog::next_entry but attaches agent-topology metadata. seq and previous_hash are derived automatically from the log’s current state.

Parameters

• event_type — category of the governance event.
• timestamp_ns — nanoseconds since Unix epoch (caller-supplied for no_std compatibility).
• payload — pre-serialized UTF-8 string (JSON in practice).
• lineage — optional agent-topology fields; Lineage::default() produces the same hash as AuditLog::next_entry with the same base fields.

Returns a reference to the newly appended entry.

pub fn verify_chain(&self) -> bool

Re-validate the entire log in O(n), checking both invariants for every entry.

Returns true if:

• Every entry passes AuditEntry::verify_integrity (SHA-256 matches stored hash).
• Every entry’s seq is exactly one greater than the previous entry’s seq (first entry must have seq = 0).
• Every entry’s previous_hash matches the preceding entry’s entry_hash (first entry must have previous_hash = [0u8; 32]).

Returns true for an empty log (vacuously valid).