Crate paigasus_helikon_sessions_sqlite 

SQLite-backed Session implementation for the Paigasus Helikon SDK.

Stores conversation event logs in a single SQLite database. Multiple sessions share one SqlitePool and are isolated by session_id. Safe for concurrent writers — appends serialize through SQLite’s database-level write lock; the (session_id, sequence) primary key is the uniqueness backstop.

Recommended pool configuration

use sqlx::sqlite::{
    SqliteConnectOptions, SqliteJournalMode, SqlitePoolOptions, SqliteSynchronous,
};
use std::time::Duration;

let opts = SqliteConnectOptions::new()
    .filename("sessions.db")
    .create_if_missing(true)
    .journal_mode(SqliteJournalMode::Wal)
    .synchronous(SqliteSynchronous::Normal)
    .busy_timeout(Duration::from_secs(30));
SqlitePoolOptions::new().connect_with(opts).await

synchronous = NORMAL is the recommended pairing with WAL for multi-writer workloads: commits stop fsyncing individually (the WAL is synced at checkpoints instead), which multiplies write throughput under contention. The trade-off is durability, not integrity — after a power loss the most recent commits may be missing, but the database cannot corrupt. Keep sqlx’s default FULL if losing any acknowledged append is unacceptable.

Concurrent appends under contention

Writers serialize on SQLite’s single database-level write lock. busy_timeout caps how long one append waits for that lock, and under sustained contention the worst-placed writer waits out the entire backlog ahead of it — so size the timeout against (concurrent writers) × (appends per writer) × (worst-case transaction latency), not against a single transaction. An append that exhausts the timeout fails with SessionError::Backend wrapping SQLITE_BUSY (“database is locked”). The failure is clean: nothing from the failed call is persisted, no stored data is lost or corrupted, and the session remains usable (pinned by this crate’s busy_timeout integration test). 30 seconds is a sane starting point; tune upward for heavy multi-writer contention.

Provider-translator caveat

The project function in paigasus-helikon-core renders Compacted events as Item::System. Both shipped provider translators reshape system messages — Anthropic hoists them to the top-level system field, OpenAI concatenates them. Compaction summaries reach the model but as top-level instructions, not positional cutovers.

Structs

SqliteSession

SQLite-backed Session implementation. One instance is one session (identified by session_id); pools are shared across instances.