Struct EventLog 

pub struct EventLog { /* private fields */ }

Append-only event log backed by a LanceDB dataset.

Thread-safe: the atomic seq counter ensures gap-free sequence numbers from a single writer. For multi-writer (Raft), the leader assigns seqs.

Implementations

impl EventLog

pub async fn open(storage: Arc<dyn PhysicalStore>) -> HirnResult<Self>

Create a new event log on the given storage backend.

Scans the existing events dataset (if any) to recover the next sequence number, ensuring gap-free continuation after restart.

pub fn subscribe(&self) -> Receiver<EventEnvelope>

Get a broadcast receiver for real-time event subscriptions.

pub fn subscribe_filtered(&self, filter: EventFilter) -> Receiver<EventEnvelope>

Get a filtered receiver that only delivers events matching the filter.

Spawns a background task that reads from the broadcast channel and forwards matching events to the returned mpsc::Receiver. The task terminates when the receiver is dropped or the broadcast sender is closed.

pub fn next_seq(&self) -> u64

Current next sequence number (the number of events appended so far, if no compaction has occurred).

pub async fn append( &self, realm: impl Into<String>, namespace: impl Into<String>, agent_id: impl Into<String>, event: MemoryEvent, ) -> HirnResult<EventEnvelope>

Append a single event to the log.

Assigns a monotonic seq number, writes to LanceDB, and broadcasts to real-time subscribers.

pub async fn append_signed( &self, event: MemoryEvent, realm: impl Into<String>, namespace: impl Into<String>, agent_id: impl Into<String>, secret: &[u8], ) -> HirnResult<EventEnvelope>

Append a single event with HMAC signing.

Same as Self::append but signs the event envelope with the provided secret before persisting it. Auditors can later call Self::verify_integrity to confirm no events have been tampered with.

pub async fn append_batch( &self, realm: &str, namespace: &str, agent_id: &str, events_in: Vec<MemoryEvent>, ) -> HirnResult<Vec<EventEnvelope>>

Append a batch of events atomically.

All events get consecutive seq numbers.

pub async fn read( &self, from_seq: u64, to_seq: u64, ) -> HirnResult<Vec<EventEnvelope>>

Read events in a sequence range [from_seq, to_seq] inclusive.

pub async fn tail(&self, from_seq: u64) -> HirnResult<Vec<EventEnvelope>>

Read all events from a sequence number onward.

pub async fn read_all(&self) -> HirnResult<Vec<EventEnvelope>>

Read all events matching an optional filter.

pub async fn read_with_filter( &self, filter: &EventFilter, ) -> HirnResult<Vec<EventEnvelope>>

Read events with an advanced filter.

pub async fn replay<F>(&self, handler: F) -> HirnResult<u64>

where F: FnMut(&EventEnvelope) -> HirnResult<()>,

Replay all events through a handler function to reconstruct state.

Events are read in seq order and passed one-by-one to handler.

pub async fn verify_integrity(&self, secret: &[u8]) -> HirnResult<Vec<u64>>

Verify HMAC integrity of all events in the log.

Returns the sequence numbers of events whose HMAC validation failed (missing HMAC or tampered data). An empty vec means all events are valid. Intended for use by external auditors.

pub async fn replay_from<F>(&self, from_seq: u64, handler: F) -> HirnResult<u64>

where F: FnMut(&EventEnvelope) -> HirnResult<()>,

Replay events from a specific seq onward.

pub async fn snapshot( &self, materialized_tables: &[&str], ) -> HirnResult<SnapshotMeta>

Take a snapshot at the current seq, creating LanceDB tags on materialized tables.

Returns the snapshot metadata including the seq at which it was taken.

pub async fn compact(&self, before_seq: u64) -> HirnResult<CompactionResult>

Compact (prune) events before the given sequence number.

Events with seq < before_seq are deleted from the events dataset. Call optimize afterward to reclaim storage.

pub async fn apply_retention( &self, policy: &RetentionPolicy, ) -> HirnResult<CompactionResult>

Apply a retention policy to compact old events.