Crate polyc_eventlog 

Append-only conversation event log on a commonware-storage journal.

This crate persists the ordered stream of events that make up a conversation (user messages, planner decisions, tool calls, …) to an append-only log backed by the Commonware storage stack — keeping persistence on the Commonware primitives rather than a relational store.

Storage primitive

EventLog wraps commonware_storage::journal::contiguous::variable::Journal: a contiguous, position-based, variable-length append-only journal. It is the natural fit here:

• Append-only. EventLog::append writes one Event and returns the monotonically increasing u64 position the journal assigned it. Positions start at 0 and never reused; pruning earlier entries does not shift later positions.
• Ordered replay. EventLog::replay returns every event in append order, each paired with its position. Append order is the ordering contract: the caller appends events in conversation order (turn, then sequence within a turn), and replay yields them back in exactly that order. The position therefore is the (turn, seq) ordinal flattened into one strictly increasing sequence — there is no separate sort key to maintain, which is precisely what an append-only log buys us.
• Variable-length items. Each event’s payload is an opaque, buffa-encoded byte blob of arbitrary size; the variable journal stores variable-length items natively (the contiguous::fixed sibling is for fixed-width records and would not fit).

Runtime genericity (tokio vs. deterministic)

The journal — and therefore EventLog — is generic over a commonware_storage::Context (the Storage + Clock + Metrics bound every Commonware storage type carries). Production drives it on the commonware_runtime::tokio backend; tests drive it on the commonware_runtime::deterministic backend for seeded, reproducible runs. The two never nest: per the prior commonware-transport spike, the Commonware runtime cannot be started from inside a live tokio runtime, so a tokio control plane hosts it on a dedicated thread. This crate stays runtime-agnostic and leaves that hosting decision to the caller.

Conversation scoping

One EventLog instance maps to one conversation’s log, identified by the storage partition name passed to EventLog::open (derive it from the conversation id, e.g. format!("conv-{uid}")). Distinct conversations use distinct partitions and so are fully isolated on disk.

Example

use commonware_runtime::{deterministic, Runner};
use polyc_eventlog::{Event, EventLog, EventLogConfig};

let executor = deterministic::Runner::default();
executor.start(|context| async move {
    let log = EventLog::open(context, EventLogConfig::for_partition("conv-1"))
        .await
        .expect("open log");

    log.append(&Event::new("user_msg", b"hello".to_vec())).await.unwrap();
    log.append(&Event::new("tool_call", b"\x01\x02".to_vec())).await.unwrap();
    log.commit().await.unwrap();

    let events = log.replay().await.unwrap();
    assert_eq!(events.len(), 2);
    assert_eq!(events[0].kind, "user_msg");
});

Re-exports

pub use error::EventLogError;

pub use event::Event;

pub use event::EventCfg;

pub use taint::GrantedCapabilities;

pub use taint::TrifectaLegs;

pub use taint::TrustTag;

pub use taint::any_untrusted;

pub use taint::any_untrusted_excluding;

pub use taint::trifecta_legs;

Modules

error

Errors surfaced by the event log.

event

The Event item stored in the log and its commonware_codec wiring.

nav

Lexical navigation over a conversation’s own history.

taint

Trust/provenance capability tags and the “lethal trifecta” detector.

Structs

EventLog

An append-only, ordered log of conversation Events.

EventLogConfig

Configuration for opening an EventLog.