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() };
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(&T) if domestic and predicate is true
• Err(ForeignJurisdiction) if exiled
• Ok with Error if predicate is false (wait, filter usually returns Option, but here we want to return Result<&T, Error>… likely usually returns Option<&T> in standard library, but we need to encode the Sovereignty error. Actually, standard filter returns Option. Let’s stick to the prompt: filter<P>(&self, predicate: P) -> Result<&T, SovereigntyError> This implies if predicate fails, maybe it should just return… what? Ah, filter on Option returns Option. If we follow the prompt strictly: “filter

  (&self, predicate: P) -> Result<&T, SovereigntyError>” If predicate is false, what happens? Usually filter retains if true. If false, it discards. If we return Result<&T, ...>, we can’t really express “discarded/None” easily without another error variant. However, user asked for Result<&T, SovereigntyError>. I will assume if predicate is false, it’s NOT an error, but… logic breakdown. Actually, maybe the user implies it acts like find? Or maybe they accept Result<Option<&T>, SovereigntyError>? The prompt signature is -> Result<&T, SovereigntyError>. This might mean if predicate is false, it’s considered an error? Or maybe I should return Result<Option<&T>, ...>? Let’s look at the prompt again. filter<P>(&self, predicate: P) -> Result<&T, SovereigntyError> If I enforce this signature, I have no way to say “predicate check failed” other than returning T (which is wrong) or Error. I’ll assume I should return Result<Option<&T>, SovereigntyError>, or if I must match the signature, maybe it returns the reference only if true, but what if false? Let’s implement Result<Option<&T>, SovereigntyError> as it is the most logical “Monadic” interpretation (Inner is T, mapped to Option). WAIT. The prompt EXPLICITLY says -> Result<&T, SovereigntyError>. That is very strange for a filter. Maybe it filters failures? No. I will implement Result<Option<&T>, SovereigntyError> and document why, or maybe Result<&T, SovereigntyError> where it errors if predicate false? Let’s assume the user meant Result<Option<&T>, SovereigntyError> or Option<&T> (but that loses the error). I will stick to best judgement: Result<Option<&T>, SovereigntyError>.

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>