@feltdb/core 0.13.0 → 0.16.0

package/dist/create/server-source/crates/feltdb/src/operation_log.rs

@@ -1,349 +0,0 @@
-/// Operation Log Persistence
-///
-/// Append-only log storing all executed operations for durability, replay, and recovery.
-/// Operations are immutable once appended; the log is the authoritative source for
-/// what has been executed in the system.
-use crate::transactions::{Operation, OperationId, StateVersion};
-use std::collections::HashMap;
-use std::sync::{Arc, Mutex};
-
-/// Persisted operation log entry
-#[derive(Clone, Debug)]
-pub struct OperationLogEntry {
-    pub log_index: u64,
-    pub operation_id: OperationId,
-    pub operation: Operation,
-    pub timestamp_ms: u64,
-}
-
-/// In-memory operation log (for testing/development)
-/// For production, implement FileOperationLog or DatabaseOperationLog
-#[derive(Clone)]
-pub struct MemoryOperationLog {
-    entries: Arc<Mutex<Vec<OperationLogEntry>>>,
-    by_id: Arc<Mutex<HashMap<String, u64>>>,
-}
-
-impl MemoryOperationLog {
-    pub fn new() -> Self {
-        Self {
-            entries: Arc::new(Mutex::new(Vec::new())),
-            by_id: Arc::new(Mutex::new(HashMap::new())),
-        }
-    }
-
-    /// Append an operation to the log
-    /// Returns the log index assigned to this operation
-    pub fn append(&self, operation: Operation) -> Result<u64, String> {
-        let mut entries = self.entries.lock().unwrap();
-        let mut by_id = self.by_id.lock().unwrap();
-
-        let op_id_key = format!(
-            "{}:{}",
-            operation.operation_id.node_id, operation.operation_id.sequence
-        );
-
-        if by_id.contains_key(&op_id_key) {
-            return Err(format!("Operation already logged: {}", op_id_key));
-        }
-
-        let log_index = entries.len() as u64;
-        let timestamp_ms = std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .unwrap()
-            .as_millis() as u64;
-
-        let entry = OperationLogEntry {
-            log_index,
-            operation_id: operation.operation_id.clone(),
-            operation: operation.clone(),
-            timestamp_ms,
-        };
-
-        by_id.insert(op_id_key, log_index);
-        entries.push(entry);
-
-        Ok(log_index)
-    }
-
-    /// Get an operation by its ID
-    pub fn get_by_id(&self, operation_id: &OperationId) -> Option<OperationLogEntry> {
-        let by_id = self.by_id.lock().unwrap();
-        let op_id_key = format!("{}:{}", operation_id.node_id, operation_id.sequence);
-
-        if let Some(&log_index) = by_id.get(&op_id_key) {
-            let entries = self.entries.lock().unwrap();
-            entries.get(log_index as usize).cloned()
-        } else {
-            None
-        }
-    }
-
-    /// Get an operation by log index
-    pub fn get_by_index(&self, log_index: u64) -> Option<OperationLogEntry> {
-        let entries = self.entries.lock().unwrap();
-        entries.get(log_index as usize).cloned()
-    }
-
-    /// Get all operations in range [start_index, end_index)
-    pub fn get_range(&self, start_index: u64, end_index: u64) -> Vec<OperationLogEntry> {
-        let entries = self.entries.lock().unwrap();
-        entries
-            .iter()
-            .skip(start_index as usize)
-            .take((end_index - start_index) as usize)
-            .cloned()
-            .collect()
-    }
-
-    /// Get the current size of the log (number of entries)
-    pub fn size(&self) -> u64 {
-        let entries = self.entries.lock().unwrap();
-        entries.len() as u64
-    }
-
-    /// Iterate over all entries in the log
-    pub fn iter(&self) -> Vec<OperationLogEntry> {
-        let entries = self.entries.lock().unwrap();
-        entries.clone()
-    }
-
-    /// Check if an operation ID has been logged
-    pub fn contains_operation_id(&self, operation_id: &OperationId) -> bool {
-        let by_id = self.by_id.lock().unwrap();
-        let op_id_key = format!("{}:{}", operation_id.node_id, operation_id.sequence);
-        by_id.contains_key(&op_id_key)
-    }
-
-    /// Truncate the log at the given index (for recovery/compaction)
-    /// Keeps entries with log_index < truncate_at
-    pub fn truncate(&self, truncate_at: u64) -> Result<(), String> {
-        let mut entries = self.entries.lock().unwrap();
-        let mut by_id = self.by_id.lock().unwrap();
-
-        if truncate_at > entries.len() as u64 {
-            return Err("Truncate index beyond log size".to_string());
-        }
-
-        let removed: Vec<_> = entries.drain(truncate_at as usize..).collect();
-        for entry in removed {
-            let op_id_key = format!(
-                "{}:{}",
-                entry.operation_id.node_id, entry.operation_id.sequence
-            );
-            by_id.remove(&op_id_key);
-        }
-
-        Ok(())
-    }
-}
-
-impl Default for MemoryOperationLog {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::transactions::{OperationCommand, OperationId};
-    use std::collections::HashMap;
-
-    #[test]
-    fn test_append_and_retrieve() {
-        let log = MemoryOperationLog::new();
-        let mut vc = crate::convergence::VectorClock::new();
-        vc.increment("node1");
-        let version = StateVersion::new(vc, "hash0".to_string());
-
-        let op = Operation::new(
-            OperationId::new("node1".to_string(), 1),
-            version.clone(),
-            "Update".to_string(),
-            OperationCommand {
-                op_type: "UpdateField".to_string(),
-                collection: "test".to_string(),
-                record_id: "rec1".to_string(),
-                fields: {
-                    let mut m = HashMap::new();
-                    m.insert("field".to_string(), serde_json::json!("value"));
-                    m
-                },
-            },
-            "user".to_string(),
-        );
-
-        let op_id = op.operation_id.clone();
-        let idx = log.append(op).unwrap();
-
-        assert_eq!(idx, 0);
-        assert!(log.get_by_id(&op_id).is_some());
-        assert_eq!(log.size(), 1);
-    }
-
-    #[test]
-    fn test_duplicate_rejection() {
-        let log = MemoryOperationLog::new();
-        let mut vc = crate::convergence::VectorClock::new();
-        vc.increment("node1");
-        let version = StateVersion::new(vc, "hash0".to_string());
-
-        let op = Operation::new(
-            OperationId::new("node1".to_string(), 1),
-            version.clone(),
-            "Update".to_string(),
-            OperationCommand {
-                op_type: "UpdateField".to_string(),
-                collection: "test".to_string(),
-                record_id: "rec1".to_string(),
-                fields: {
-                    let mut m = HashMap::new();
-                    m.insert("field".to_string(), serde_json::json!("value"));
-                    m
-                },
-            },
-            "user".to_string(),
-        );
-
-        let _ = log.append(op.clone()).unwrap();
-        let result = log.append(op);
-
-        assert!(result.is_err());
-        assert!(result.unwrap_err().contains("already logged"));
-    }
-
-    #[test]
-    fn test_range_query() {
-        let log = MemoryOperationLog::new();
-        let mut vc = crate::convergence::VectorClock::new();
-        vc.increment("node1");
-        let version = StateVersion::new(vc, "hash0".to_string());
-
-        for i in 0..5 {
-            let op = Operation::new(
-                OperationId::new("node1".to_string(), i + 1),
-                version.clone(),
-                format!("Update{}", i),
-                OperationCommand {
-                    op_type: "UpdateField".to_string(),
-                    collection: "test".to_string(),
-                    record_id: format!("rec{}", i),
-                    fields: {
-                        let mut m = HashMap::new();
-                        m.insert("field".to_string(), serde_json::json!(i));
-                        m
-                    },
-                },
-                "user".to_string(),
-            );
-            let _ = log.append(op);
-        }
-
-        let range = log.get_range(1, 4);
-        assert_eq!(range.len(), 3);
-        assert_eq!(range[0].log_index, 1);
-        assert_eq!(range[2].log_index, 3);
-    }
-
-    #[test]
-    fn test_contains_operation_id() {
-        let log = MemoryOperationLog::new();
-        let mut vc = crate::convergence::VectorClock::new();
-        vc.increment("node1");
-        let version = StateVersion::new(vc, "hash0".to_string());
-
-        let op_id = OperationId::new("node1".to_string(), 1);
-        let op = Operation::new(
-            op_id.clone(),
-            version.clone(),
-            "Update".to_string(),
-            OperationCommand {
-                op_type: "UpdateField".to_string(),
-                collection: "test".to_string(),
-                record_id: "rec1".to_string(),
-                fields: {
-                    let mut m = HashMap::new();
-                    m.insert("field".to_string(), serde_json::json!("value"));
-                    m
-                },
-            },
-            "user".to_string(),
-        );
-
-        let _ = log.append(op);
-
-        assert!(log.contains_operation_id(&op_id));
-
-        let other_id = OperationId::new("node1".to_string(), 999);
-        assert!(!log.contains_operation_id(&other_id));
-    }
-
-    #[test]
-    fn test_truncate() {
-        let log = MemoryOperationLog::new();
-        let mut vc = crate::convergence::VectorClock::new();
-        vc.increment("node1");
-        let version = StateVersion::new(vc, "hash0".to_string());
-
-        for i in 0..5 {
-            let op = Operation::new(
-                OperationId::new("node1".to_string(), i + 1),
-                version.clone(),
-                format!("Update{}", i),
-                OperationCommand {
-                    op_type: "UpdateField".to_string(),
-                    collection: "test".to_string(),
-                    record_id: format!("rec{}", i),
-                    fields: {
-                        let mut m = HashMap::new();
-                        m.insert("field".to_string(), serde_json::json!(i));
-                        m
-                    },
-                },
-                "user".to_string(),
-            );
-            let _ = log.append(op);
-        }
-
-        assert_eq!(log.size(), 5);
-        let _ = log.truncate(3).unwrap();
-        assert_eq!(log.size(), 3);
-
-        let op_id = OperationId::new("node1".to_string(), 4);
-        assert!(!log.contains_operation_id(&op_id));
-    }
-
-    #[test]
-    fn test_iteration() {
-        let log = MemoryOperationLog::new();
-        let mut vc = crate::convergence::VectorClock::new();
-        vc.increment("node1");
-        let version = StateVersion::new(vc, "hash0".to_string());
-
-        for i in 0..3 {
-            let op = Operation::new(
-                OperationId::new("node1".to_string(), i + 1),
-                version.clone(),
-                format!("Update{}", i),
-                OperationCommand {
-                    op_type: "UpdateField".to_string(),
-                    collection: "test".to_string(),
-                    record_id: format!("rec{}", i),
-                    fields: {
-                        let mut m = HashMap::new();
-                        m.insert("field".to_string(), serde_json::json!(i));
-                        m
-                    },
-                },
-                "user".to_string(),
-            );
-            let _ = log.append(op);
-        }
-
-        let all = log.iter();
-        assert_eq!(all.len(), 3);
-        assert_eq!(all[0].log_index, 0);
-        assert_eq!(all[2].log_index, 2);
-    }
-}

package/dist/create/server-source/crates/feltdb/src/p1_application_atomicity.rs

@@ -1,332 +0,0 @@
-//! Production Gate P1 — application-facing atomicity.
-//!
-//! `apply_atomic_transaction` writes one fsynced transaction record, and
-//! `replay_log` restores every row of that record together. These tests hold
-//! the *application* store to the same all-or-nothing contract the transaction
-//! primitive guarantees, including the case that matters most in practice:
-//! the process died while the transaction record was being written.
-
-#[cfg(test)]
-mod tests {
-    use crate::{AtomicMutation, AtomicPrecondition, FeltDb};
-    use serde_json::json;
-    use std::io::{Seek, SeekFrom, Write};
-    use tempfile::TempDir;
-
-    fn mutation(capability: &str, key: &str, value: serde_json::Value) -> AtomicMutation {
-        AtomicMutation {
-            capability: capability.to_string(),
-            key: key.to_string(),
-            value: Some(value),
-        }
-    }
-
-    /// A cross-collection transaction, as an application would issue it.
-    fn user_order_audit() -> Vec<AtomicMutation> {
-        vec![
-            mutation("users", "users:u1", json!({ "id": "u1", "name": "Ada" })),
-            mutation(
-                "orders",
-                "orders:o1",
-                json!({ "id": "o1", "user": "u1", "total": 42 }),
-            ),
-            mutation(
-                "audit",
-                "audit:a1",
-                json!({ "id": "a1", "event": "order.created" }),
-            ),
-        ]
-    }
-
-    fn present(db: &FeltDb, key: &str) -> bool {
-        db.get_value(key).expect("read must succeed").is_some()
-    }
-
-    fn visible_count(db: &FeltDb) -> usize {
-        ["users:u1", "orders:o1", "audit:a1"]
-            .iter()
-            .filter(|key| present(db, key))
-            .count()
-    }
-
-    #[test]
-    fn a_cross_collection_transaction_commits_every_operation(
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        let dir = TempDir::new()?;
-        let path = dir.path().join("app.log");
-        let db = FeltDb::open(&path)?;
-
-        let commit = db.apply_atomic_transaction("tx-1", None, &[], &user_order_audit(), None)?;
-        assert_eq!(commit.rows.len(), 3);
-        assert!(!commit.duplicate);
-        assert_eq!(visible_count(&db), 3);
-        Ok(())
-    }
-
-    #[test]
-    fn a_cross_collection_transaction_survives_restart() -> Result<(), Box<dyn std::error::Error>> {
-        let dir = TempDir::new()?;
-        let path = dir.path().join("app.log");
-
-        {
-            let db = FeltDb::open(&path)?;
-            db.apply_atomic_transaction("tx-1", None, &[], &user_order_audit(), None)?;
-        }
-
-        let reopened = FeltDb::open(&path)?;
-        assert_eq!(
-            visible_count(&reopened),
-            3,
-            "every row must recover together"
-        );
-        Ok(())
-    }
-
-    #[test]
-    fn a_failed_precondition_leaves_no_operation_applied() -> Result<(), Box<dyn std::error::Error>>
-    {
-        let dir = TempDir::new()?;
-        let path = dir.path().join("app.log");
-        let db = FeltDb::open(&path)?;
-
-        // The middle key must already exist at a given version; it does not.
-        let preconditions = vec![AtomicPrecondition {
-            capability: "orders".to_string(),
-            key: "orders:o1".to_string(),
-            expected_version: Some(7),
-        }];
-
-        let outcome =
-            db.apply_atomic_transaction("tx-bad", None, &preconditions, &user_order_audit(), None);
-        assert!(
-            outcome.is_err(),
-            "a failed precondition must reject the transaction"
-        );
-
-        assert_eq!(visible_count(&db), 0, "no operation may be applied");
-        drop(db);
-
-        let reopened = FeltDb::open(&path)?;
-        assert_eq!(visible_count(&reopened), 0, "and nothing may be durable");
-        Ok(())
-    }
-
-    #[test]
-    fn replaying_a_transaction_id_is_idempotent() -> Result<(), Box<dyn std::error::Error>> {
-        let dir = TempDir::new()?;
-        let path = dir.path().join("app.log");
-        let db = FeltDb::open(&path)?;
-
-        let first = db.apply_atomic_transaction("tx-1", None, &[], &user_order_audit(), None)?;
-        assert!(!first.duplicate);
-        let second = db.apply_atomic_transaction("tx-1", None, &[], &user_order_audit(), None)?;
-        assert!(
-            second.duplicate,
-            "the same transaction id must not apply twice"
-        );
-        assert_eq!(visible_count(&db), 3);
-        Ok(())
-    }
-
-    #[test]
-    fn transaction_identity_survives_restart() -> Result<(), Box<dyn std::error::Error>> {
-        let dir = TempDir::new()?;
-        let path = dir.path().join("app.log");
-
-        {
-            let db = FeltDb::open(&path)?;
-            db.apply_atomic_transaction("tx-stable", None, &[], &user_order_audit(), None)?;
-        }
-
-        let reopened = FeltDb::open(&path)?;
-        let replayed =
-            reopened.apply_atomic_transaction("tx-stable", None, &[], &user_order_audit(), None)?;
-        assert!(
-            replayed.duplicate,
-            "identity must be restored so redelivery stays idempotent"
-        );
-        assert_eq!(visible_count(&reopened), 3);
-        Ok(())
-    }
-
-    /// The case that matters in production: the process died while the
-    /// transaction record was being written.
-    ///
-    /// The half-written record is not a committed transaction, so recovery must
-    /// discard it and open the store with the previously committed history
-    /// intact. Refusing to open at all would turn a normal crash into an
-    /// outage.
-    #[test]
-    fn a_torn_transaction_record_is_discarded_and_the_store_still_opens(
-    ) -> Result<(), Box<dyn std::error::Error>> {
-        let dir = TempDir::new()?;
-        let path = dir.path().join("app.log");
-
-        {
-            let db = FeltDb::open(&path)?;
-            db.apply_atomic_transaction("tx-1", None, &[], &user_order_audit(), None)?;
-        }
-
-        // Append a partial transaction record with no terminating newline,
-        // exactly as a crash mid-write would leave behind.
-        let complete = std::fs::read_to_string(&path)?;
-        let mut file = std::fs::OpenOptions::new().append(true).open(&path)?;
-        let torn = &complete[..complete.len() / 2];
-        file.write_all(torn.as_bytes())?;
-        file.flush()?;
-        drop(file);
-
-        let recovered = FeltDb::open(&path).map_err(|error| {
-            format!("a torn tail must not stop the store from opening: {error}")
-        })?;
-        assert_eq!(
-            visible_count(&recovered),
-            3,
-            "committed history must survive"
-        );
-        Ok(())
-    }
-
-    /// A transaction that was still being written never committed, so none of
-    /// its rows may appear.
-    #[test]
-    fn a_transaction_torn_mid_write_applies_nothing() -> Result<(), Box<dyn std::error::Error>> {
-        let dir = TempDir::new()?;
-        let path = dir.path().join("app.log");
-
-        // Write a complete transaction, then a partial second one.
-        {
-            let db = FeltDb::open(&path)?;
-            db.apply_atomic_transaction("tx-1", None, &[], &user_order_audit(), None)?;
-        }
-        let after_first = std::fs::read_to_string(&path)?;
-
-        {
-            let db = FeltDb::open(&path)?;
-            db.apply_atomic_transaction(
-                "tx-2",
-                None,
-                &[],
-                &[mutation(
-                    "users",
-                    "users:u2",
-                    json!({ "id": "u2", "name": "Grace" }),
-                )],
-                None,
-            )?;
-        }
-
-        // Truncate the second record part-way through.
-        let full = std::fs::read_to_string(&path)?;
-        let second = &full[after_first.len()..];
-        let keep = after_first.len() + second.len() / 2;
-        let file = std::fs::OpenOptions::new().write(true).open(&path)?;
-        file.set_len(keep as u64)?;
-        file.sync_all()?;
-        drop(file);
-
-        let recovered = FeltDb::open(&path)?;
-        assert_eq!(
-            visible_count(&recovered),
-            3,
-            "the committed transaction survives"
-        );
-        assert!(
-            !present(&recovered, "users:u2"),
-            "a torn transaction must apply nothing"
-        );
-        Ok(())
-    }
-
-    /// Damage before the end of the log is corruption, not an interrupted
-    /// write, and recovery must refuse rather than silently drop history.
-    #[test]
-    fn interior_corruption_is_still_refused() -> Result<(), Box<dyn std::error::Error>> {
-        let dir = TempDir::new()?;
-        let path = dir.path().join("app.log");
-
-        {
-            let db = FeltDb::open(&path)?;
-            db.apply_atomic_transaction("tx-1", None, &[], &user_order_audit(), None)?;
-            db.apply_atomic_transaction(
-                "tx-2",
-                None,
-                &[],
-                &[mutation("users", "users:u2", json!({ "id": "u2" }))],
-                None,
-            )?;
-        }
-
-        let mut file = std::fs::OpenOptions::new().write(true).open(&path)?;
-        file.seek(SeekFrom::Start(30))?;
-        file.write_all(b"@@@@@@@@")?;
-        file.sync_all()?;
-        drop(file);
-
-        assert!(
-            FeltDb::open(&path).is_err(),
-            "corruption before the end of the log must not be silently discarded"
-        );
-        Ok(())
-    }
-
-    #[test]
-    fn single_operation_writes_remain_compatible() -> Result<(), Box<dyn std::error::Error>> {
-        let dir = TempDir::new()?;
-        let path = dir.path().join("app.log");
-
-        {
-            let db = FeltDb::open(&path)?;
-            // The existing single-operation API, unchanged.
-            db.insert("users:solo", json!({ "id": "solo", "name": "Alan" }))?;
-            // Mixed with a transaction.
-            db.apply_atomic_transaction("tx-1", None, &[], &user_order_audit(), None)?;
-            db.insert("users:solo2", json!({ "id": "solo2" }))?;
-        }
-
-        let reopened = FeltDb::open(&path)?;
-        assert!(
-            present(&reopened, "users:solo"),
-            "single writes must still recover"
-        );
-        assert!(present(&reopened, "users:solo2"));
-        assert_eq!(
-            visible_count(&reopened),
-            3,
-            "transaction rows recover alongside them"
-        );
-        Ok(())
-    }
-
-    #[test]
-    fn deletes_participate_in_a_transaction() -> Result<(), Box<dyn std::error::Error>> {
-        let dir = TempDir::new()?;
-        let path = dir.path().join("app.log");
-
-        {
-            let db = FeltDb::open(&path)?;
-            db.apply_atomic_transaction("seed", None, &[], &user_order_audit(), None)?;
-            // Delete one row and create another, atomically.
-            db.apply_atomic_transaction(
-                "move",
-                None,
-                &[],
-                &[
-                    AtomicMutation {
-                        capability: "orders".to_string(),
-                        key: "orders:o1".to_string(),
-                        value: None,
-                    },
-                    mutation("orders", "orders:o2", json!({ "id": "o2", "total": 42 })),
-                ],
-                None,
-            )?;
-        }
-
-        let reopened = FeltDb::open(&path)?;
-        assert!(!present(&reopened, "orders:o1"), "the delete must persist");
-        assert!(present(&reopened, "orders:o2"), "the insert must persist");
-        assert!(present(&reopened, "users:u1"), "untouched rows are kept");
-        Ok(())
-    }
-}