chio-http-session

chio-http-session is the per-session audit journal for Chio's guard pipeline: an in-process, thread-safe, append-only, hash-chained record of tool invocations, cumulative data flow, and delegation depth for a single session. Guards hold a SessionJournal per session, append to it on every tool call via record, and read it back through a single-lock SessionJournalSnapshot.

Despite the shared chio-http-* prefix, this crate is unrelated to chio-http-core: it defines no HTTP request/response types and no wire framing. chio-http-core::SessionContext is the mutable, request-scoped context threaded through HTTP evaluation; chio-http-session::SessionJournal is the durable, tamper-evident history of invocations that guards such as chio-guards' advisory, data-flow, and behavioral-sequence guards consult across the life of a session. Neither type references the other.

Responsibilities

• Append-only, hash-chained record of tool invocations for one session (JournalEntry, with a SHA-256 entry_hash computed over each entry's fields on append).
• Cumulative counters for data flow (bytes read/written, invocation count, max delegation depth), tool sequence, per-tool counts, and a consecutive-run streak, all of which survive ring eviction.
• Capacity-bounded entries and tool_sequence rings, defaulting to caps sourced from chio_kernel::MemoryBudgetConfig, with evicted entries folded into a running head hash so head_hash and verify_integrity still commit to the dropped prefix.
• Fail-closed distinct-key cap on tool_counts: once tool_counts_cap distinct tool names are held, a previously-unseen name is dropped rather than admitted.
• A single-lock SessionJournalSnapshot giving guards one coherent read of data flow, tool sequence, tool counts, streak, and head hash.
• Rejects empty, padded, or control-character-bearing tool_name, server_id, or agent_id before they reach the hash chain.

Public API

• SessionJournal - the thread-safe journal. Constructors: new, from_memory_budget, with_entry_cap, with_caps.
• SessionJournal::record(RecordParams) -> Result<u64, SessionJournalError> - append one entry, returning its sequence number.
• SessionJournal::{snapshot, data_flow, tool_sequence, tool_counts, tool_counts_len, len, is_empty, entries, recent_entries, verify_integrity, head_hash, session_id} - read APIs.
• RecordParams - the append input (tool_name, server_id, agent_id, bytes_read, bytes_written, delegation_depth, allowed).
• JournalEntry - the persisted entry shape.
• CumulativeDataFlow - total_bytes_read, total_bytes_written, total_invocations, max_delegation_depth.
• SessionJournalSnapshot - the guard-facing read view.
• SessionJournalError - LockPoisoned, InvalidRecordField { field }, IntegrityViolation { index, expected, actual }.

Usage

use chio_http_session::{RecordParams, SessionJournal};

let journal = SessionJournal::new("session-1".to_string());

journal
    .record(RecordParams {
        tool_name: "read_file".to_string(),
        server_id: "srv-1".to_string(),
        agent_id: "agent-1".to_string(),
        bytes_read: 128,
        bytes_written: 0,
        delegation_depth: 0,
        allowed: true,
    })
    .unwrap();

let snapshot = journal.snapshot().unwrap();
assert_eq!(snapshot.entry_count, 1);

Testing

cargo test -p chio-http-session

See also

• chio-http-core - defines the HTTP-facing SessionContext and request evaluation types; unrelated to this crate despite the shared prefix.
• chio-guards - the primary consumer; its advisory, data-flow, and behavioral-sequence guards hold an Arc<SessionJournal> for session-aware decisions.
• chio-kernel - supplies MemoryBudgetConfig, the source of this journal's default entry and tool-count caps.