Struct Sovereign 

pub struct Sovereign<T> { /* private fields */ }

A wrapper that enforces ownership semantics across network boundaries.

“Memory safety with sovereign integrity.”

Implementations

impl<T> Sovereign<T>

pub fn new(value: T) -> Self

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.

pub fn new_exiled(value: T) -> Self

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());

pub fn annex(&self) -> Result<(), AnnexError>

Annexes the resource, moving it to foreign jurisdiction.

Once annexed, the resource cannot be accessed locally. Access attempts will result in a Sovereignty Violation.

pub fn inner_ref(&self) -> &T

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 state(&self) -> SovereignState

Returns the current state of the resource.

pub fn is_domestic(&self) -> bool

Returns true if the resource is under domestic jurisdiction.

pub fn is_exiled(&self) -> bool

Returns true if the resource is under foreign jurisdiction (exiled).

pub fn try_get(&self) -> Result<&T, SovereigntyError>

Attempts to get a reference to the value, returning an error if Exiled.

pub fn try_get_mut(&mut self) -> Result<&mut T, SovereigntyError>

Attempts to get a mutable reference to the value, returning an error if Exiled.

pub fn repatriate(&self, token: RepatriationToken)

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());

pub fn map<F, U>(&self, f: F) -> Result<U, SovereigntyError>

where F: FnOnce(&T) -> U,

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 and_then<F, U>(&self, f: F) -> Result<U, SovereigntyError>

where F: FnOnce(&T) -> Result<U, SovereigntyError>,

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 filter<P>(&self, predicate: P) -> Result<Option<&T>, SovereigntyError>

where P: FnOnce(&T) -> bool,

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 modify<F>(&mut self, f: F) -> Result<(), SovereigntyError>

where F: FnOnce(&mut T),

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);

Trait Implementations

impl<T: Debug> Debug for Sovereign<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Deref for Sovereign<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for Sovereign<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T> DistributedBorrow<T> for Sovereign<T>

fn try_hire( &self, candidate_id: u128, term: Duration, ) -> Result<Lease<T>, LeaseError>

Attempt to acquire a lease on the resource.

impl<T: Send> Send for Sovereign<T>

impl<T: Sync> Sync for Sovereign<T>