Struct SessionJournal 

pub struct SessionJournal { /* private fields */ }

Thread-safe, append-only, hash-chained session journal.

Create one per session and share it (via Arc<SessionJournal>) with all guards that need session-aware context.

Implementations

impl SessionJournal

pub fn new(session_id: String) -> Self

Create a new empty journal for the given session using the DEFAULT process memory budget caps.

Session-aware guards that hold a CONFIGURED process memory budget should prefer Self::from_memory_budget so lowering journal_entry_cap (or journal_tool_counts_cap) actually tightens each per-session journal instead of every caller silently retaining the compiled-in default.

pub fn from_memory_budget( session_id: String, budget: &MemoryBudgetConfig, ) -> Self

Create a new empty journal whose entry-ring and distinct-tool-name caps come from a CONFIGURED process memory budget. Threading the operator’s chio_kernel::MemoryBudgetConfig (rather than a fresh defaults() read inside Self::new) means lowering journal_entry_cap / journal_tool_counts_cap on the process budget actually bounds each per-session journal, so a multi-session workload stays within the configured budget instead of every session retaining the default 4096 entries.

pub fn with_entry_cap(session_id: String, entry_cap: usize) -> Self

Create a new empty journal with an explicit entry-ring capacity and the default distinct-tool-name cap. The entries and tool_sequence rings are bounded to entry_cap; data_flow stays cumulative and tool_counts is cumulative but distinct-key bounded.

pub fn with_caps( session_id: String, entry_cap: usize, tool_counts_cap: usize, ) -> Self

Create a new empty journal with explicit entry-ring and distinct-tool-name caps. entry_cap bounds the entries and tool_sequence rings; tool_counts_cap bounds the number of DISTINCT tool names retained in the cumulative tool_counts map fail-closed.

pub fn session_id(&self) -> &str

Return the session identifier.

pub fn record(&self, params: RecordParams) -> Result<u64, SessionJournalError>

Append a new entry to the journal.

The entry is hash-chained to the previous entry. Returns the sequence number of the new entry.

pub fn data_flow(&self) -> Result<CumulativeDataFlow, SessionJournalError>

Return a snapshot of the cumulative data flow statistics.

pub fn snapshot(&self) -> Result<SessionJournalSnapshot, SessionJournalError>

Return a coherent snapshot of guard-facing journal state.

The snapshot captures cumulative data flow, tool sequence, tool counts, entry count, and head hash while holding one journal lock. Guards that need more than one view should prefer this method over multiple getters.

pub fn tool_sequence(&self) -> Result<Vec<String>, SessionJournalError>

Return the ordered tool invocation sequence (bounded to the entry cap).

pub fn tool_counts(&self) -> Result<HashMap<String, u64>, SessionJournalError>

Return per-tool invocation counts.

pub fn tool_counts_len(&self) -> Result<usize, SessionJournalError>

Number of DISTINCT tool names currently retained in the cumulative tool_counts map. Bounded above by the journal’s tool_counts_cap. Exposed so a telemetry exporter or the kernel’s bounded-structure registry can observe how close the per-session distinct-key set is to saturation once the journal is wired into a live dispatch path.

pub fn len(&self) -> Result<usize, SessionJournalError>

Return the number of entries in the journal.

pub fn is_empty(&self) -> Result<bool, SessionJournalError>

Return whether the journal is empty.

pub fn entries(&self) -> Result<Vec<JournalEntry>, SessionJournalError>

Return a clone of the retained journal entries (bounded to the entry cap).

pub fn recent_entries( &self, n: usize, ) -> Result<Vec<JournalEntry>, SessionJournalError>

Return the most recent N entries (or all retained if fewer than N exist).

pub fn verify_integrity(&self) -> Result<(), SessionJournalError>

Verify the integrity of the hash chain.

Returns Ok(()) if all entries are correctly chained, or an error indicating where the chain breaks.

pub fn head_hash(&self) -> Result<String, SessionJournalError>

Return the exported head hash: the most recent entry hash before any eviction, or (once a prefix has been evicted) a fold of the evicted prefix and the retained tail, so the head stays committed to the full sequence across eviction (or the zero hash if empty).

Trait Implementations

impl Debug for SessionJournal

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

Formats the value using the given formatter.