@feltdb/core 0.4.12 → 0.4.13

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

@@ -0,0 +1,251 @@
+use crate::now_ms;
+/// Operation log module for durable append-only mutations
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+
+/// A durable operation that can be appended to the log
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Operation {
+    /// Unique operation ID (monotonically increasing)
+    pub op_id: u64,
+    /// Instance ID - unique identifier for the FeltDB instance that created this operation
+    pub instance_id: String,
+    /// Sequence number - monotonically increasing sequence per instance
+    pub sequence: u64,
+    /// Type of operation (insert, update, delete)
+    pub op_type: OperationType,
+    /// The key being operated on (e.g., "users:123")
+    pub key: String,
+    /// The value (for insert/update operations)
+    pub value: Option<Value>,
+    /// Timestamp in milliseconds since UNIX epoch
+    pub timestamp_ms: u128,
+    /// The data type being operated on
+    pub rust_type: String,
+    /// Capability/namespace
+    pub capability: String,
+    /// Content hash - deterministic hash of the operation's content for deduplication
+    pub content_hash: String,
+    /// Vector clock for causal tracking (optional for backward compatibility)
+    #[serde(default)]
+    pub vector_clock: Option<std::collections::HashMap<String, u64>>,
+}
+
+/// Types of mutations that become durable operations
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub enum OperationType {
+    /// Insert a new record
+    Insert,
+    /// Update an existing record
+    Update,
+    /// Delete an existing record
+    Delete,
+}
+
+impl Operation {
+    /// Create a new insert operation
+    pub fn insert(
+        op_id: u64,
+        instance_id: String,
+        sequence: u64,
+        key: String,
+        value: Value,
+        rust_type: String,
+        capability: String,
+    ) -> Self {
+        let op = Self {
+            op_id,
+            instance_id,
+            sequence,
+            op_type: OperationType::Insert,
+            key,
+            value: Some(value),
+            timestamp_ms: now_ms(),
+            rust_type,
+            capability,
+            content_hash: String::new(), // Will be computed below
+            vector_clock: None,
+        };
+        let mut result = op;
+        result.content_hash = result.compute_content_hash();
+        result
+    }
+
+    /// Create a new update operation
+    pub fn update(
+        op_id: u64,
+        instance_id: String,
+        sequence: u64,
+        key: String,
+        value: Value,
+        rust_type: String,
+        capability: String,
+    ) -> Self {
+        let op = Self {
+            op_id,
+            instance_id,
+            sequence,
+            op_type: OperationType::Update,
+            key,
+            value: Some(value),
+            timestamp_ms: now_ms(),
+            rust_type,
+            capability,
+            content_hash: String::new(), // Will be computed below
+            vector_clock: None,
+        };
+        let mut result = op;
+        result.content_hash = result.compute_content_hash();
+        result
+    }
+
+    /// Create a new delete operation
+    pub fn delete(
+        op_id: u64,
+        instance_id: String,
+        sequence: u64,
+        key: String,
+        rust_type: String,
+        capability: String,
+    ) -> Self {
+        let op = Self {
+            op_id,
+            instance_id,
+            sequence,
+            op_type: OperationType::Delete,
+            key,
+            value: None,
+            timestamp_ms: now_ms(),
+            rust_type,
+            capability,
+            content_hash: String::new(), // Will be computed below
+            vector_clock: None,
+        };
+        let mut result = op;
+        result.content_hash = result.compute_content_hash();
+        result
+    }
+
+    /// Compute deterministic content hash for this operation
+    /// This is used for deduplication across peers
+    pub fn compute_content_hash(&self) -> String {
+        let mut hasher = Sha256::new();
+
+        // Hash the operation type
+        hasher.update(format!("{:?}", self.op_type).as_bytes());
+
+        // Hash the key
+        hasher.update(self.key.as_bytes());
+
+        // Hash the value if present
+        if let Some(val) = &self.value {
+            hasher.update(val.to_string().as_bytes());
+        }
+
+        // Hash the rust type
+        hasher.update(self.rust_type.as_bytes());
+
+        // Hash the capability
+        hasher.update(self.capability.as_bytes());
+
+        let result = hasher.finalize();
+        format!("{:x}", result)
+    }
+
+    /// Set the vector clock for this operation
+    pub fn with_vector_clock(
+        mut self,
+        vector_clock: std::collections::HashMap<String, u64>,
+    ) -> Self {
+        self.vector_clock = Some(vector_clock);
+        self
+    }
+
+    /// Get the vector clock for this operation
+    pub fn get_vector_clock(&self) -> Option<&std::collections::HashMap<String, u64>> {
+        self.vector_clock.as_ref()
+    }
+}
+
+/// Mutation ordering specification for FeltDB
+/// This defines the order in which mutation side effects occur
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationOrder {
+    /// Conservative: Apply locally first, then persist in background
+    /// Mutation → Validate → Apply state transition → Emit diff → Persist
+    /// Good for: Interactive feel, optimistic updates
+    ApplyFirst,
+
+    /// Durable: Persist first, then apply and emit
+    /// Mutation → Validate → Persist → Apply state transition → Emit diff
+    /// Good for: Durability guarantee, no data loss
+    PersistFirst,
+}
+
+/// The default mutation ordering for FeltDB
+/// We choose PersistFirst to ensure durability guarantees
+pub const DEFAULT_MUTATION_ORDER: MutationOrder = MutationOrder::PersistFirst;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn operation_insert_creates_insert_op() {
+        let op = Operation::insert(
+            1,
+            "inst1".to_string(),
+            1,
+            "users:123".to_string(),
+            serde_json::json!({"name": "Alice"}),
+            "User".to_string(),
+            "users".to_string(),
+        );
+
+        assert_eq!(op.op_id, 1);
+        assert_eq!(op.instance_id, "inst1");
+        assert_eq!(op.sequence, 1);
+        assert_eq!(op.op_type, OperationType::Insert);
+        assert_eq!(op.key, "users:123");
+        assert!(op.value.is_some());
+    }
+
+    #[test]
+    fn operation_delete_has_no_value() {
+        let op = Operation::delete(
+            2,
+            "inst1".to_string(),
+            2,
+            "users:456".to_string(),
+            "User".to_string(),
+            "users".to_string(),
+        );
+
+        assert_eq!(op.op_type, OperationType::Delete);
+        assert!(op.value.is_none());
+        assert_eq!(op.instance_id, "inst1");
+        assert_eq!(op.sequence, 2);
+    }
+
+    #[test]
+    fn operations_are_serializable() {
+        let op = Operation::update(
+            1,
+            "inst1".to_string(),
+            1,
+            "users:789".to_string(),
+            serde_json::json!({"status": "active"}),
+            "User".to_string(),
+            "users".to_string(),
+        );
+
+        let json = serde_json::to_string(&op).expect("serialize");
+        let deserialized: Operation = serde_json::from_str(&json).expect("deserialize");
+
+        assert_eq!(deserialized.op_id, op.op_id);
+        assert_eq!(deserialized.op_type, op.op_type);
+        assert_eq!(deserialized.instance_id, op.instance_id);
+        assert_eq!(deserialized.sequence, op.sequence);
+    }
+}

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

@@ -0,0 +1,438 @@
+/// Operation Algebra Registry
+///
+/// Declares the convergence semantics and merge algebra for every
+/// operation type in FeltDB. Gate 2 requires every replicated operation
+/// to declare how it converges under concurrent application.
+///
+/// This registry is the foundation of operation-specific CRDT semantics.
+
+use std::collections::HashMap;
+
+/// Conflict classification for an operation
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub enum ConflictType {
+    /// Commutative: can be applied in any order
+    Commutative,
+    /// Register: LWW (last-write-wins by timestamp)
+    Register,
+    /// Set CRDT: union on add, tombstone on remove
+    SetCRDT,
+    /// Counter CRDT: additive
+    CounterCRDT,
+    /// Custom: user-provided merge semantics
+    Custom(String),
+    /// Transaction: requires precondition/consensus
+    Transaction,
+}
+
+/// How this operation converges with concurrent applications
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ConvergenceSemantic {
+    /// All orderings produce identical result
+    StrictlyCommutative,
+    /// Deterministic merge function resolves concurrent versions
+    DeterministicMerge,
+    /// Requires consensus/total ordering
+    ConsensusRequired,
+}
+
+/// Declared convergence algebra for an operation type
+#[derive(Clone, Debug)]
+pub struct OperationAlgebra {
+    pub operation_type: String,
+    pub read_set_bound: String,                // "single_record", "multiple_records", etc
+    pub write_set_bound: String,               // "single_record", "multiple_records", etc
+    pub conflict_type: ConflictType,
+    pub convergence_semantic: ConvergenceSemantic,
+    pub merge_function_description: String,
+    pub commutativity_proof: Option<String>,   // Reference to commutative algebra proof
+    pub determinism_proof: Option<String>,     // Reference to determinism proof
+}
+
+impl OperationAlgebra {
+    pub fn new(
+        operation_type: &str,
+        read_set_bound: &str,
+        write_set_bound: &str,
+        conflict_type: ConflictType,
+        convergence_semantic: ConvergenceSemantic,
+        merge_function_description: &str,
+    ) -> Self {
+        Self {
+            operation_type: operation_type.to_string(),
+            read_set_bound: read_set_bound.to_string(),
+            write_set_bound: write_set_bound.to_string(),
+            conflict_type,
+            convergence_semantic,
+            merge_function_description: merge_function_description.to_string(),
+            commutativity_proof: None,
+            determinism_proof: None,
+        }
+    }
+
+    pub fn with_proofs(mut self, commutativity: Option<String>, determinism: Option<String>) -> Self {
+        self.commutativity_proof = commutativity;
+        self.determinism_proof = determinism;
+        self
+    }
+
+    pub fn is_commutative(&self) -> bool {
+        self.convergence_semantic == ConvergenceSemantic::StrictlyCommutative
+    }
+
+    pub fn is_deterministic(&self) -> bool {
+        self.convergence_semantic != ConvergenceSemantic::ConsensusRequired
+    }
+}
+
+/// Registry of all operation types and their convergence algebra
+pub struct OperationAlgebraRegistry {
+    algebras: HashMap<String, OperationAlgebra>,
+}
+
+impl OperationAlgebraRegistry {
+    /// Create new registry with standard operations
+    pub fn new() -> Self {
+        let mut registry = Self {
+            algebras: HashMap::new(),
+        };
+        registry.register_standard_operations();
+        registry
+    }
+
+    /// Register all standard FeltDB operation types
+    fn register_standard_operations(&mut self) {
+        // SetField: Last-Write-Wins register
+        self.register(
+            OperationAlgebra::new(
+                "SetField",
+                "single_record.field",
+                "single_record.field",
+                ConflictType::Register,
+                ConvergenceSemantic::DeterministicMerge,
+                "LWW: max(timestamp, value)",
+            )
+            .with_proofs(
+                None,
+                Some("Deterministic: higher timestamp wins deterministically".to_string()),
+            ),
+        );
+
+        // Increment: Counter CRDT (commutative addition)
+        self.register(
+            OperationAlgebra::new(
+                "Increment",
+                "single_record.field",
+                "single_record.field",
+                ConflictType::CounterCRDT,
+                ConvergenceSemantic::StrictlyCommutative,
+                "Counter CRDT: sum(all_increments)",
+            )
+            .with_proofs(
+                Some("Commutative: addition commutes over integers".to_string()),
+                Some("Deterministic: sum is deterministic".to_string()),
+            ),
+        );
+
+        // AddToSet: Set CRDT (union on add)
+        self.register(
+            OperationAlgebra::new(
+                "AddToSet",
+                "single_record.set",
+                "single_record.set",
+                ConflictType::SetCRDT,
+                ConvergenceSemantic::StrictlyCommutative,
+                "Set CRDT: union(all_adds)",
+            )
+            .with_proofs(
+                Some("Commutative: set union is commutative".to_string()),
+                Some("Deterministic: union is deterministic".to_string()),
+            ),
+        );
+
+        // RemoveFromSet: Set CRDT (tombstone semantics)
+        self.register(
+            OperationAlgebra::new(
+                "RemoveFromSet",
+                "single_record.set",
+                "single_record.set",
+                ConflictType::SetCRDT,
+                ConvergenceSemantic::DeterministicMerge,
+                "Set CRDT: (set - tombstones) ∪ (tombstones resolved by causal ordering)",
+            )
+            .with_proofs(
+                None,
+                Some("Deterministic: tombstone semantics with causal ordering".to_string()),
+            ),
+        );
+
+        // Create: Conflict detection (earliest timestamp wins deterministically)
+        self.register(
+            OperationAlgebra::new(
+                "Create",
+                "none",
+                "single_record",
+                ConflictType::Register,
+                ConvergenceSemantic::DeterministicMerge,
+                "Deterministic: min(timestamp, id) for create conflicts",
+            )
+            .with_proofs(
+                None,
+                Some("Deterministic: total order via (timestamp, node_id)".to_string()),
+            ),
+        );
+
+        // Delete: Tombstone semantics (deterministic)
+        self.register(
+            OperationAlgebra::new(
+                "Delete",
+                "single_record",
+                "single_record",
+                ConflictType::Register,
+                ConvergenceSemantic::DeterministicMerge,
+                "Tombstone: delete_timestamp determines visibility",
+            )
+            .with_proofs(
+                None,
+                Some("Deterministic: tombstone ordering via timestamp and node_id".to_string()),
+            ),
+        );
+
+        // Transfer: Business invariant (requires consensus/transaction)
+        self.register(
+            OperationAlgebra::new(
+                "Transfer",
+                "source_record,dest_record",
+                "source_record,dest_record",
+                ConflictType::Transaction,
+                ConvergenceSemantic::ConsensusRequired,
+                "Transaction: requires precondition validation and consensus ordering",
+            )
+            .with_proofs(
+                None,
+                Some("Consensus: total ordering via distributed log".to_string()),
+            ),
+        );
+
+        // Append: Sequence ordering (vector clock ordering)
+        self.register(
+            OperationAlgebra::new(
+                "Append",
+                "single_sequence",
+                "single_sequence",
+                ConflictType::Custom("SequenceOrdering".to_string()),
+                ConvergenceSemantic::DeterministicMerge,
+                "Sequence: vector clock establishes total order",
+            )
+            .with_proofs(
+                None,
+                Some("Deterministic: vector clock provides causal lineage".to_string()),
+            ),
+        );
+
+        // Noop: No-operation (trivially commutative)
+        self.register(
+            OperationAlgebra::new(
+                "Noop",
+                "none",
+                "none",
+                ConflictType::Commutative,
+                ConvergenceSemantic::StrictlyCommutative,
+                "No-operation: idempotent, affects nothing",
+            )
+            .with_proofs(
+                Some("Trivially commutative: no state affected".to_string()),
+                Some("Trivially deterministic: no change produced".to_string()),
+            ),
+        );
+    }
+
+    /// Register an operation algebra
+    pub fn register(&mut self, algebra: OperationAlgebra) {
+        self.algebras.insert(algebra.operation_type.clone(), algebra);
+    }
+
+    /// Look up algebra for operation type
+    pub fn get(&self, operation_type: &str) -> Option<&OperationAlgebra> {
+        self.algebras.get(operation_type)
+    }
+
+    /// Check if operation type is registered
+    pub fn contains(&self, operation_type: &str) -> bool {
+        self.algebras.contains_key(operation_type)
+    }
+
+    /// Get all registered algebras
+    pub fn all_algebras(&self) -> Vec<&OperationAlgebra> {
+        self.algebras.values().collect()
+    }
+
+    /// Verify all registered operations declare convergence semantics
+    pub fn verify_all_declared(&self) -> Result<(), Vec<String>> {
+        let undeclared: Vec<String> = self
+            .algebras
+            .values()
+            .filter(|a| a.convergence_semantic == ConvergenceSemantic::ConsensusRequired)
+            .map(|a| a.operation_type.clone())
+            .collect();
+
+        if undeclared.is_empty() {
+            Ok(())
+        } else {
+            Err(undeclared)
+        }
+    }
+
+    /// Count operations by convergence semantic
+    pub fn convergence_statistics(&self) -> HashMap<String, usize> {
+        let mut stats = HashMap::new();
+        for algebra in self.algebras.values() {
+            let key = format!("{:?}", algebra.convergence_semantic);
+            *stats.entry(key).or_insert(0) += 1;
+        }
+        stats
+    }
+}
+
+impl Default for OperationAlgebraRegistry {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_registry_creation() {
+        let registry = OperationAlgebraRegistry::new();
+        assert!(registry.algebras.len() > 0);
+    }
+
+    #[test]
+    fn test_setfield_is_lww_register() {
+        let registry = OperationAlgebraRegistry::new();
+        let setfield = registry.get("SetField").unwrap();
+
+        assert_eq!(setfield.conflict_type, ConflictType::Register);
+        assert_eq!(
+            setfield.convergence_semantic,
+            ConvergenceSemantic::DeterministicMerge
+        );
+    }
+
+    #[test]
+    fn test_increment_is_commutative() {
+        let registry = OperationAlgebraRegistry::new();
+        let increment = registry.get("Increment").unwrap();
+
+        assert!(increment.is_commutative());
+        assert_eq!(increment.conflict_type, ConflictType::CounterCRDT);
+    }
+
+    #[test]
+    fn test_addtoset_is_commutative() {
+        let registry = OperationAlgebraRegistry::new();
+        let addtoset = registry.get("AddToSet").unwrap();
+
+        assert!(addtoset.is_commutative());
+        assert_eq!(addtoset.conflict_type, ConflictType::SetCRDT);
+    }
+
+    #[test]
+    fn test_transfer_requires_consensus() {
+        let registry = OperationAlgebraRegistry::new();
+        let transfer = registry.get("Transfer").unwrap();
+
+        assert!(!transfer.is_commutative());
+        assert_eq!(
+            transfer.convergence_semantic,
+            ConvergenceSemantic::ConsensusRequired
+        );
+    }
+
+    #[test]
+    fn test_custom_registration() {
+        let mut registry = OperationAlgebraRegistry::new();
+        let custom = OperationAlgebra::new(
+            "MyCustomOp",
+            "any",
+            "any",
+            ConflictType::Custom("my_merge".to_string()),
+            ConvergenceSemantic::DeterministicMerge,
+            "Custom merge semantics",
+        );
+
+        registry.register(custom);
+        assert!(registry.contains("MyCustomOp"));
+    }
+
+    #[test]
+    fn test_convergence_statistics() {
+        let registry = OperationAlgebraRegistry::new();
+        let stats = registry.convergence_statistics();
+
+        // Should have entries for different convergence semantics
+        assert!(stats.len() > 0);
+        // Most operations should be deterministic or commutative
+        let has_deterministic = stats.values().any(|count| *count > 0);
+        assert!(has_deterministic);
+    }
+
+    #[test]
+    fn test_algebra_with_proofs() {
+        let algebra = OperationAlgebra::new(
+            "TestOp",
+            "test",
+            "test",
+            ConflictType::Commutative,
+            ConvergenceSemantic::StrictlyCommutative,
+            "test merge",
+        )
+        .with_proofs(
+            Some("proof1".to_string()),
+            Some("proof2".to_string()),
+        );
+
+        assert!(algebra.commutativity_proof.is_some());
+        assert!(algebra.determinism_proof.is_some());
+    }
+
+    #[test]
+    fn test_all_standard_operations_registered() {
+        let registry = OperationAlgebraRegistry::new();
+
+        let operations = vec![
+            "SetField",
+            "Increment",
+            "AddToSet",
+            "RemoveFromSet",
+            "Create",
+            "Delete",
+            "Transfer",
+            "Append",
+            "Noop",
+        ];
+
+        for op in operations {
+            assert!(registry.contains(op), "Operation {} not registered", op);
+        }
+    }
+
+    #[test]
+    fn test_operation_is_deterministic() {
+        let registry = OperationAlgebraRegistry::new();
+
+        // Commutative and deterministic merge are deterministic
+        let setfield = registry.get("SetField").unwrap();
+        assert!(setfield.is_deterministic());
+
+        let increment = registry.get("Increment").unwrap();
+        assert!(increment.is_deterministic());
+
+        // Consensus operations are NOT deterministic without consensus authority
+        let transfer = registry.get("Transfer").unwrap();
+        assert!(!transfer.is_deterministic());
+    }
+}