batpak 0.3.0

Event sourcing with causal graphs and policy gates. Sync API, zero async.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

#![warn(missing_docs)]
// Intentional impossible-feature guards (async-store, sha256, exponential-backoff) use
// cfg attributes for features that are NOT declared in Cargo.toml. Suppress the
// unexpected_cfgs warning at crate level because item-level #[allow] is unreliable
// for cfg checks on some toolchain versions.
#![allow(unexpected_cfgs)]
// cast_possible_truncation and cast_sign_loss are enforced via [lints.clippy] in Cargo.toml.
// Each intentional cast has an inline #[allow] with a justification comment.
//! batpak: Event Sourcing Runtime with DAG Causation Tracking.
//!
//! Batpak provides a complete event sourcing platform with:
//! - **Event Sourcing**: Immutable event log with hash chain integrity
//! - **DAG Causation**: Tracks causation relationships between events
//! - **Gate Evaluation**: Pluggable policy enforcement before event commitment
//! - **Persistent Storage**: Segment-based append-only store with fast querying
//!
//! The core pattern: acquire a [`Proposal`](crate::pipeline::Proposal), evaluate it through
//! [`Gate`](crate::guard::Gate) instances, then [`commit`](crate::pipeline::Pipeline::commit) to
//! the [`Store`](crate::store::Store).
//!
//! ```no_run
//! use batpak::prelude::*;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let store = Store::open(StoreConfig::new("./my-store"))?;
//! let gates: GateSet<()> = GateSet::new();
//! let pipeline = Pipeline::new(gates);
//!
//! let coord = Coordinate::new("entity:1", "scope:test")?;
//! let kind = EventKind::custom(0xF, 1);
//! let payload = serde_json::json!({"hello": "world"});
//!
//! let proposal = Proposal::new(payload.clone());
//! let receipt = pipeline.evaluate(&(), proposal)?;
//! let committed = pipeline.commit(receipt, |p| -> Result<_, StoreError> {
//!     let r = store.append(&coord, kind, &p)?;
//!     Ok(Committed { payload: p, event_id: r.event_id, sequence: r.sequence, hash: [0u8; 32] })
//! })?;
//! # Ok(())
//! # }
//! ```
//!
//! **Reading order:**
//! 1. [`coordinate`]: Identify entities and scopes
//! 2. [`event`]: Structure your events
//! 3. [`guard`]: Build policy gates
//! 4. [`pipeline`]: Propose and commit
//! 5. [`store`]: Persist and query

/// Entity and scope addressing for events.
pub mod coordinate;
/// Event types, headers, and sourcing traits.
pub mod event;
/// Policy gate evaluation before event commitment.
pub mod guard;
/// UUID v7 identifier generation.
pub mod id;
/// Result-like type for pipeline operations.
pub mod outcome;
/// Propose-evaluate-commit workflow.
pub mod pipeline;
/// Common re-exports for convenient use.
pub mod prelude;
/// Persistent event storage and querying.
pub mod store;
/// Compile-time state machine transitions.
pub mod typestate;
/// Module declarations in DEPENDENCY ORDER:
/// wire → coordinate → outcome → event → guard → pipeline → store → typestate → id → prelude
/// [SPEC:src/lib.rs — Module declarations in DEPENDENCY ORDER]
/// Serde serialization helpers.
pub mod wire; // serde helpers — no deps, must come first

/// compile_error guards for impossible configurations:
// async-store is not a declared feature — suppress cfg warning for this guard
#[allow(unexpected_cfgs)]
#[cfg(feature = "async-store")]
compile_error!(
    "INVARIANT 2: batpak does not have an async Store API. \
     Async callers use spawn_blocking() or flume recv_async(). \
     See: src/store/subscription.rs for the async pattern."
);

// sha256 is not a declared feature — suppress cfg warning for this guard
#[allow(unexpected_cfgs)]
#[cfg(feature = "sha256")]
compile_error!(
    "INVARIANT 5: blake3 is the only hash. No HashAlgorithm enum. \
     One function: compute_hash(bytes) -> [u8; 32], behind feature = blake3."
);