@feltdb/core 0.8.4 → 0.8.5

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

@@ -0,0 +1,222 @@
+//! The deterministic contract behind FeltDB's semantic state diff.
+//!
+//! This is the second specimen of the pattern established by
+//! [`crate::trigger_contract`]: a decision FeltDB already makes, drawn behind a
+//! runtime-independent boundary so that more than one implementation can be
+//! held to it.
+//!
+//! ```text
+//!        canonical state A  +  canonical state B
+//!                        │
+//!         ┌──────────────┴──────────────┐
+//!         │                             │
+//!   native evaluation             WASM evaluation
+//!         │                             │
+//!         └──────────────┬──────────────┘
+//!                        │
+//!               canonical diff bytes
+//! ```
+//!
+//! # This module adds no diff semantics
+//!
+//! [`SemanticDiff::compute`] is untouched and remains authoritative. Everything
+//! here is envelope: identity, version, canonical encoding, and the decision to
+//! report an unusable input rather than fail. If this module and
+//! `SemanticDiff::compute` ever disagree, `SemanticDiff::compute` is right.
+//!
+//! # Determinism budget
+//!
+//! Evaluation reads nothing but its two states. No clock, filesystem, network,
+//! random source, process identity, authentication context, authority metadata
+//! or process-global mutable state participates, and the audit that produced
+//! this contract found none in the implementation either.
+//!
+//! # What the audit established about the semantics
+//!
+//! These are properties of the existing implementation, recorded here because
+//! the contract is defined against them rather than against an idea of what a
+//! diff should do:
+//!
+//! - **Arrays are positional.** A reorder is not detected; `[1,2] -> [2,1]`
+//!   reports `Changed` at index 0 and at index 1. Elements past the shorter
+//!   length become `Added` or `Removed` at their index.
+//! - **Absence and null are different, in both directions.** `missing -> value`
+//!   is `Added`, `null -> value` is `Changed`, `value -> missing` is `Removed`,
+//!   `value -> null` is `Changed`.
+//! - **`old_value` and `new_value` are `Option`, encoded as `null` when absent.**
+//!   That is ambiguous with a JSON null on its own, and `kind` is what
+//!   disambiguates: `missing -> null` is `Added` with `new_value: null`.
+//! - **Numbers compare by `serde_json` variant.** `42` and `42.0` differ, so
+//!   they report `Changed`; `-0` is a float and so differs from the integer
+//!   `0`; `-0.0` and `0.0` are equal under IEEE equality and report nothing.
+//! - **A type transition is one `Changed`,** carrying both whole values, at the
+//!   path where it happens — including at the empty path, for the states
+//!   themselves.
+//! - **Ordering is total.** Changes sort by path, then by kind. Paths are
+//!   unique within one diff, so the ordering does not depend on sort stability.
+
+use crate::state_model::SemanticDiff;
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use sha2::{Digest, Sha256};
+
+/// Stable identity of this contract.
+pub const STATE_DIFF_CONTRACT_ID: &str = "feltdb.state.diff";
+
+/// Version of this contract's input shape, output shape and semantics.
+///
+/// The output shape is [`SemanticDiff`]'s own serialization, so a change to
+/// that type is a change to this contract and must bump this.
+pub const STATE_DIFF_CONTRACT_VERSION: u32 = 1;
+
+/// The complete deterministic input: two states, and the contract's identity.
+///
+/// Members are declared alphabetically so the canonical struct encoding matches
+/// the sorted-key encoding `serde_json` gives every JSON object.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateDiffInput {
+    pub contract: String,
+    pub state_a: Value,
+    pub state_b: Value,
+    pub version: u32,
+}
+
+impl StateDiffInput {
+    /// Builds an input stamped with this contract's identity and version.
+    pub fn new(state_a: Value, state_b: Value) -> Self {
+        Self {
+            contract: STATE_DIFF_CONTRACT_ID.to_string(),
+            state_a,
+            state_b,
+            version: STATE_DIFF_CONTRACT_VERSION,
+        }
+    }
+}
+
+/// Why an input could not be evaluated.
+///
+/// Three codes, matching the vocabulary [`crate::trigger_contract`] uses. As
+/// there, an error carries a code and nothing else: a free-form message would
+/// be a divergence surface between implementations that says nothing about the
+/// semantics under test.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum ContractErrorCode {
+    /// The bytes are not a well-formed instance of this contract's input.
+    ContractInputInvalid,
+    /// The input declares a different contract.
+    ContractIdMismatch,
+    /// The input declares a version this implementation does not implement.
+    ContractVersionUnsupported,
+}
+
+/// The error body of a contract output.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ContractErrorBody {
+    pub code: ContractErrorCode,
+}
+
+/// The complete deterministic output.
+///
+/// Exactly one of `diff` and `error` is present. `diff` is [`SemanticDiff`]
+/// serialized exactly as it already serializes — this contract does not
+/// reshape it, because the existing semantic result *is* the contract.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct StateDiffOutput {
+    pub contract: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub diff: Option<SemanticDiff>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub error: Option<ContractErrorBody>,
+    pub version: u32,
+}
+
+impl StateDiffOutput {
+    fn computed(diff: SemanticDiff) -> Self {
+        Self {
+            contract: STATE_DIFF_CONTRACT_ID.to_string(),
+            diff: Some(diff),
+            error: None,
+            version: STATE_DIFF_CONTRACT_VERSION,
+        }
+    }
+
+    fn failure(code: ContractErrorCode) -> Self {
+        Self {
+            contract: STATE_DIFF_CONTRACT_ID.to_string(),
+            diff: None,
+            error: Some(ContractErrorBody { code }),
+            version: STATE_DIFF_CONTRACT_VERSION,
+        }
+    }
+}
+
+/// The runtime that executed a contract, recorded in evidence.
+///
+/// Only [`ContractRuntime::Native`] is wired anywhere. As with the trigger
+/// contract, the WASM variant exists so a recorded runtime can be named
+/// honestly; it is not a selection switch.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ContractRuntime {
+    Native,
+    Wasm,
+}
+
+impl ContractRuntime {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Native => "native",
+            Self::Wasm => "wasm",
+        }
+    }
+}
+
+/// The deterministic contract, natively implemented.
+///
+/// A thin adapter over the existing implementation, deliberately holding no
+/// diff logic of its own.
+pub fn diff_states(state_a: &Value, state_b: &Value) -> SemanticDiff {
+    SemanticDiff::compute(state_a, state_b)
+}
+
+/// The canonical byte encoding of a contract input.
+pub fn canonical_input_bytes(input: &StateDiffInput) -> Vec<u8> {
+    serde_json::to_vec(input).expect("contract input is always serializable")
+}
+
+/// The canonical byte encoding of a contract output.
+pub fn canonical_output_bytes(output: &StateDiffOutput) -> Vec<u8> {
+    serde_json::to_vec(output).expect("contract output is always serializable")
+}
+
+/// Content identity of a contract input, for provenance.
+pub fn input_digest(input: &StateDiffInput) -> String {
+    format!("sha256:{:x}", Sha256::digest(canonical_input_bytes(input)))
+}
+
+/// The runtime-independent entry point: canonical bytes in, canonical bytes out.
+///
+/// This is the exact shape a foreign runtime implements. It never panics and
+/// never returns anything but a canonical output encoding, so an unusable input
+/// is a contract decision rather than a host-specific failure mode.
+pub fn evaluate_canonical(input: &[u8]) -> Vec<u8> {
+    canonical_output_bytes(&evaluate_canonical_output(input))
+}
+
+/// [`evaluate_canonical`] before encoding, for callers that want the value.
+pub fn evaluate_canonical_output(input: &[u8]) -> StateDiffOutput {
+    let Ok(parsed) = serde_json::from_slice::<StateDiffInput>(input) else {
+        return StateDiffOutput::failure(ContractErrorCode::ContractInputInvalid);
+    };
+    if parsed.contract != STATE_DIFF_CONTRACT_ID {
+        return StateDiffOutput::failure(ContractErrorCode::ContractIdMismatch);
+    }
+    if parsed.version != STATE_DIFF_CONTRACT_VERSION {
+        return StateDiffOutput::failure(ContractErrorCode::ContractVersionUnsupported);
+    }
+    StateDiffOutput::computed(diff_states(&parsed.state_a, &parsed.state_b))
+}

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

@@ -14,9 +14,8 @@
 //! - Explicit reconciliation (no automatic merge)
 
 use crate::state_model::{
-    StateId, StateRevision, StateStore, StateTopology, Relationship,
-    SemanticDiff, ConflictClassification, ReconciliationPlan,
-    StateReconciliationResult, STATE_MODEL_VERSION,
+    ConflictClassification, ReconciliationPlan, Relationship, SemanticDiff, StateId,
+    StateReconciliationResult, StateRevision, StateStore, StateTopology, STATE_MODEL_VERSION,
 };
 use crate::FeltDb;
 use std::sync::Arc;
@@ -47,8 +46,8 @@ impl FeltDBStateSystem {
     /// ```ignore
     /// let db = FeltDb::open("./data")?;
     /// let store = FeltDBStateSystem::create_store(&Arc::new(db))?;
-    /// let initial = store.create(json_string, "app-authority")?;
-    /// let current = store.current()?;
+    /// let initial = store.create("docs:1", json_string, "app-authority")?;
+    /// let same = store.get(&initial.id).expect("retrieved by identity");
     /// ```
     pub fn create_store(db: &Arc<FeltDb>) -> Result<StateStore, String> {
         StateStore::with_feltdb(db.clone())
@@ -81,7 +80,9 @@ impl FeltDBStateSystem {
         2. Use FeltDBStateSystem::create_store(&Arc::new(db)) to initialize state
         3. Call store.create() for initial state
         4. Call store.commit() for transitions
-        5. Call store.current() to retrieve the working state
+        5. Call store.get(&id) to retrieve a revision by identity
+           (the store does not track which revision is "current" — see
+            StateStore's own documentation for why that is a separate concern)
         6. Use StateTopology to inspect causal relationships
         7. Use SemanticDiff to compute changes between states
         8. Use ConflictClassification to analyze divergence
@@ -104,7 +105,10 @@ impl FeltDBStateSystem {
 #[cfg(test)]
 mod facade_tests {
     use super::*;
-    use crate::{ConflictClass, SemanticDiff, StateTopology, Relationship, ConflictClassification, state_model::StateStore};
+    use crate::{
+        state_model::StateStore, ConflictClass, ConflictClassification, Relationship, SemanticDiff,
+        StateTopology,
+    };
     use serde_json::json;
 
     #[test]
@@ -112,11 +116,17 @@ mod facade_tests {
         // For testing, use new_volatile() - production must use create_store(&db)
         let store = StateStore::new_volatile();
         let initial = store
-            .create(r#"{"data":"test"}"#.to_string(), "test-auth".to_string())
+            .create(
+                "docs:1",
+                r#"{"data":"test"}"#.to_string(),
+                "test-auth".to_string(),
+            )
             .expect("Failed to create initial state");
-        
-        let current = store.current().expect("Failed to get current state");
-        assert_eq!(current.id, initial.id);
+
+        let stored = store
+            .get(&initial.id)
+            .expect("the revision is retrievable by identity");
+        assert_eq!(stored.id, initial.id);
     }
 
     #[test]
@@ -128,19 +138,21 @@ mod facade_tests {
     fn test_facade_comprehensive_workflow() {
         // Initialize - for testing, use new_volatile()
         let store = StateStore::new_volatile();
-        
+
         // Create initial state
         let initial = store
             .create(
+                "docs:1",
                 r#"{"users":{"alice":100}}"#.to_string(),
                 "app-auth".to_string(),
             )
             .expect("Failed to create");
 
-        // Verify current
-        assert_eq!(store.current().unwrap().id, initial.id);
+        // Verify the revision is retrievable by identity. The store tracks no
+        // "current" pointer; the caller holds the ids it cares about.
+        assert_eq!(store.get(&initial.id).unwrap().id, initial.id);
 
-        // Branch 1: alice updates
+        // Divergence 1: alice updates
         let branch1 = store
             .commit(
                 r#"{"users":{"alice":150}}"#.to_string(),
@@ -149,11 +161,7 @@ mod facade_tests {
             )
             .expect("Failed branch 1");
 
-        store
-            .create_branch("alice-branch".to_string(), branch1.id.clone())
-            .expect("Failed to create alice-branch");
-
-        // Branch 2: create from initial
+        // Divergence 2: from the same parent
         let branch2 = store
             .commit(
                 r#"{"users":{"alice":100,"bob":50}}"#.to_string(),
@@ -162,10 +170,6 @@ mod facade_tests {
             )
             .expect("Failed branch 2");
 
-        store
-            .create_branch("bob-branch".to_string(), branch2.id.clone())
-            .expect("Failed to create bob-branch");
-
         // Inspect topology
         let mut topology = StateTopology::new();
         topology.add_revision(initial.clone());
@@ -181,12 +185,10 @@ mod facade_tests {
         }
 
         // Compute diff using JSON values
-        let initial_json: serde_json::Value = serde_json::from_str(
-            r#"{"users":{"alice":100}}"#,
-        ).unwrap();
-        let branch1_json: serde_json::Value = serde_json::from_str(
-            r#"{"users":{"alice":150}}"#,
-        ).unwrap();
+        let initial_json: serde_json::Value =
+            serde_json::from_str(r#"{"users":{"alice":100}}"#).unwrap();
+        let branch1_json: serde_json::Value =
+            serde_json::from_str(r#"{"users":{"alice":150}}"#).unwrap();
         let diff = SemanticDiff::compute(&initial_json, &branch1_json);
         assert!(!diff.changes.is_empty());
 
@@ -199,16 +201,16 @@ mod facade_tests {
     fn test_facade_immutability() {
         let store = StateStore::new_volatile();
         let initial = store
-            .create(r#"{"v":1}"#.to_string(), "auth".to_string())
+            .create("docs:1", r#"{"v":1}"#.to_string(), "auth".to_string())
             .unwrap();
-        
+
         let initial_id = initial.id.clone();
-        
+
         // Create another state
         let second = store
             .commit(r#"{"v":2}"#.to_string(), &initial, "auth".to_string())
             .unwrap();
-        
+
         // Verify first state is unchanged
         assert_eq!(store.get(&initial_id).unwrap().content, r#"{"v":1}"#);
         assert_eq!(initial_id, initial.id);
@@ -218,12 +220,16 @@ mod facade_tests {
     fn test_facade_restart_recovery() {
         let store1 = StateStore::new_volatile();
         let initial = store1
-            .create(r#"{"data":"test"}"#.to_string(), "auth".to_string())
+            .create(
+                "docs:1",
+                r#"{"data":"test"}"#.to_string(),
+                "auth".to_string(),
+            )
             .unwrap();
-        
+
         // Simulate restart: new store instance
         let _store2 = StateStore::new_volatile();
-        
+
         // Note: In real scenario, store would load from persistent storage
         // Here we demonstrate the API contract: states retrieved by id are valid
         assert!(store1.exists(&initial.id));
@@ -233,44 +239,62 @@ mod facade_tests {
     fn test_facade_authority_neutrality() {
         let store = StateStore::new_volatile();
         let initial = store
-            .create(r#"{"balance":100}"#.to_string(), "alice".to_string())
+            .create(
+                "docs:1",
+                r#"{"balance":100}"#.to_string(),
+                "alice".to_string(),
+            )
             .unwrap();
-        
+
         let update1 = store
-            .commit(r#"{"balance":150}"#.to_string(), &initial, "alice".to_string())
+            .commit(
+                r#"{"balance":150}"#.to_string(),
+                &initial,
+                "alice".to_string(),
+            )
             .unwrap();
-        
+
         let update2 = store
-            .commit(r#"{"balance":150}"#.to_string(), &initial, "bob".to_string())
+            .commit(
+                r#"{"balance":150}"#.to_string(),
+                &initial,
+                "bob".to_string(),
+            )
             .unwrap();
-        
-        // Same content, different authorities produce same id
+
+        // The same state, from the same parent, is the same historical fact —
+        // so it is one revision, whoever committed it. Authority is recorded
+        // but takes no part in identity.
         assert_eq!(update1.id, update2.id);
-        
-        // But authorities are recorded for audit
+        assert_eq!(update1.content_id, update2.content_id);
+
+        // And because authority takes no part in identity, the second commit
+        // is a no-op that returns what was already recorded. The authority on a
+        // revision is whoever first committed that historical fact, not
+        // whoever last asked for it.
         assert_eq!(update1.authority, "alice");
-        assert_eq!(update2.authority, "bob");
+        assert_eq!(update2.authority, "alice");
     }
 
     #[test]
     fn test_facade_read_only_operations() {
         let store = StateStore::new_volatile();
         let initial = store
-            .create(r#"{"v":1}"#.to_string(), "auth".to_string())
+            .create("docs:1", r#"{"v":1}"#.to_string(), "auth".to_string())
             .unwrap();
-        
+
         let update = store
             .commit(r#"{"v":2}"#.to_string(), &initial, "auth".to_string())
             .unwrap();
-        
+
         // Topology operations should not mutate
         let mut topology = StateTopology::new();
         topology.add_revision(initial.clone());
         topology.add_revision(update.clone());
-        
+
         let rel = topology.relationship(&initial.id, &update.id);
         assert!(matches!(rel, Relationship::Ancestor));
-        
+
         // Verify both states still exist unchanged
         assert_eq!(store.get(&initial.id).unwrap().id, initial.id);
         assert_eq!(store.get(&update.id).unwrap().id, update.id);
@@ -281,9 +305,13 @@ mod facade_tests {
         // This test verifies we can use the state system without any .git access
         let store = StateStore::new_volatile();
         let state = store
-            .create(r#"{"test":"no-git"}"#.to_string(), "auth".to_string())
+            .create(
+                "docs:1",
+                r#"{"test":"no-git"}"#.to_string(),
+                "auth".to_string(),
+            )
             .expect("State creation should work without .git");
-        
+
         // Topology and diff operations should work without git
         let mut topology = StateTopology::new();
         topology.add_revision(state.clone());

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

@@ -2,7 +2,6 @@
 ///
 /// 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;
 
@@ -27,7 +26,8 @@ impl CanonicalState {
 
     /// 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()))
+        self.records
+            .get(&(collection.to_string(), record_id.to_string()))
     }
 
     /// Canonical serialization for hashing (deterministic ordering)