praborrow_core/

lib.rs

//! Core primitives for distributed ownership enforcement.
//!
//! This crate provides `Sovereign<T>`, a wrapper type that tracks ownership
//! across network boundaries. When a resource is "annexed" (moved to another node),
//! local access is prohibited.
//!
//! # The Garuda Proof System
//!
//! With `praborrow-prover`, this crate now supports **formally verified** state
//! transitions. Use `annex_verified()` to require SMT proof before annexation.
//!
//! # Safety
//! Uses `UnsafeCell` and `AtomicU8` for interior mutability with thread-safety.
//! The `Send`/`Sync` implementations are safe when `T` is `Send`/`Sync`.

#![cfg_attr(not(feature = "std"), no_std)]

extern crate alloc;

use alloc::collections::BTreeMap;
use alloc::string::String;
use core::cell::UnsafeCell;
use core::marker::PhantomData;
use core::ops::{Deref, DerefMut};
use core::sync::atomic::{AtomicU8, Ordering};

/// The state of a Sovereign resource.
/// 0: Domestic (Local jurisdiction)
/// 1: Exiled (Foreign jurisdiction - moved to another node)
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
#[repr(u8)]
pub enum SovereignState {
    Domestic = 0,
    Exiled = 1,
}

impl core::fmt::Display for SovereignState {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            SovereignState::Domestic => f.write_str("Domestic"),
            SovereignState::Exiled => f.write_str("Exiled"),
        }
    }
}

/// A token that proves a resource has been returned to domestic jurisdiction.
///
/// This token is required to call `Sovereign::repatriate`. It can only be constructed
/// by trusted system components (like the lease manager) that can guarantee the
/// resource is safe to reclaim.
pub struct RepatriationToken {
    /// ID of the lease holder returning the resource
    pub(crate) holder_id: u128,
    _private: (),
}

impl RepatriationToken {
    /// Creates a new repatriation token.
    ///
    /// # Safety
    ///
    /// This function is unsafe because creating a token allows the holder to
    /// repatriate a sovereign resource. The caller must guarantee that the
    /// resource is indeed back in domestic jurisdiction and no longer accessed
    /// remotely.
    pub unsafe fn new(holder_id: u128) -> Self {
        Self {
            holder_id,
            _private: (),
        }
    }
}

/// A wrapper that enforces ownership semantics across network boundaries.
///
/// "Memory safety with sovereign integrity."
pub struct Sovereign<T> {
    inner: UnsafeCell<T>,
    state: AtomicU8,
}

/// Error enforcing constitutional invariants.
#[non_exhaustive]
#[derive(thiserror::Error, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "std", derive(serde::Serialize, serde::Deserialize))]
pub enum ConstitutionError {
    #[error("Invariant violated: {expression}. Values: {values:?}")]
    InvariantViolation {
        expression: String,
        values: BTreeMap<String, String>,
    },
}

/// Error returned when accessing a Sovereign resource fails.
#[non_exhaustive]
#[derive(thiserror::Error, Debug, Clone, PartialEq, Eq)]
pub enum SovereigntyError {
    /// Resource is under foreign jurisdiction (Exiled).
    #[error("SOVEREIGNTY VIOLATION: Resource is under foreign jurisdiction.")]
    ForeignJurisdiction,
}

impl<T> Sovereign<T> {
    /// Creates a new Sovereign resource under domestic jurisdiction.
    ///
    /// # Atomic Ordering
    ///
    /// Uses `SeqCst` ordering for maximum safety in distributed scenarios.
    /// This ensures all threads see state changes in a consistent order,
    /// which is critical for ownership semantics across network boundaries.
    #[must_use = "Sovereign resources must be managed carefully"]
    pub fn new(value: T) -> Self {
        Self {
            inner: UnsafeCell::new(value),
            state: AtomicU8::new(SovereignState::Domestic as u8),
        }
    }

    /// Creates a new Sovereign resource that is already under foreign jurisdiction.
    ///
    /// This is useful for nodes receiving data that has been transferred from
    /// another node - the resource starts in an Exiled state.
    ///
    /// # Example
    ///
    /// ```
    /// use praborrow_core::{Sovereign, SovereignState};
    ///
    /// let foreign_data = Sovereign::new_exiled(42i32);
    /// assert!(foreign_data.is_exiled());
    /// ```
    #[must_use = "Sovereign resources must be managed carefully"]
    pub fn new_exiled(value: T) -> Self {
        Self {
            inner: UnsafeCell::new(value),
            state: AtomicU8::new(SovereignState::Exiled as u8),
        }
    }

    /// Annexes the resource, moving it to foreign jurisdiction.
    ///
    /// Once annexed, the resource cannot be accessed locally.
    /// Access attempts will result in a Sovereignty Violation.
    #[must_use = "Annexation result should be checked"]
    #[tracing::instrument(skip(self))]
    pub fn annex(&self) -> Result<(), AnnexError> {
        let current = self.state.load(Ordering::SeqCst);
        if current == SovereignState::Exiled as u8 {
            return Err(AnnexError::AlreadyExiled);
        }

        // Diplomatically transition state
        self.state
            .store(SovereignState::Exiled as u8, Ordering::SeqCst);

        tracing::debug!(
            from = "Domestic",
            to = "Exiled",
            "Resource annexed to foreign jurisdiction"
        );

        Ok(())
    }

    /// Returns a reference to the inner value without jurisdiction check.
    ///
    /// # Safety
    ///
    /// This is safe because we're returning a shared reference and the caller
    /// is responsible for ensuring the resource is domestic. Use `try_get()`
    /// for safe access with jurisdiction verification.
    pub fn inner_ref(&self) -> &T {
        // SAFETY: We're only reading, and this is safe when called from
        // contexts that have already verified jurisdiction.
        unsafe { &*self.inner.get() }
    }

    /// Returns the current state of the resource.
    #[inline]
    pub fn state(&self) -> SovereignState {
        match self.state.load(Ordering::SeqCst) {
            0 => SovereignState::Domestic,
            _ => SovereignState::Exiled,
        }
    }

    /// Returns `true` if the resource is under domestic jurisdiction.
    #[inline]
    pub fn is_domestic(&self) -> bool {
        self.state.load(Ordering::SeqCst) == SovereignState::Domestic as u8
    }

    /// Returns `true` if the resource is under foreign jurisdiction (exiled).
    #[inline]
    pub fn is_exiled(&self) -> bool {
        self.state.load(Ordering::SeqCst) == SovereignState::Exiled as u8
    }

    /// Attempts to get a reference to the value, returning an error if Exiled.
    #[must_use = "Check jurisdiction result"]
    pub fn try_get(&self) -> Result<&T, SovereigntyError> {
        if self.is_exiled() {
            return Err(SovereigntyError::ForeignJurisdiction);
        }
        // SAFETY: We verified the resource is domestic.
        unsafe { Ok(&*self.inner.get()) }
    }

    /// Attempts to get a mutable reference to the value, returning an error if Exiled.
    #[must_use = "Check jurisdiction result"]
    pub fn try_get_mut(&mut self) -> Result<&mut T, SovereigntyError> {
        if self.is_exiled() {
            return Err(SovereigntyError::ForeignJurisdiction);
        }
        // SAFETY: We verified resource is domestic and have &mut self.
        unsafe { Ok(&mut *self.inner.get()) }
    }

    /// Repatriates a resource, transitioning it from Exiled back to Domestic.
    ///
    /// Requires a `RepatriationToken` as proof that the resource is safe to reclaim.
    ///
    /// # Example
    ///
    /// ```
    /// use praborrow_core::{Sovereign, SovereignState, RepatriationToken};
    ///
    /// let resource = Sovereign::new(42i32);
    /// resource.annex().unwrap();
    /// assert!(resource.is_exiled());
    ///
    /// // ... resource is sent to foreign node and returned ...
    ///
    /// // SAFETY: construction of token implies safety verification
    /// let token = unsafe { RepatriationToken::new(123) };
    /// resource.repatriate(token);
    /// assert!(resource.is_domestic());
    /// ```
    #[tracing::instrument(skip(self, token), fields(holder_id = token.holder_id))]
    pub fn repatriate(&self, token: RepatriationToken) {
        let previous = self
            .state
            .swap(SovereignState::Domestic as u8, Ordering::SeqCst);

        if previous == SovereignState::Exiled as u8 {
            tracing::debug!(
                from = "Exiled",
                to = "Domestic",
                holder_id = token.holder_id,
                "Resource repatriated to domestic jurisdiction"
            );
        }
    }

    /// Checks if the resource is currently domestic, panicking if not.
    ///
    /// Used internally by Deref/DerefMut. Prefer `try_get()` for non-panicking access.
    #[track_caller]
    fn verify_jurisdiction(&self) {
        if self.is_exiled() {
            panic!("SOVEREIGNTY VIOLATION: Resource is under foreign jurisdiction.");
        }
    }

    /// Maps a function over the domestic sovereign value.
    ///
    /// If the resource is Exiled, returns `Err(SovereigntyError::ForeignJurisdiction)`
    /// without evaluating the function.
    ///
    /// # Example
    ///
    /// ```
    /// use praborrow_core::Sovereign;
    /// let s = Sovereign::new(5);
    /// let result = s.map(|x| x * 2).unwrap();
    /// assert_eq!(result, 10);
    /// ```
    pub fn map<F, U>(&self, f: F) -> Result<U, SovereigntyError>
    where
        F: FnOnce(&T) -> U,
    {
        if self.is_exiled() {
            return Err(SovereigntyError::ForeignJurisdiction);
        }
        // SAFETY: We verified resource is domestic.
        Ok(f(unsafe { &*self.inner.get() }))
    }

    /// Chains a function that returns a Result over the domestic sovereign value.
    ///
    /// This is useful for sequencing operations that might fail or themselves require
    /// jurisdiction checks.
    pub fn and_then<F, U>(&self, f: F) -> Result<U, SovereigntyError>
    where
        F: FnOnce(&T) -> Result<U, SovereigntyError>,
    {
        if self.is_exiled() {
            return Err(SovereigntyError::ForeignJurisdiction);
        }
        // SAFETY: We verified resource is domestic.
        f(unsafe { &*self.inner.get() })
    }

    /// Returns a reference to the inner value if it matches the predicate.
    ///
    /// # Returns
    ///
    /// - `Ok(Some(&T))` if domestic and predicate is true
    /// - `Ok(None)` if domestic and predicate is false
    /// - `Err(ForeignJurisdiction)` if exiled
    pub fn filter<P>(&self, predicate: P) -> Result<Option<&T>, SovereigntyError>
    where
        P: FnOnce(&T) -> bool,
    {
        if self.is_exiled() {
            return Err(SovereigntyError::ForeignJurisdiction);
        }
        // SAFETY: We verified resource is domestic.
        let val = unsafe { &*self.inner.get() };
        if predicate(val) {
            Ok(Some(val))
        } else {
            Ok(None)
        }
    }

    /// Modifies the value in-place if domestic.
    ///
    /// # Example
    ///
    /// ```
    /// use praborrow_core::Sovereign;
    /// let mut s = Sovereign::new(5);
    /// s.modify(|x| *x += 1).unwrap();
    /// assert_eq!(*s, 6);
    /// ```
    pub fn modify<F>(&mut self, f: F) -> Result<(), SovereigntyError>
    where
        F: FnOnce(&mut T),
    {
        if self.is_exiled() {
            return Err(SovereigntyError::ForeignJurisdiction);
        }
        // SAFETY: We verified resource is domestic and have &mut self.
        f(unsafe { &mut *self.inner.get() });
        Ok(())
    }
}

impl<T: core::fmt::Debug> core::fmt::Debug for Sovereign<T> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        let state = self.state();
        match state {
            SovereignState::Domestic => {
                // SAFETY: We checked state is Domestic.
                let val = unsafe { &*self.inner.get() };
                f.debug_struct("Sovereign")
                    .field("state", &state)
                    .field("inner", val)
                    .finish()
            }
            SovereignState::Exiled => f
                .debug_struct("Sovereign")
                .field("state", &state)
                .field("inner", &"<Inaccessible>")
                .finish(),
        }
    }
}

impl<T> Deref for Sovereign<T> {
    type Target = T;

    #[track_caller]
    fn deref(&self) -> &Self::Target {
        self.verify_jurisdiction();
        // SAFETY: We've verified the resource is domestic, so access is valid.
        unsafe { &*self.inner.get() }
    }
}

impl<T> DerefMut for Sovereign<T> {
    #[track_caller]
    fn deref_mut(&mut self) -> &mut Self::Target {
        self.verify_jurisdiction();
        // SAFETY: We've verified the resource is domestic and have &mut self.
        unsafe { &mut *self.inner.get() }
    }
}

// SAFETY: Sovereign<T> is Send/Sync if T is Send/Sync, as we use AtomicU8 for state
// and check it before access. The UnsafeCell is protected by the atomic state check.
unsafe impl<T: Send> Send for Sovereign<T> {}
unsafe impl<T: Sync> Sync for Sovereign<T> {}

/// Protocol for enforcing constitutional invariants (runtime checks).
///
/// Types implementing this trait can validate their internal state against
/// a set of invariants defined via the `#[derive(Constitution)]` macro.
pub trait CheckProtocol {
    /// Enforces all invariants, returning an error if any are violated.
    ///
    /// # Returns
    ///
    /// - `Ok(())` if all invariants are satisfied
    /// - `Err(ConstitutionError)` containing a description of the violated invariant
    ///
    /// # Example
    ///
    /// ```ignore
    /// use praborrow_core::CheckProtocol;
    ///
    /// let data = MyStruct { value: -1 };
    /// match data.enforce_law() {
    ///     Ok(()) => println!("All invariants satisfied"),
    ///     Err(e) => println!("Invariant violated: {}", e),
    /// }
    /// ```
    fn enforce_law(&self) -> Result<(), ConstitutionError>;
}

/// A value carrying cryptographic proof of verification.
///
/// This type can only be constructed by successful SMT verification.
/// Its existence in a type signature proves that formal verification occurred.
///
/// # Type Safety Guarantee
///
/// `ProofCarrying<T>` cannot be forged - the private `_proof` field
/// ensures only the prover crate can construct it.
#[derive(Debug)]
pub struct ProofCarrying<T> {
    /// The carried value.
    pub value: T,
    /// Private marker ensuring construction only via verification.
    _proof: PhantomData<()>,
}

impl<T> ProofCarrying<T> {
    /// Creates a new proof-carrying value.
    ///
    /// This should only be called after successful verification.
    #[doc(hidden)]
    pub fn new_unchecked(value: T) -> Self {
        Self {
            value,
            _proof: PhantomData,
        }
    }

    /// Extracts the inner value, consuming the proof.
    pub fn into_inner(self) -> T {
        self.value
    }
}

impl<T: Clone> Clone for ProofCarrying<T> {
    fn clone(&self) -> Self {
        Self {
            value: self.value.clone(),
            _proof: PhantomData,
        }
    }
}

/// Error type for verified annexation operations.
#[non_exhaustive]
#[derive(thiserror::Error, Debug, Clone, PartialEq, Eq)]
pub enum AnnexError {
    /// Resource is already under foreign jurisdiction.
    #[error("Resource is already under foreign jurisdiction")]
    AlreadyExiled,
    /// SMT verification failed.
    #[error("Verification failed: {reason}")]
    VerificationFailed { reason: String },
    /// Prover encountered an error.
    #[error("Prover error: {0}")]
    ProverError(String),
}

/// Error returned when a lease operation fails.
#[non_exhaustive]
#[derive(thiserror::Error, Debug, Clone, PartialEq, Eq)]
pub enum LeaseError {
    /// Resource is already leased to another holder.
    #[error("Resource is already leased to another holder")]
    AlreadyLeased,
    /// Resource is under foreign jurisdiction.
    #[error("Resource is under foreign jurisdiction")]
    ForeignJurisdiction,
    /// Lease duration must be non-zero.
    #[error("Lease duration must be non-zero")]
    InvalidDuration,
}

/// Represents a lease on a Sovereign resource.
pub struct Lease<T> {
    /// The holder's unique identifier.
    pub holder: u128,
    /// Duration of the lease.
    pub duration: core::time::Duration,
    /// Phantom data for the resource type.
    _phantom: PhantomData<T>,
}

impl<T> Lease<T> {
    /// Creates a new lease.
    ///
    /// # Duration Validation
    ///
    /// If `duration` is zero, returns `Err(LeaseError::InvalidDuration)`.
    pub fn new(holder: u128, duration: core::time::Duration) -> Result<Self, LeaseError> {
        if duration.is_zero() {
            return Err(LeaseError::InvalidDuration);
        }

        Ok(Self {
            holder,
            duration,
            _phantom: PhantomData,
        })
    }

    /// Returns the duration of the lease.
    #[inline]
    pub fn duration(&self) -> core::time::Duration {
        self.duration
    }

    /// Returns the holder ID.
    #[inline]
    pub fn holder(&self) -> u128 {
        self.holder
    }
}

/// Trait for distributed borrow operations.
pub trait DistributedBorrow<T> {
    /// Attempt to acquire a lease on the resource.
    fn try_hire(
        &self,
        candidate_id: u128,
        term: core::time::Duration,
    ) -> Result<Lease<T>, LeaseError>;
}

impl<T> DistributedBorrow<T> for Sovereign<T> {
    fn try_hire(
        &self,
        candidate_id: u128,
        term: core::time::Duration,
    ) -> Result<Lease<T>, LeaseError> {
        let current = self.state.load(Ordering::SeqCst);
        if current == SovereignState::Exiled as u8 {
            return Err(LeaseError::AlreadyLeased);
        }

        // Transition to exiled state (leased)
        self.state
            .store(SovereignState::Exiled as u8, Ordering::SeqCst);
        Lease::<T>::new(candidate_id, term)
    }
}

/// Extension trait for Sovereign types whose inner types implement formal verification.
///
/// This trait is automatically implemented for `Sovereign<T>` where `T` can be
/// formally verified via the Garuda Proof System.
pub trait VerifiedAnnex<T> {
    /// Annexes the resource after successful formal verification.
    ///
    /// Unlike `annex()`, this method requires mathematical proof that all
    /// invariants are satisfied before the state transition occurs.
    ///
    /// # Returns
    ///
    /// - `Ok(ProofCarrying<()>)` - Verification passed, resource is now Exiled
    /// - `Err(AnnexError)` - Verification failed or resource already Exiled
    ///
    /// # Example
    ///
    /// ```ignore
    /// use praborrow_core::{Sovereign, VerifiedAnnex};
    ///
    /// let resource = Sovereign::new(MyVerifiableStruct { balance: 100 });
    ///
    /// // This will run SMT verification before annexing
    /// match resource.annex_verified() {
    ///     Ok(proof) => println!("Annexation proven safe!"),
    ///     Err(e) => println!("Cannot annex: {}", e),
    /// }
    /// ```
    fn annex_verified(&self) -> Result<ProofCarrying<()>, AnnexError>;
}

// Note: The actual implementation of VerifiedAnnex requires praborrow-prover,
// which would create a circular dependency. Instead, the implementation is
// provided via blanket impl in praborrow-prover or via the facade crate.
//
// Users should use the `praborrow` facade crate for full functionality.

#[cfg(test)]
mod debug_test;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_sovereign_new() {
        let s = Sovereign::new(42i32);
        assert_eq!(s.state(), SovereignState::Domestic);
        assert!(s.is_domestic());
        assert!(!s.is_exiled());
    }

    #[test]
    fn test_sovereign_new_exiled() {
        let s = Sovereign::new_exiled(42i32);
        assert_eq!(s.state(), SovereignState::Exiled);
        assert!(s.is_exiled());
        assert!(!s.is_domestic());
    }

    #[test]
    fn test_sovereign_deref() {
        let s = Sovereign::new(42i32);
        assert_eq!(*s, 42);
    }

    #[test]
    fn test_sovereign_deref_mut() {
        let mut s = Sovereign::new(42i32);
        *s = 100;
        assert_eq!(*s, 100);
    }

    #[test]
    fn test_sovereign_annex() {
        let s = Sovereign::new(42i32);
        assert!(s.annex().is_ok());
        assert_eq!(s.state(), SovereignState::Exiled);
        assert!(s.is_exiled());
    }

    #[test]
    fn test_sovereign_double_annex() {
        let s = Sovereign::new(42i32);
        assert!(s.annex().is_ok());
        assert!(s.annex().is_err());
    }

    #[test]
    fn test_sovereign_repatriate() {
        let s = Sovereign::new(42i32);
        s.annex().unwrap();
        assert!(s.is_exiled());


        // SAFETY: In test context, we control both sides
        // SAFETY: In test context, we control both sides
        let token = unsafe { RepatriationToken::new(100) };
        s.repatriate(token);
        assert!(s.is_domestic());

        // Should be able to access again
        assert_eq!(*s, 42);
    }

    #[test]
    #[should_panic(expected = "SOVEREIGNTY VIOLATION")]
    fn test_sovereignty_violation() {
        let s = Sovereign::new(42i32);
        s.annex().unwrap();
        let _ = *s; // This should panic
    }

    #[test]
    fn test_try_get_domestic() {
        let s = Sovereign::new(42i32);
        assert_eq!(*s.try_get().unwrap(), 42);
    }

    #[test]
    fn test_try_get_exiled() {
        let s = Sovereign::new(42i32);
        s.annex().unwrap();
        assert!(matches!(
            s.try_get(),
            Err(SovereigntyError::ForeignJurisdiction)
        ));
    }

    #[test]
    fn test_proof_carrying() {
        let proof = ProofCarrying::new_unchecked(42i32);
        assert_eq!(proof.value, 42);
        assert_eq!(proof.into_inner(), 42);
    }

    #[test]
    fn test_annex_error_display() {
        let e = AnnexError::AlreadyExiled;
        assert!(e.to_string().contains("foreign jurisdiction"));

        let e = AnnexError::VerificationFailed {
            reason: "test".to_string(),
        };
        assert!(e.to_string().contains("test"));
    }

    #[test]
    fn test_lease_zero_duration_fails() {
        let lease = Lease::<i32>::new(1, core::time::Duration::ZERO);
        assert!(matches!(lease, Err(LeaseError::InvalidDuration)));
    }

    #[test]
    fn test_lease_normal_duration() {
        let duration = core::time::Duration::from_secs(10);
        let lease = Lease::<i32>::new(1, duration).unwrap();
        assert_eq!(lease.duration(), duration);
        assert_eq!(lease.holder(), 1);
    }

    #[test]
    fn test_map_domestic() {
        let s = Sovereign::new(10);
        let res = s.map(|x| x * 2);
        assert_eq!(res, Ok(20));
    }

    #[test]
    fn test_map_exiled() {
        let s = Sovereign::new(10);
        s.annex().unwrap();
        let res = s.map(|x| x * 2);
        assert_eq!(res, Err(SovereigntyError::ForeignJurisdiction));
    }

    #[test]
    fn test_and_then() {
        let s = Sovereign::new(10);
        let res = s.and_then(|x| {
            if *x > 5 {
                Ok(*x * 2)
            } else {
                Err(SovereigntyError::ForeignJurisdiction) // Just using this error for test
            }
        });
        assert_eq!(res, Ok(20));
    }

    #[test]
    fn test_filter() {
        let s = Sovereign::new(10);

        // Match
        let res1 = s.filter(|x| *x > 5);
        assert_eq!(res1, Ok(Some(&10)));

        // No match
        let res2 = s.filter(|x| *x < 5);
        assert_eq!(res2, Ok(None));

        // Exiled
        s.annex().unwrap();
        let res3 = s.filter(|x| *x > 5);
        assert_eq!(res3, Err(SovereigntyError::ForeignJurisdiction));
    }

    #[test]
    fn test_modify() {
        let mut s = Sovereign::new(10);
        s.modify(|x| *x += 1).unwrap();
        assert_eq!(*s, 11);

        s.annex().unwrap();
        let res = s.modify(|x| *x += 1);
        assert_eq!(res, Err(SovereigntyError::ForeignJurisdiction));
    }
}