@feltdb/core 0.15.0 → 0.16.1

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

@@ -1,222 +0,0 @@
-//! 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

@@ -1,320 +0,0 @@
-//! Canonical FeltDB State Subsystem Public API Facade
-//!
-//! This module presents the graduated state model as a unified, product-facing
-//! subsystem. Applications should use this facade to access FeltDB's state
-//! primitives rather than reimplementing them.
-//!
-//! Proven Contracts:
-//! - Deterministic content-addressed state identifiers
-//! - Immutable revisions with explicit ancestry
-//! - Durable persistence with restart recovery
-//! - Causal topology tracking
-//! - Semantic diff computation
-//! - Conflict classification
-//! - Explicit reconciliation (no automatic merge)
-
-use crate::state_model::{
-    ConflictClassification, ReconciliationPlan, Relationship, SemanticDiff, StateId,
-    StateReconciliationResult, StateRevision, StateStore, StateTopology, STATE_MODEL_VERSION,
-};
-use crate::FeltDb;
-use std::sync::Arc;
-
-/// FeltDB State System - canonical state subsystem public API
-pub struct FeltDBStateSystem;
-
-impl FeltDBStateSystem {
-    /// Create a new state store for an application with FeltDB persistence
-    ///
-    /// Returns a StateStore that provides:
-    /// - Durable persistence through FeltDB's canonical operation log
-    /// - Immutable revisions
-    /// - Deterministic state identifiers
-    /// - Restart recovery (once implemented)
-    ///
-    /// Applications MUST provide a FeltDb instance. This ensures all state
-    /// mutations are persisted through FeltDB's canonical persistence boundary.
-    ///
-    /// # Arguments
-    /// * `db` - Arc<FeltDb> instance for durable storage
-    ///
-    /// # Returns
-    /// * `Ok(StateStore)` - Successfully initialized store with FeltDB backing
-    /// * `Err(String)` - If initialization fails
-    ///
-    /// # Example
-    /// ```ignore
-    /// let db = FeltDb::open("./data")?;
-    /// let store = FeltDBStateSystem::create_store(&Arc::new(db))?;
-    /// 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())
-    }
-
-    /// Create a volatile (in-memory only) state store for testing
-    ///
-    /// This store is NOT persisted and will lose all data when dropped.
-    /// This is test-only and should not be used in production.
-    ///
-    /// For production, use `create_store(&db)` which requires FeltDB persistence.
-    pub fn create_test_store() -> StateStore {
-        StateStore::new_volatile()
-    }
-
-    /// Get the version of the canonical state model
-    pub fn version() -> u32 {
-        STATE_MODEL_VERSION
-    }
-
-    /// Documentation: This is the canonical way to access FeltDB's state
-    /// primitives. Do not reimplement StateId, StateRevision, StateHistory,
-    /// StateStore, or related primitives.
-    pub fn documentation() -> &'static str {
-        r#"
-        FeltDB State Subsystem - Canonical Primitives
-        
-        Applications should:
-        1. Initialize FeltDB: let db = FeltDb::open(path)?;
-        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.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
-        9. Use ReconciliationPlan with explicit caller policy
-        
-        Applications should NOT:
-        - Reimplement StateId
-        - Reimplement StateRevision
-        - Reimplement StateStore
-        - Compute diffs independently
-        - Implement their own conflict classification
-        - Use implicit/automatic merge
-        - Create StateStore without FeltDB backing (use new_volatile() for testing only)
-        "#
-    }
-}
-
-// Note: All types are re-exported at lib.rs level for public API
-
-#[cfg(test)]
-mod facade_tests {
-    use super::*;
-    use crate::{
-        state_model::StateStore, ConflictClass, ConflictClassification, Relationship, SemanticDiff,
-        StateTopology,
-    };
-    use serde_json::json;
-
-    #[test]
-    fn test_facade_creates_store() {
-        // For testing, use new_volatile() - production must use create_store(&db)
-        let store = StateStore::new_volatile();
-        let initial = store
-            .create(
-                "docs:1",
-                r#"{"data":"test"}"#.to_string(),
-                "test-auth".to_string(),
-            )
-            .expect("Failed to create initial state");
-
-        let stored = store
-            .get(&initial.id)
-            .expect("the revision is retrievable by identity");
-        assert_eq!(stored.id, initial.id);
-    }
-
-    #[test]
-    fn test_facade_version() {
-        assert_eq!(FeltDBStateSystem::version(), 1);
-    }
-
-    #[test]
-    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 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);
-
-        // Divergence 1: alice updates
-        let branch1 = store
-            .commit(
-                r#"{"users":{"alice":150}}"#.to_string(),
-                &initial,
-                "alice-auth".to_string(),
-            )
-            .expect("Failed branch 1");
-
-        // Divergence 2: from the same parent
-        let branch2 = store
-            .commit(
-                r#"{"users":{"alice":100,"bob":50}}"#.to_string(),
-                &initial,
-                "bob-auth".to_string(),
-            )
-            .expect("Failed branch 2");
-
-        // Inspect topology
-        let mut topology = StateTopology::new();
-        topology.add_revision(initial.clone());
-        topology.add_revision(branch1.clone());
-        topology.add_revision(branch2.clone());
-
-        // Verify relationships
-        match topology.relationship(&branch1.id, &branch2.id) {
-            Relationship::Diverged => {
-                // Expected: both descended from initial but different
-            }
-            _ => panic!("Expected Diverged relationship"),
-        }
-
-        // 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 diff = SemanticDiff::compute(&initial_json, &branch1_json);
-        assert!(!diff.changes.is_empty());
-
-        // Classify conflict
-        let classification = ConflictClassification::classify(&initial, &branch1, &branch2);
-        assert_eq!(classification.overall, ConflictClass::Independent);
-    }
-
-    #[test]
-    fn test_facade_immutability() {
-        let store = StateStore::new_volatile();
-        let initial = store
-            .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);
-    }
-
-    #[test]
-    fn test_facade_restart_recovery() {
-        let store1 = StateStore::new_volatile();
-        let initial = store1
-            .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));
-    }
-
-    #[test]
-    fn test_facade_authority_neutrality() {
-        let store = StateStore::new_volatile();
-        let initial = store
-            .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(),
-            )
-            .unwrap();
-
-        let update2 = store
-            .commit(
-                r#"{"balance":150}"#.to_string(),
-                &initial,
-                "bob".to_string(),
-            )
-            .unwrap();
-
-        // 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);
-        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, "alice");
-    }
-
-    #[test]
-    fn test_facade_read_only_operations() {
-        let store = StateStore::new_volatile();
-        let initial = store
-            .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);
-    }
-
-    #[test]
-    fn test_facade_no_git_dependency() {
-        // This test verifies we can use the state system without any .git access
-        let store = StateStore::new_volatile();
-        let state = store
-            .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());
-        assert!(topology.is_ancestor(&state.id, &state.id));
-    }
-}