batpak

Sync-first event sourcing for Rust: append-only log, causal metadata, policy gates, projections, subscriptions, and typestate-friendly workflows without an async runtime.

Start In 5 Minutes

cargo xtask setup
cargo run --example quickstart

If you just want the crate:

cargo add batpak

use batpak::prelude::*;

let config = StoreConfig::new("./batpak-data")
    .with_sync_every_n_events(100)
    .with_sync_mode(SyncMode::SyncData);
let store = Store::open(config)?;

let coord = Coordinate::new("player:alice", "room:dungeon")?;
let kind = EventKind::custom(0xF, 1);
let receipt = store.append(&coord, kind, &serde_json::json!({"x": 10, "y": 20}))?;
println!("stored {} at {}", receipt.event_id, receipt.sequence);

store.close()?;
# Ok::<(), Box<dyn std::error::Error>>(())

Pick Your Lane

• User lane: cargo build, cargo test, cargo run --example quickstart
• Maintainer lane: cargo xtask doctor, cargo xtask ci, cargo xtask preflight (gold standard before pushing)
• Perf lane: cargo xtask bench --surface neutral|native [--save|--compare]

What You Get

• Append-only segment store with CRC32 integrity
• Optional Blake3 hash chains
• Causal metadata and region queries
• Atomic batch append: multi-event commit with two-phase markers, crash recovery, and intra-batch causation
• Fault injection framework (dangerous-test-hooks feature) for chaos testing batch and write paths
• Gate / receipt workflow for policy enforcement
• Event-sourced projections with optional native file-backed cache
• subscribe_lossy / cursor_guaranteed delivery names that say what they do
• close(self) -> Closed for explicit durable shutdown; Drop is best-effort only
• Query/read operations yield StoredEvent<serde_json::Value> at the storage boundary

Docs

• Guide
• Architecture reference
• Tuning reference
• Contributing
• Agent guide
• Specification

Features

• blake3 (default): hash-chain verification
• dangerous-test-hooks: explicit test-only runtime hooks

Canonical Commands

cargo xtask doctor
cargo xtask ci
cargo xtask docs
cargo xtask preflight    # full CI inside the devcontainer (gold standard for "ready to push")
cargo xtask perf-gates   # hardware-dependent perf tests (run on demand only)

just remains available as shorthand, but cargo xtask is the canonical command surface.

License

MIT OR Apache-2.0