@feltdb/core 0.4.12 → 0.4.14

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

@@ -0,0 +1,291 @@
+/// Cryptographic State Hashing
+///
+/// Produces SHA-256 hashes of canonical state serializations.
+/// Invariant: same state → same hash, different state → different hash (except negligible crypto collision)
+
+use serde_json::{json, Value};
+use std::collections::BTreeMap;
+
+/// Canonical state representation for hashing
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CanonicalState {
+    /// Records indexed by (collection, record_id)
+    pub records: BTreeMap<(String, String), Value>,
+}
+
+impl CanonicalState {
+    pub fn new() -> Self {
+        Self {
+            records: BTreeMap::new(),
+        }
+    }
+
+    /// Add or update a record
+    pub fn set_record(&mut self, collection: String, record_id: String, data: Value) {
+        self.records.insert((collection, record_id), data);
+    }
+
+    /// Get a record
+    pub fn get_record(&self, collection: &str, record_id: &str) -> Option<&Value> {
+        self.records.get(&(collection.to_string(), record_id.to_string()))
+    }
+
+    /// Canonical serialization for hashing (deterministic ordering)
+    pub fn to_canonical_json(&self) -> Value {
+        let mut state_map = serde_json::Map::new();
+
+        for ((collection, record_id), data) in &self.records {
+            let key = format!("{}:{}", collection, record_id);
+            state_map.insert(key, data.clone());
+        }
+
+        Value::Object(state_map)
+    }
+
+    /// Compute cryptographic hash of canonical state
+    pub fn hash(&self) -> StateHash {
+        let canonical = self.to_canonical_json();
+        let json_str = canonical.to_string();
+        StateHash::compute(&json_str)
+    }
+
+    /// Get the size of the canonical state (for metrics)
+    pub fn size_bytes(&self) -> usize {
+        self.to_canonical_json().to_string().len()
+    }
+}
+
+impl Default for CanonicalState {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// SHA-256 hash of state
+#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct StateHash(String);
+
+impl StateHash {
+    /// Compute hash from canonical JSON string
+    pub fn compute(canonical_json: &str) -> Self {
+        use sha2::{Digest, Sha256};
+
+        let mut hasher = Sha256::new();
+        hasher.update(canonical_json.as_bytes());
+        let result = hasher.finalize();
+
+        let hash_hex = format!("{:x}", result);
+        StateHash(hash_hex)
+    }
+
+    /// Create from string (for testing/recovery)
+    pub fn from_hex(hex: String) -> Self {
+        StateHash(hex)
+    }
+
+    /// Get hex representation
+    pub fn as_hex(&self) -> &str {
+        &self.0
+    }
+
+    /// Verify a canonical state produces this hash
+    pub fn verify(&self, canonical_json: &str) -> bool {
+        Self::compute(canonical_json) == *self
+    }
+}
+
+impl std::fmt::Display for StateHash {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_canonical_state_creation() {
+        let mut state = CanonicalState::new();
+        state.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"name": "Alice", "balance": 100}),
+        );
+
+        assert_eq!(state.records.len(), 1);
+        let record = state.get_record("users", "user1");
+        assert!(record.is_some());
+    }
+
+    #[test]
+    fn test_state_hash_deterministic() {
+        let mut state1 = CanonicalState::new();
+        state1.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"name": "Alice", "balance": 100}),
+        );
+
+        let mut state2 = CanonicalState::new();
+        state2.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"name": "Alice", "balance": 100}),
+        );
+
+        let hash1 = state1.hash();
+        let hash2 = state2.hash();
+
+        assert_eq!(hash1, hash2, "Same state must produce same hash");
+    }
+
+    #[test]
+    fn test_state_hash_collision_resistant() {
+        let mut state1 = CanonicalState::new();
+        state1.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"name": "Alice", "balance": 100}),
+        );
+
+        let mut state2 = CanonicalState::new();
+        state2.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"name": "Alice", "balance": 101}),
+        );
+
+        let hash1 = state1.hash();
+        let hash2 = state2.hash();
+
+        assert_ne!(hash1, hash2, "Different state must produce different hash");
+    }
+
+    #[test]
+    fn test_state_hash_field_order_invariant() {
+        let mut state1 = CanonicalState::new();
+        state1.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"name": "Alice", "balance": 100}),
+        );
+
+        let mut state2 = CanonicalState::new();
+        state2.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"balance": 100, "name": "Alice"}),
+        );
+
+        let hash1 = state1.hash();
+        let hash2 = state2.hash();
+
+        assert_eq!(hash1, hash2, "Field order must not affect hash");
+    }
+
+    #[test]
+    fn test_state_hash_multiple_records() {
+        let mut state = CanonicalState::new();
+        state.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"name": "Alice"}),
+        );
+        state.set_record(
+            "users".to_string(),
+            "user2".to_string(),
+            json!({"name": "Bob"}),
+        );
+        state.set_record(
+            "accounts".to_string(),
+            "acc1".to_string(),
+            json!({"balance": 1000}),
+        );
+
+        let hash = state.hash();
+
+        assert_eq!(hash.as_hex().len(), 64, "SHA-256 hex is 64 chars");
+        assert!(hash.verify(&state.to_canonical_json().to_string()));
+    }
+
+    #[test]
+    fn test_state_hash_record_update() {
+        let mut state = CanonicalState::new();
+        state.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"balance": 100}),
+        );
+
+        let hash_before = state.hash();
+
+        state.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"balance": 200}),
+        );
+
+        let hash_after = state.hash();
+
+        assert_ne!(hash_before, hash_after, "Hash changes when state updates");
+    }
+
+    #[test]
+    fn test_state_hash_empty_state() {
+        let state = CanonicalState::new();
+        let hash = state.hash();
+
+        assert_eq!(hash.as_hex().len(), 64);
+        assert!(hash.verify(&state.to_canonical_json().to_string()));
+    }
+
+    #[test]
+    fn test_state_hash_verify() {
+        let mut state = CanonicalState::new();
+        state.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"name": "Alice"}),
+        );
+
+        let hash = state.hash();
+        let canonical_json = state.to_canonical_json().to_string();
+
+        assert!(hash.verify(&canonical_json));
+    }
+
+    #[test]
+    fn test_canonical_json_ordering() {
+        let mut state1 = CanonicalState::new();
+        state1.set_record("a".to_string(), "1".to_string(), json!(1));
+        state1.set_record("c".to_string(), "3".to_string(), json!(3));
+        state1.set_record("b".to_string(), "2".to_string(), json!(2));
+
+        let mut state2 = CanonicalState::new();
+        state2.set_record("c".to_string(), "3".to_string(), json!(3));
+        state2.set_record("a".to_string(), "1".to_string(), json!(1));
+        state2.set_record("b".to_string(), "2".to_string(), json!(2));
+
+        let json1 = state1.to_canonical_json().to_string();
+        let json2 = state2.to_canonical_json().to_string();
+
+        assert_eq!(
+            json1, json2,
+            "Insertion order must not affect canonical JSON"
+        );
+    }
+
+    #[test]
+    fn test_state_size_bytes() {
+        let mut state = CanonicalState::new();
+        state.set_record(
+            "users".to_string(),
+            "user1".to_string(),
+            json!({"name": "Alice", "balance": 100}),
+        );
+
+        let size = state.size_bytes();
+        assert!(size > 0);
+    }
+}

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

@@ -0,0 +1,376 @@
+/// State Transition Store
+///
+/// Persistent storage of executed state transitions.
+/// Transitions are immutable once committed; this is the authoritative record of
+/// what state changes have occurred and in what order.
+
+use crate::transactions::{StateTransition, StateVersion};
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+
+/// Persisted state transition record
+#[derive(Clone, Debug)]
+pub struct StateTransitionRecord {
+    pub store_index: u64,
+    pub transition: StateTransition,
+    pub timestamp_ms: u64,
+}
+
+/// In-memory state transition store (for testing/development)
+/// For production, implement FileStateTransitionStore or DatabaseStateTransitionStore
+#[derive(Clone)]
+pub struct MemoryStateTransitionStore {
+    records: Arc<Mutex<Vec<StateTransitionRecord>>>,
+    by_transaction_id: Arc<Mutex<HashMap<String, u64>>>,
+    by_state_version: Arc<Mutex<HashMap<String, u64>>>,
+}
+
+impl MemoryStateTransitionStore {
+    pub fn new() -> Self {
+        Self {
+            records: Arc::new(Mutex::new(Vec::new())),
+            by_transaction_id: Arc::new(Mutex::new(HashMap::new())),
+            by_state_version: Arc::new(Mutex::new(HashMap::new())),
+        }
+    }
+
+    /// Record a committed state transition
+    /// Returns the store index assigned to this transition
+    pub fn record_transition(&self, transition: StateTransition) -> Result<u64, String> {
+        let mut records = self.records.lock().unwrap();
+        let mut by_txn = self.by_transaction_id.lock().unwrap();
+        let mut by_version = self.by_state_version.lock().unwrap();
+
+        // Ensure transition is successful before recording
+        if !transition.is_successful() {
+            return Err("Cannot record unsuccessful transition".to_string());
+        }
+
+        // Index by transaction_id if present
+        if let Some(ref txn_id) = transition.transaction_id {
+            if by_txn.contains_key(txn_id) {
+                return Err(format!("Transaction already recorded: {}", txn_id));
+            }
+        }
+
+        let store_index = records.len() as u64;
+        let timestamp_ms = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+
+        let record = StateTransitionRecord {
+            store_index,
+            transition: transition.clone(),
+            timestamp_ms,
+        };
+
+        // Index by transaction_id
+        if let Some(ref txn_id) = transition.transaction_id {
+            by_txn.insert(txn_id.clone(), store_index);
+        }
+
+        // Index by to_version (state_hash for quick lookup)
+        by_version.insert(transition.to_version.state_hash.clone(), store_index);
+
+        records.push(record);
+
+        Ok(store_index)
+    }
+
+    /// Get a transition by transaction ID
+    pub fn get_by_transaction_id(&self, transaction_id: &str) -> Option<StateTransitionRecord> {
+        let by_txn = self.by_transaction_id.lock().unwrap();
+        if let Some(&store_index) = by_txn.get(transaction_id) {
+            let records = self.records.lock().unwrap();
+            records.get(store_index as usize).cloned()
+        } else {
+            None
+        }
+    }
+
+    /// Get a transition by store index
+    pub fn get_by_index(&self, store_index: u64) -> Option<StateTransitionRecord> {
+        let records = self.records.lock().unwrap();
+        records.get(store_index as usize).cloned()
+    }
+
+    /// Get transitions in range [start_index, end_index)
+    pub fn get_range(&self, start_index: u64, end_index: u64) -> Vec<StateTransitionRecord> {
+        let records = self.records.lock().unwrap();
+        records
+            .iter()
+            .skip(start_index as usize)
+            .take((end_index - start_index) as usize)
+            .cloned()
+            .collect()
+    }
+
+    /// Find transitions that led from a specific state version
+    pub fn get_from_version(&self, state_hash: &str) -> Vec<StateTransitionRecord> {
+        let records = self.records.lock().unwrap();
+        records
+            .iter()
+            .filter(|r| r.transition.from_version.state_hash == state_hash)
+            .cloned()
+            .collect()
+    }
+
+    /// Find the transition that led to a specific state version
+    pub fn get_to_version(&self, state_hash: &str) -> Option<StateTransitionRecord> {
+        let by_version = self.by_state_version.lock().unwrap();
+        if let Some(&store_index) = by_version.get(state_hash) {
+            let records = self.records.lock().unwrap();
+            records.get(store_index as usize).cloned()
+        } else {
+            None
+        }
+    }
+
+    /// Get the current size of the store (number of transitions)
+    pub fn size(&self) -> u64 {
+        let records = self.records.lock().unwrap();
+        records.len() as u64
+    }
+
+    /// Iterate over all transitions in the store
+    pub fn iter(&self) -> Vec<StateTransitionRecord> {
+        let records = self.records.lock().unwrap();
+        records.clone()
+    }
+
+    /// Check if a transaction has been recorded
+    pub fn contains_transaction_id(&self, transaction_id: &str) -> bool {
+        let by_txn = self.by_transaction_id.lock().unwrap();
+        by_txn.contains_key(transaction_id)
+    }
+
+    /// Get the chain of transitions from a starting state to the current state
+    /// Returns transitions in order
+    pub fn get_transition_chain(&self, from_state_hash: &str) -> Vec<StateTransitionRecord> {
+        let records = self.records.lock().unwrap();
+        let mut chain = Vec::new();
+        let mut current_hash = from_state_hash.to_string();
+
+        for record in records.iter() {
+            if record.transition.from_version.state_hash == current_hash {
+                current_hash = record.transition.to_version.state_hash.clone();
+                chain.push(record.clone());
+            }
+        }
+
+        chain
+    }
+
+    /// Truncate the store at the given index (for recovery/compaction)
+    /// Keeps records with store_index < truncate_at
+    pub fn truncate(&self, truncate_at: u64) -> Result<(), String> {
+        let mut records = self.records.lock().unwrap();
+        let mut by_txn = self.by_transaction_id.lock().unwrap();
+        let mut by_version = self.by_state_version.lock().unwrap();
+
+        if truncate_at > records.len() as u64 {
+            return Err("Truncate index beyond store size".to_string());
+        }
+
+        let removed: Vec<_> = records.drain(truncate_at as usize..).collect();
+        for record in removed {
+            if let Some(ref txn_id) = record.transition.transaction_id {
+                by_txn.remove(txn_id);
+            }
+            by_version.remove(&record.transition.to_version.state_hash);
+        }
+
+        Ok(())
+    }
+}
+
+impl Default for MemoryStateTransitionStore {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::convergence::VectorClock;
+    use crate::transactions::{ConsistencyContract, OperationCommand, OperationId, Operation};
+    use std::collections::HashMap;
+
+    fn create_test_transition(from_hash: &str, to_hash: &str, txn_id: Option<&str>) -> StateTransition {
+        let mut from_vc = VectorClock::new();
+        from_vc.increment("node1");
+        let from_version = StateVersion::new(from_vc, from_hash.to_string());
+
+        let mut to_vc = VectorClock::new();
+        to_vc.increment("node1");
+        to_vc.increment("node1");
+        let to_version = StateVersion::new(to_vc, to_hash.to_string());
+
+        let mut op = Operation::new(
+            OperationId::new("node1".to_string(), 1),
+            from_version.clone(),
+            "Test".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(),
+        );
+
+        if let Some(txn_id_str) = txn_id {
+            op = op.with_transaction_id(txn_id_str.to_string());
+        }
+
+        StateTransition::new(
+            from_version,
+            vec![op],
+            to_version,
+            ConsistencyContract::causal(),
+        )
+    }
+
+    #[test]
+    fn test_record_and_retrieve() {
+        let store = MemoryStateTransitionStore::new();
+        let transition = create_test_transition("hash0", "hash1", Some("txn1"));
+
+        let idx = store.record_transition(transition).unwrap();
+
+        assert_eq!(idx, 0);
+        assert!(store.get_by_transaction_id("txn1").is_some());
+        assert_eq!(store.size(), 1);
+    }
+
+    #[test]
+    fn test_duplicate_transaction_rejection() {
+        let store = MemoryStateTransitionStore::new();
+        let transition1 = create_test_transition("hash0", "hash1", Some("txn1"));
+        let transition2 = create_test_transition("hash1", "hash2", Some("txn1"));
+
+        let _ = store.record_transition(transition1).unwrap();
+        let result = store.record_transition(transition2);
+
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("already recorded"));
+    }
+
+    #[test]
+    fn test_get_by_index() {
+        let store = MemoryStateTransitionStore::new();
+        let transition1 = create_test_transition("hash0", "hash1", Some("txn1"));
+        let transition2 = create_test_transition("hash1", "hash2", Some("txn2"));
+
+        store.record_transition(transition1).unwrap();
+        store.record_transition(transition2).unwrap();
+
+        let record1 = store.get_by_index(0).unwrap();
+        assert_eq!(record1.store_index, 0);
+
+        let record2 = store.get_by_index(1).unwrap();
+        assert_eq!(record2.store_index, 1);
+    }
+
+    #[test]
+    fn test_get_from_version() {
+        let store = MemoryStateTransitionStore::new();
+        let transition1 = create_test_transition("hash0", "hash1", Some("txn1"));
+        let transition2 = create_test_transition("hash0", "hash2", Some("txn2"));
+        let transition3 = create_test_transition("hash1", "hash3", Some("txn3"));
+
+        store.record_transition(transition1).unwrap();
+        store.record_transition(transition2).unwrap();
+        store.record_transition(transition3).unwrap();
+
+        let from_hash0 = store.get_from_version("hash0");
+        assert_eq!(from_hash0.len(), 2);
+
+        let from_hash1 = store.get_from_version("hash1");
+        assert_eq!(from_hash1.len(), 1);
+    }
+
+    #[test]
+    fn test_get_to_version() {
+        let store = MemoryStateTransitionStore::new();
+        let transition = create_test_transition("hash0", "hash1", Some("txn1"));
+
+        store.record_transition(transition).unwrap();
+
+        let record = store.get_to_version("hash1").unwrap();
+        assert_eq!(record.transition.to_version.state_hash, "hash1");
+    }
+
+    #[test]
+    fn test_get_transition_chain() {
+        let store = MemoryStateTransitionStore::new();
+        let t1 = create_test_transition("hash0", "hash1", Some("txn1"));
+        let t2 = create_test_transition("hash1", "hash2", Some("txn2"));
+        let t3 = create_test_transition("hash2", "hash3", Some("txn3"));
+
+        store.record_transition(t1).unwrap();
+        store.record_transition(t2).unwrap();
+        store.record_transition(t3).unwrap();
+
+        let chain = store.get_transition_chain("hash0");
+        assert_eq!(chain.len(), 3);
+        assert_eq!(chain[0].transition.to_version.state_hash, "hash1");
+        assert_eq!(chain[1].transition.to_version.state_hash, "hash2");
+        assert_eq!(chain[2].transition.to_version.state_hash, "hash3");
+    }
+
+    #[test]
+    fn test_contains_transaction_id() {
+        let store = MemoryStateTransitionStore::new();
+        let transition = create_test_transition("hash0", "hash1", Some("txn1"));
+
+        store.record_transition(transition).unwrap();
+
+        assert!(store.contains_transaction_id("txn1"));
+        assert!(!store.contains_transaction_id("txn999"));
+    }
+
+    #[test]
+    fn test_truncate() {
+        let store = MemoryStateTransitionStore::new();
+        let t1 = create_test_transition("hash0", "hash1", Some("txn1"));
+        let t2 = create_test_transition("hash1", "hash2", Some("txn2"));
+        let t3 = create_test_transition("hash2", "hash3", Some("txn3"));
+
+        store.record_transition(t1).unwrap();
+        store.record_transition(t2).unwrap();
+        store.record_transition(t3).unwrap();
+
+        assert_eq!(store.size(), 3);
+        store.truncate(2).unwrap();
+        assert_eq!(store.size(), 2);
+
+        assert!(store.contains_transaction_id("txn1"));
+        assert!(store.contains_transaction_id("txn2"));
+        assert!(!store.contains_transaction_id("txn3"));
+    }
+
+    #[test]
+    fn test_range_query() {
+        let store = MemoryStateTransitionStore::new();
+        for i in 0..5 {
+            let t = create_test_transition(
+                &format!("hash{}", i),
+                &format!("hash{}", i + 1),
+                Some(&format!("txn{}", i)),
+            );
+            store.record_transition(t).unwrap();
+        }
+
+        let range = store.get_range(1, 4);
+        assert_eq!(range.len(), 3);
+        assert_eq!(range[0].store_index, 1);
+        assert_eq!(range[2].store_index, 3);
+    }
+}