graphos_engine/transaction/
mod.rs

1//! Transaction management with MVCC and Snapshot Isolation.
2//!
3//! # Isolation Level
4//!
5//! Graphos provides **Snapshot Isolation (SI)**, which offers strong consistency
6//! guarantees while maintaining high concurrency. Each transaction sees a consistent
7//! snapshot of the database as of its start time.
8//!
9//! ## Guarantees
10//!
11//! - **Read Consistency**: A transaction always reads the same values for the same
12//!   entities throughout its lifetime (repeatable reads).
13//! - **Write-Write Conflict Detection**: If two concurrent transactions write to the
14//!   same entity, the second to commit will be aborted.
15//! - **No Dirty Reads**: A transaction never sees uncommitted changes from other
16//!   transactions.
17//! - **No Lost Updates**: Write-write conflicts prevent the lost update anomaly.
18//!
19//! ## Limitations (Write Skew Anomaly)
20//!
21//! Snapshot Isolation does **not** provide full Serializable isolation. The "write skew"
22//! anomaly is possible when two transactions read overlapping data but write to
23//! disjoint sets:
24//!
25//! ```text
26//! Initial state: A = 50, B = 50, constraint: A + B >= 0
27//!
28//! T1: Read A, B → both 50
29//! T2: Read A, B → both 50
30//! T1: Write A = A - 100 = -50 (valid: -50 + 50 = 0)
31//! T2: Write B = B - 100 = -50 (valid: 50 + -50 = 0)
32//! T1: Commit ✓
33//! T2: Commit ✓ (no write-write conflict since T1 wrote A, T2 wrote B)
34//!
35//! Final state: A = -50, B = -50, constraint violated: A + B = -100 < 0
36//! ```
37//!
38//! ## Workarounds for Write Skew
39//!
40//! If your application has invariants that span multiple entities, consider:
41//!
42//! 1. **Promote reads to writes**: Add a dummy write to entities you read if you
43//!    need them to remain unchanged.
44//! 2. **Application-level locking**: Use external locks for critical sections.
45//! 3. **Constraint checking**: Validate invariants at commit time and retry if
46//!    violated.
47//!
48//! ## Epoch-Based Versioning
49//!
50//! Graphos uses epoch-based MVCC where:
51//! - Each commit advances the global epoch
52//! - Transactions read data visible at their start epoch
53//! - Version chains store multiple versions for concurrent access
54//! - Garbage collection removes versions no longer needed by active transactions
55//!
56//! # Example
57//!
58//! ```ignore
59//! let tx = session.begin_transaction()?;
60//!
61//! // All reads see a consistent snapshot
62//! let result = session.execute("MATCH (n:Person) RETURN n")?;
63//!
64//! // Writes are isolated until commit
65//! session.execute("CREATE (n:Person {name: 'Alice'})")?;
66//!
67//! // Commit may fail if write-write conflict detected
68//! session.commit()?;
69//! ```
70
71mod manager;
72mod mvcc;
73
74pub use manager::{EntityId, TransactionManager, TxInfo, TxState};
75pub use mvcc::{Version, VersionChain, VersionInfo};
graphos_engine/transaction/mod.rs

graphos_engine/transaction/
mod.rs
