Crate batpak 

Sync-first event sourcing for Rust: append-only segments, causal metadata, caller-defined gates, and typed projections.

Batpak stores immutable events in segment files, tracks causation metadata, evaluates caller-defined gates before commit, and rebuilds typed projections through a synchronous API that does not require an async runtime.

Use it when you need a tamper-evident, replayable record of what happened: every event is hash-bound to its per-entity ancestor with Blake3, every accepted write returns a verifiable (optionally Ed25519-signed) receipt, and projections are derived views rebuilt from the log by construction.

Most callers start with the eight-job path: open a Store, append typed events, page commit order with Store::query_entries_after, point-read with Store::get, walk bounded hash-chain ancestry with Store::walk_ancestors, verify receipts with Store::verify_append_receipt_detailed, project derived state with Store::project, then close the store. Gates and Pipeline are advanced batteries for caller-owned evaluation before commit.

use batpak::prelude::*;

#[derive(serde::Serialize, serde::Deserialize, EventPayload)]
#[batpak(category = 0xF, type_id = 1)]
struct PlayerMoved {
    x: i32,
    y: i32,
}

let dir = tempfile::tempdir()?;
let store = Store::open(StoreConfig::new(dir.path()))?;
let coord = Coordinate::new("player:alice", "room:dungeon")?;

let receipt = store.append_typed(&coord, &PlayerMoved { x: 10, y: 20 })?;
let stored = store.get(receipt.event_id)?;

assert_eq!(stored.coordinate.entity(), "player:alice");
assert_eq!(stored.event.header.event_id, receipt.event_id);

Reading order:

1. coordinate: Identify entities and scopes.
2. event: Structure typed payloads and projection inputs.
3. store: Persist, page, point-read, walk, verify, and project.
4. guard and pipeline: Add caller-defined write evaluation.
5. artifact, registry, transition, reservation, and schema: Advanced substrate batteries for envelopes, ledgers, transition evidence, reservation mechanics, and drift reports.

Re-exports

pub use crate::encoding as canonical;

pub use crate::event::EventPayload;

pub use crate::event::EventSourced;

pub use crate::event::MultiReactive;

Modules

artifact

Crate-level substrate: canonical artifact body digest vs envelope digest. Canonical artifact envelope: digest of the serializable body vs digest of the envelope (signatures, attestations, diagnostics).

coordinate

Entity and scope addressing for events.

encoding

Stable named-field MessagePack encoding helpers. Stable batpak encoding helpers.

event

Event types, headers, and sourcing traits.

guard

Caller-defined gate evaluation before event commitment.

id

UUID v7 identifier generation.

outcome

Result-like type for pipeline operations.

pipeline

Propose-evaluate-commit workflow.

prelude

Common re-exports for convenient use. Beginner-oriented imports for the canonical BatPAK store path.

registry

Crate-level substrate: generic signed registry rows composing artifact envelopes. Batpak Substrate Closure attested registry row: stable row identity, canonical row body digest, lifecycle and supersession pointers, drift evidence, and verification reports that compose crate::artifact::CanonicalArtifactEnvelope without importing crate::store.

reservation

Crate-level substrate: generic reservation ledger mechanics. Batpak Substrate Closure reservation ledger: dimensionless units, opaque subject_ref, closed structural states, explicit transition operations, deterministic findings, and reconciliation buckets. This module does not import crate::store and encodes no payment, inventory, capability, or workflow policy.

schema

Deterministic schema/fixture snapshot drift evidence. Deterministic Batpak Substrate Closure schema/fixture snapshot drift evidence.

store

Persistent event storage and querying.

transition

Crate-level substrate: generic state transition events and reports. Batpak Substrate Closure state transition evidence: opaque machine/subject identifiers, prior and successor state discriminants, transition identity, sorted cause references, optional ordering metadata, and deterministic reports with structural findings only.

typestate

Compile-time state machine transitions.

wire

Module declarations in DEPENDENCY ORDER: wire → coordinate → outcome → event → guard → pipeline → store → typestate → id → prelude Serde serialization helpers.

Macros

define_entity_id

define_entity_id!: Layer 1+ macro. Uses generate_v7_id() helper. Downstream crates do NOT need uuid as a direct dependency.

define_state_machine

define_state_machine!: generates a sealed marker trait + zero-sized state structs.

define_typestate

define_typestate!: generates a PhantomData wrapper for typed state machines.

Derive Macros

EventPayload

Derives batpak::event::EventPayload for a named-field struct.

EventSourced

Derives batpak::event::EventSourced for a named-field struct.

MultiEventReactor

Derives batpak::event::MultiReactive<Input> for a named-field struct, for use with Store::react_loop_multi (JSON) or Store::react_loop_multi_raw (msgpack).