Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/examples/exo-ai-2025/crates/exo-federation/src/coherent_commit.rs

@@ -0,0 +1,191 @@
+//! Coherent Commit — ADR-029 Phase 3 federation replacement.
+//!
+//! Replaces exo-federation's PBFT (O(n²) messages) with:
+//! 1. CoherenceRouter (sheaf Laplacian spectral gap check)
+//! 2. Raft-style log entry (replicated across federation nodes)
+//! 3. CrossParadigmWitness (unified audit chain)
+//!
+//! Retains: exo-federation's Kyber post-quantum channel setup.
+//! Replaces: PBFT consensus mechanism.
+//!
+//! Key improvement: O(n) message complexity vs O(n²) for PBFT,
+//! plus formal Type I error bounds from sheaf Laplacian gate.
+
+/// A federation state update (replaces PBFT Prepare/Promise/Commit messages)
+#[derive(Debug, Clone)]
+pub struct FederatedUpdate {
+    /// Unique update identifier
+    pub id: [u8; 32],
+    /// Log index (Raft-style monotonic)
+    pub log_index: u64,
+    /// Proposer node id
+    pub proposer: u32,
+    /// Update payload (serialized state delta)
+    pub payload: Vec<u8>,
+    /// Phi value at proposal time
+    pub phi: f64,
+    /// Coherence signal λ at proposal time
+    pub lambda: f64,
+}
+
+/// Federation node state (simplified Raft-style)
+#[derive(Debug, Clone)]
+pub struct FederationNode {
+    pub id: u32,
+    pub is_leader: bool,
+    /// Current log index
+    pub log_index: u64,
+    /// Committed log index
+    pub committed_index: u64,
+    /// Simulated peer count
+    pub peer_count: u32,
+}
+
+/// Result of a coherent commit
+#[derive(Debug, Clone)]
+pub struct CoherentCommitResult {
+    pub log_index: u64,
+    pub consensus_reached: bool,
+    pub votes_received: u32,
+    pub votes_needed: u32,
+    pub lambda_at_commit: f64,
+    pub phi_at_commit: f64,
+    pub witness_sequence: u64,
+    pub latency_us: u64,
+}
+
+impl FederationNode {
+    pub fn new(id: u32, peer_count: u32) -> Self {
+        Self {
+            id,
+            is_leader: id == 0,
+            log_index: 0,
+            committed_index: 0,
+            peer_count,
+        }
+    }
+
+    /// Propose and commit an update via coherence-gated consensus.
+    /// Replaces PBFT prepare/promise/commit with:
+    /// 1. Coherence gate check (spectral gap λ > threshold)
+    /// 2. Raft-style majority vote simulation
+    /// 3. Witness generation
+    pub fn coherent_commit(
+        &mut self,
+        update: &FederatedUpdate,
+    ) -> CoherentCommitResult {
+        use std::time::Instant;
+        let t0 = Instant::now();
+
+        // Step 1: Coherence gate — check structural stability before commit
+        // High lambda = structurally stable = safe to commit
+        let coherence_check = update.lambda > 0.1 && update.phi > 0.0;
+
+        // Step 2: Simulate Raft majority vote (O(n) messages vs PBFT O(n²))
+        let quorum = self.peer_count / 2 + 1;
+        // In simulation: votes = quorum if coherence OK, else minority
+        let votes = if coherence_check { quorum } else { quorum / 2 };
+        let consensus = votes >= quorum;
+
+        // Step 3: Commit if consensus reached
+        if consensus {
+            self.log_index += 1;
+            self.committed_index = self.log_index;
+        }
+
+        let latency_us = t0.elapsed().as_micros() as u64;
+
+        CoherentCommitResult {
+            log_index: self.log_index,
+            consensus_reached: consensus,
+            votes_received: votes,
+            votes_needed: quorum,
+            lambda_at_commit: update.lambda,
+            phi_at_commit: update.phi,
+            witness_sequence: self.committed_index,
+            latency_us,
+        }
+    }
+}
+
+/// Multi-node federation with coherent commit protocol
+pub struct CoherentFederation {
+    pub nodes: Vec<FederationNode>,
+    commit_history: Vec<CoherentCommitResult>,
+}
+
+impl CoherentFederation {
+    pub fn new(n_nodes: u32) -> Self {
+        let nodes = (0..n_nodes).map(|i| FederationNode::new(i, n_nodes)).collect();
+        Self { nodes, commit_history: Vec::new() }
+    }
+
+    /// Broadcast update to all nodes and collect results
+    pub fn broadcast_commit(&mut self, update: &FederatedUpdate) -> Vec<CoherentCommitResult> {
+        let results: Vec<CoherentCommitResult> = self.nodes.iter_mut()
+            .map(|node| node.coherent_commit(update))
+            .collect();
+        // Store leader result
+        if let Some(r) = results.first() {
+            self.commit_history.push(r.clone());
+        }
+        results
+    }
+
+    pub fn consensus_rate(&self) -> f64 {
+        if self.commit_history.is_empty() { return 0.0; }
+        let consensus_count = self.commit_history.iter().filter(|r| r.consensus_reached).count();
+        consensus_count as f64 / self.commit_history.len() as f64
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn test_update(lambda: f64, phi: f64) -> FederatedUpdate {
+        FederatedUpdate {
+            id: [0u8; 32], log_index: 0, proposer: 0,
+            payload: vec![1, 2, 3],
+            phi, lambda,
+        }
+    }
+
+    #[test]
+    fn test_coherent_commit_with_stable_state() {
+        let mut node = FederationNode::new(0, 5);
+        let update = test_update(0.8, 3.0); // High lambda + Phi → should commit
+        let result = node.coherent_commit(&update);
+        assert!(result.consensus_reached, "Stable state should reach consensus");
+        assert_eq!(result.log_index, 1);
+    }
+
+    #[test]
+    fn test_coherent_commit_blocked_low_lambda() {
+        let mut node = FederationNode::new(0, 5);
+        let update = test_update(0.02, 0.5); // Low lambda → may fail
+        let result = node.coherent_commit(&update);
+        // With low lambda, votes may not reach quorum
+        if !result.consensus_reached {
+            assert!(result.votes_received < result.votes_needed);
+        }
+    }
+
+    #[test]
+    fn test_federation_broadcast() {
+        let mut fed = CoherentFederation::new(5);
+        let update = test_update(0.7, 2.5);
+        let results = fed.broadcast_commit(&update);
+        assert_eq!(results.len(), 5);
+        assert!(fed.consensus_rate() > 0.0);
+    }
+
+    #[test]
+    fn test_raft_o_n_messages() {
+        // Verify O(n) message complexity: votes_needed = n/2 + 1
+        let node = FederationNode::new(0, 10);
+        assert_eq!(node.peer_count, 10);
+        let quorum = node.peer_count / 2 + 1; // = 6
+        assert_eq!(quorum, 6, "Raft quorum should be n/2 + 1");
+    }
+}

vendor/ruvector/examples/exo-ai-2025/crates/exo-federation/src/consensus.rs

@@ -0,0 +1,334 @@
+//! Byzantine fault-tolerant consensus
+//!
+//! Implements PBFT-style consensus for state updates across federation:
+//! - Pre-prepare phase
+//! - Prepare phase
+//! - Commit phase
+//! - Proof generation
+
+use crate::{FederationError, PeerId, Result, StateUpdate};
+use serde::{Deserialize, Serialize};
+
+/// Consensus message types
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum ConsensusMessage {
+    PrePrepare { proposal: SignedProposal },
+    Prepare { digest: Vec<u8>, sender: PeerId },
+    Commit { digest: Vec<u8>, sender: PeerId },
+}
+
+/// Signed proposal for a state update
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SignedProposal {
+    pub update: StateUpdate,
+    pub sequence_number: u64,
+    pub signature: Vec<u8>,
+}
+
+/// Proof that consensus was reached
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitProof {
+    pub update_id: String,
+    pub commit_messages: Vec<CommitMessage>,
+    pub timestamp: u64,
+}
+
+impl CommitProof {
+    /// Verify that proof contains sufficient commits
+    pub fn verify(&self, total_nodes: usize) -> bool {
+        let threshold = byzantine_threshold(total_nodes);
+        self.commit_messages.len() >= threshold
+    }
+}
+
+/// A commit message from a peer
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommitMessage {
+    pub peer_id: PeerId,
+    pub digest: Vec<u8>,
+    pub signature: Vec<u8>,
+}
+
+/// Result of a consensus attempt
+#[derive(Debug)]
+pub enum CommitResult {
+    Success(CommitProof),
+    InsufficientPrepares,
+    InsufficientCommits,
+}
+
+/// Calculate Byzantine fault threshold
+///
+/// For n = 3f + 1 nodes, we can tolerate f Byzantine faults.
+/// Consensus requires 2f + 1 = (2n + 2) / 3 agreements.
+fn byzantine_threshold(n: usize) -> usize {
+    (2 * n + 2) / 3
+}
+
+/// Execute Byzantine fault-tolerant consensus on a state update
+///
+/// # PBFT Protocol
+///
+/// 1. **Pre-prepare**: Leader proposes update
+/// 2. **Prepare**: Nodes acknowledge receipt (2f+1 required)
+/// 3. **Commit**: Nodes commit to proposal (2f+1 required)
+/// 4. **Execute**: Update is applied with proof
+///
+/// # Implementation from PSEUDOCODE.md
+///
+/// ```pseudocode
+/// FUNCTION ByzantineCommit(update, federation):
+///     n = federation.node_count()
+///     f = (n - 1) / 3
+///     threshold = 2*f + 1
+///
+///     // Phase 1: Pre-prepare
+///     IF federation.is_leader():
+///         proposal = SignedProposal(update, sequence_number=NEXT_SEQ)
+///         Broadcast(federation.nodes, PrePrepare(proposal))
+///
+///     // Phase 2: Prepare
+///     pre_prepare = ReceivePrePrepare()
+///     IF ValidateProposal(pre_prepare):
+///         prepare_msg = Prepare(pre_prepare.digest, local_id)
+///         Broadcast(federation.nodes, prepare_msg)
+///
+///     prepares = CollectMessages(type=Prepare, count=threshold)
+///     IF len(prepares) < threshold:
+///         RETURN InsufficientPrepares
+///
+///     // Phase 3: Commit
+///     commit_msg = Commit(pre_prepare.digest, local_id)
+///     Broadcast(federation.nodes, commit_msg)
+///
+///     commits = CollectMessages(type=Commit, count=threshold)
+///     IF len(commits) >= threshold:
+///         federation.apply_update(update)
+///         proof = CommitProof(commits)
+///         RETURN Success(proof)
+///     ELSE:
+///         RETURN InsufficientCommits
+/// ```
+pub async fn byzantine_commit(update: StateUpdate, peer_count: usize) -> Result<CommitProof> {
+    let n = peer_count;
+    let f = if n > 0 { (n - 1) / 3 } else { 0 };
+    let threshold = 2 * f + 1;
+
+    if n < 4 {
+        return Err(FederationError::InsufficientPeers {
+            needed: 4,
+            actual: n,
+        });
+    }
+
+    // Phase 1: Pre-prepare (leader proposes)
+    let sequence_number = get_next_sequence_number();
+    let proposal = SignedProposal {
+        update: update.clone(),
+        sequence_number,
+        signature: sign_proposal(&update),
+    };
+
+    // Broadcast pre-prepare (simulated)
+    let _pre_prepare = ConsensusMessage::PrePrepare {
+        proposal: proposal.clone(),
+    };
+
+    // Phase 2: Prepare (nodes acknowledge)
+    let digest = compute_digest(&update);
+
+    // Simulate collecting prepare messages from peers
+    let prepares = simulate_prepare_phase(&digest, threshold)?;
+
+    if prepares.len() < threshold {
+        return Err(FederationError::ConsensusError(format!(
+            "Insufficient prepares: got {}, needed {}",
+            prepares.len(),
+            threshold
+        )));
+    }
+
+    // Phase 3: Commit (nodes commit)
+    let commit_messages = simulate_commit_phase(&digest, threshold)?;
+
+    if commit_messages.len() < threshold {
+        return Err(FederationError::ConsensusError(format!(
+            "Insufficient commits: got {}, needed {}",
+            commit_messages.len(),
+            threshold
+        )));
+    }
+
+    // Create proof
+    let proof = CommitProof {
+        update_id: update.update_id.clone(),
+        commit_messages,
+        timestamp: current_timestamp(),
+    };
+
+    // Verify proof
+    if !proof.verify(n) {
+        return Err(FederationError::ConsensusError(
+            "Proof verification failed".to_string(),
+        ));
+    }
+
+    Ok(proof)
+}
+
+/// Compute digest of a state update
+fn compute_digest(update: &StateUpdate) -> Vec<u8> {
+    use sha2::{Digest, Sha256};
+    let mut hasher = Sha256::new();
+    hasher.update(&update.update_id);
+    hasher.update(&update.data);
+    hasher.update(&update.timestamp.to_le_bytes());
+    hasher.finalize().to_vec()
+}
+
+/// Sign a proposal (placeholder)
+fn sign_proposal(update: &StateUpdate) -> Vec<u8> {
+    use sha2::{Digest, Sha256};
+    let mut hasher = Sha256::new();
+    hasher.update(b"signature:");
+    hasher.update(&update.update_id);
+    hasher.finalize().to_vec()
+}
+
+/// Get next sequence number (placeholder)
+fn get_next_sequence_number() -> u64 {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static COUNTER: AtomicU64 = AtomicU64::new(1);
+    COUNTER.fetch_add(1, Ordering::SeqCst)
+}
+
+/// Simulate prepare phase (placeholder for network communication)
+fn simulate_prepare_phase(digest: &[u8], threshold: usize) -> Result<Vec<(PeerId, Vec<u8>)>> {
+    let mut prepares = Vec::new();
+
+    // Simulate receiving prepare messages from peers
+    for i in 0..threshold {
+        let peer_id = PeerId::new(format!("peer_{}", i));
+        prepares.push((peer_id, digest.to_vec()));
+    }
+
+    Ok(prepares)
+}
+
+/// Simulate commit phase (placeholder for network communication)
+fn simulate_commit_phase(digest: &[u8], threshold: usize) -> Result<Vec<CommitMessage>> {
+    let mut commits = Vec::new();
+
+    // Simulate receiving commit messages from peers
+    for i in 0..threshold {
+        let peer_id = PeerId::new(format!("peer_{}", i));
+        let signature = sign_commit(digest, &peer_id);
+
+        commits.push(CommitMessage {
+            peer_id,
+            digest: digest.to_vec(),
+            signature,
+        });
+    }
+
+    Ok(commits)
+}
+
+/// Sign a commit message (placeholder)
+fn sign_commit(digest: &[u8], peer_id: &PeerId) -> Vec<u8> {
+    use sha2::{Digest, Sha256};
+    let mut hasher = Sha256::new();
+    hasher.update(b"commit:");
+    hasher.update(digest);
+    hasher.update(peer_id.0.as_bytes());
+    hasher.finalize().to_vec()
+}
+
+/// Get current timestamp
+fn current_timestamp() -> u64 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_millis() as u64
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_byzantine_commit_success() {
+        let update = StateUpdate {
+            update_id: "test_update_1".to_string(),
+            data: vec![1, 2, 3, 4],
+            timestamp: current_timestamp(),
+        };
+
+        // Need at least 4 nodes for BFT (n = 3f + 1, f = 1)
+        let proof = byzantine_commit(update, 4).await.unwrap();
+
+        assert!(proof.verify(4));
+        assert_eq!(proof.update_id, "test_update_1");
+    }
+
+    #[tokio::test]
+    async fn test_byzantine_commit_insufficient_peers() {
+        let update = StateUpdate {
+            update_id: "test_update_2".to_string(),
+            data: vec![1, 2, 3],
+            timestamp: current_timestamp(),
+        };
+
+        // Only 3 nodes - not enough for BFT
+        let result = byzantine_commit(update, 3).await;
+
+        assert!(result.is_err());
+        match result {
+            Err(FederationError::InsufficientPeers { needed, actual }) => {
+                assert_eq!(needed, 4);
+                assert_eq!(actual, 3);
+            }
+            _ => panic!("Expected InsufficientPeers error"),
+        }
+    }
+
+    #[test]
+    fn test_byzantine_threshold() {
+        // n = 3f + 1, threshold = 2f + 1
+        assert_eq!(byzantine_threshold(4), 3); // f=1, 2f+1=3
+        assert_eq!(byzantine_threshold(7), 5); // f=2, 2f+1=5
+        assert_eq!(byzantine_threshold(10), 7); // f=3, 2f+1=7
+    }
+
+    #[test]
+    fn test_commit_proof_verification() {
+        let proof = CommitProof {
+            update_id: "test".to_string(),
+            commit_messages: vec![
+                CommitMessage {
+                    peer_id: PeerId::new("peer1".to_string()),
+                    digest: vec![1, 2, 3],
+                    signature: vec![4, 5, 6],
+                },
+                CommitMessage {
+                    peer_id: PeerId::new("peer2".to_string()),
+                    digest: vec![1, 2, 3],
+                    signature: vec![7, 8, 9],
+                },
+                CommitMessage {
+                    peer_id: PeerId::new("peer3".to_string()),
+                    digest: vec![1, 2, 3],
+                    signature: vec![10, 11, 12],
+                },
+            ],
+            timestamp: current_timestamp(),
+        };
+
+        // For 4 nodes, need 3 commits
+        assert!(proof.verify(4));
+
+        // For 7 nodes, would need 5 commits
+        assert!(!proof.verify(7));
+    }
+}

vendor/ruvector/examples/exo-ai-2025/crates/exo-federation/src/crdt.rs

@@ -0,0 +1,323 @@
+//! Conflict-Free Replicated Data Types (CRDTs)
+//!
+//! Implements CRDTs for eventual consistency across federation:
+//! - G-Set (Grow-only Set)
+//! - LWW-Register (Last-Writer-Wins Register)
+//! - Reconciliation algorithms
+
+use crate::Result;
+use serde::{Deserialize, Serialize};
+use std::collections::{HashMap, HashSet};
+
+/// Grow-only Set CRDT
+///
+/// A set that only supports additions. Merge is simply union.
+/// This is useful for accumulating search results from multiple peers.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GSet<T: Eq + std::hash::Hash + Clone> {
+    elements: HashSet<T>,
+}
+
+impl<T: Eq + std::hash::Hash + Clone> GSet<T> {
+    /// Create a new empty G-Set
+    pub fn new() -> Self {
+        Self {
+            elements: HashSet::new(),
+        }
+    }
+
+    /// Add an element to the set
+    pub fn add(&mut self, element: T) {
+        self.elements.insert(element);
+    }
+
+    /// Check if set contains element
+    pub fn contains(&self, element: &T) -> bool {
+        self.elements.contains(element)
+    }
+
+    /// Get all elements
+    pub fn elements(&self) -> impl Iterator<Item = &T> {
+        self.elements.iter()
+    }
+
+    /// Get the size of the set
+    pub fn len(&self) -> usize {
+        self.elements.len()
+    }
+
+    /// Check if set is empty
+    pub fn is_empty(&self) -> bool {
+        self.elements.is_empty()
+    }
+
+    /// Merge with another G-Set
+    ///
+    /// G-Set merge is simply the union of both sets.
+    /// This operation is:
+    /// - Commutative: merge(A, B) = merge(B, A)
+    /// - Associative: merge(merge(A, B), C) = merge(A, merge(B, C))
+    /// - Idempotent: merge(A, A) = A
+    pub fn merge(&mut self, other: &GSet<T>) {
+        for element in &other.elements {
+            self.elements.insert(element.clone());
+        }
+    }
+}
+
+impl<T: Eq + std::hash::Hash + Clone> Default for GSet<T> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Last-Writer-Wins Register CRDT
+///
+/// A register that resolves conflicts by timestamp.
+/// The value with the highest timestamp wins.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LWWRegister<T: Clone> {
+    value: T,
+    timestamp: u64,
+}
+
+impl<T: Clone> LWWRegister<T> {
+    /// Create a new LWW-Register with initial value
+    pub fn new(value: T, timestamp: u64) -> Self {
+        Self { value, timestamp }
+    }
+
+    /// Set a new value with timestamp
+    pub fn set(&mut self, value: T, timestamp: u64) {
+        if timestamp > self.timestamp {
+            self.value = value;
+            self.timestamp = timestamp;
+        }
+    }
+
+    /// Get the current value
+    pub fn get(&self) -> &T {
+        &self.value
+    }
+
+    /// Get the timestamp
+    pub fn timestamp(&self) -> u64 {
+        self.timestamp
+    }
+
+    /// Merge with another LWW-Register
+    ///
+    /// The register with the higher timestamp wins.
+    /// If timestamps are equal, we need a tie-breaker (e.g., node ID).
+    pub fn merge(&mut self, other: &LWWRegister<T>) {
+        if other.timestamp > self.timestamp {
+            self.value = other.value.clone();
+            self.timestamp = other.timestamp;
+        }
+    }
+}
+
+/// Last-Writer-Wins Map CRDT
+///
+/// A map where each key has an LWW-Register value.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LWWMap<K: Eq + std::hash::Hash + Clone, V: Clone> {
+    entries: HashMap<K, LWWRegister<V>>,
+}
+
+impl<K: Eq + std::hash::Hash + Clone, V: Clone> LWWMap<K, V> {
+    /// Create a new LWW-Map
+    pub fn new() -> Self {
+        Self {
+            entries: HashMap::new(),
+        }
+    }
+
+    /// Set a value with timestamp
+    pub fn set(&mut self, key: K, value: V, timestamp: u64) {
+        self.entries
+            .entry(key)
+            .and_modify(|reg| reg.set(value.clone(), timestamp))
+            .or_insert_with(|| LWWRegister::new(value, timestamp));
+    }
+
+    /// Get a value
+    pub fn get(&self, key: &K) -> Option<&V> {
+        self.entries.get(key).map(|reg| reg.get())
+    }
+
+    /// Get all entries
+    pub fn entries(&self) -> impl Iterator<Item = (&K, &V)> {
+        self.entries.iter().map(|(k, reg)| (k, reg.get()))
+    }
+
+    /// Merge with another LWW-Map
+    pub fn merge(&mut self, other: &LWWMap<K, V>) {
+        for (key, other_reg) in &other.entries {
+            self.entries
+                .entry(key.clone())
+                .and_modify(|reg| reg.merge(other_reg))
+                .or_insert_with(|| other_reg.clone());
+        }
+    }
+}
+
+impl<K: Eq + std::hash::Hash + Clone, V: Clone> Default for LWWMap<K, V> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+/// Federated query response
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FederatedResponse<T: Clone> {
+    pub results: Vec<T>,
+    pub rankings: Vec<(String, f32, u64)>, // (id, score, timestamp)
+}
+
+/// Reconcile CRDT data from multiple federated responses
+///
+/// # Implementation from PSEUDOCODE.md
+///
+/// ```pseudocode
+/// FUNCTION ReconcileCRDT(responses, local_state):
+///     merged_results = GSet()
+///     FOR response IN responses:
+///         FOR result IN response.results:
+///             merged_results.add(result)
+///
+///     ranking_map = LWWMap()
+///     FOR response IN responses:
+///         FOR (result_id, score, timestamp) IN response.rankings:
+///             ranking_map.set(result_id, score, timestamp)
+///
+///     final_results = []
+///     FOR result IN merged_results:
+///         score = ranking_map.get(result.id)
+///         final_results.append((result, score))
+///
+///     final_results.sort(by=score, descending=True)
+///     RETURN final_results
+/// ```
+pub fn reconcile_crdt<T>(responses: Vec<FederatedResponse<T>>) -> Result<Vec<(T, f32)>>
+where
+    T: Clone + Eq + std::hash::Hash + std::fmt::Display,
+{
+    // Step 1: Merge all results using G-Set
+    let mut merged_results = GSet::new();
+    for response in &responses {
+        for result in &response.results {
+            merged_results.add(result.clone());
+        }
+    }
+
+    // Step 2: Merge rankings using LWW-Map
+    let mut ranking_map = LWWMap::new();
+    for response in &responses {
+        for (result_id, score, timestamp) in &response.rankings {
+            ranking_map.set(result_id.clone(), *score, *timestamp);
+        }
+    }
+
+    // Step 3: Combine results with their scores (look up by Display representation)
+    let mut final_results: Vec<(T, f32)> = merged_results
+        .elements()
+        .map(|result| {
+            let key = format!("{}", result);
+            let score = ranking_map.get(&key).copied().unwrap_or(0.5);
+            (result.clone(), score)
+        })
+        .collect();
+
+    // Step 4: Sort by score descending
+    final_results.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap());
+
+    Ok(final_results)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_gset() {
+        let mut set1 = GSet::new();
+        set1.add(1);
+        set1.add(2);
+
+        let mut set2 = GSet::new();
+        set2.add(2);
+        set2.add(3);
+
+        set1.merge(&set2);
+
+        assert_eq!(set1.len(), 3);
+        assert!(set1.contains(&1));
+        assert!(set1.contains(&2));
+        assert!(set1.contains(&3));
+    }
+
+    #[test]
+    fn test_gset_idempotent() {
+        let mut set1 = GSet::new();
+        set1.add(1);
+        set1.add(2);
+
+        let set2 = set1.clone();
+        set1.merge(&set2);
+
+        assert_eq!(set1.len(), 2);
+    }
+
+    #[test]
+    fn test_lww_register() {
+        let mut reg1 = LWWRegister::new(100, 1);
+        let reg2 = LWWRegister::new(200, 2);
+
+        reg1.merge(&reg2);
+        assert_eq!(*reg1.get(), 200);
+
+        // Older timestamp should not override
+        let reg3 = LWWRegister::new(300, 1);
+        reg1.merge(&reg3);
+        assert_eq!(*reg1.get(), 200);
+    }
+
+    #[test]
+    fn test_lww_map() {
+        let mut map1 = LWWMap::new();
+        map1.set("key1", 100, 1);
+        map1.set("key2", 200, 1);
+
+        let mut map2 = LWWMap::new();
+        map2.set("key2", 250, 2); // Newer timestamp
+        map2.set("key3", 300, 1);
+
+        map1.merge(&map2);
+
+        assert_eq!(*map1.get(&"key1").unwrap(), 100);
+        assert_eq!(*map1.get(&"key2").unwrap(), 250); // Updated
+        assert_eq!(*map1.get(&"key3").unwrap(), 300);
+    }
+
+    #[test]
+    fn test_reconcile_crdt() {
+        let response1 = FederatedResponse {
+            results: vec![1, 2, 3],
+            rankings: vec![("1".to_string(), 0.9, 100), ("2".to_string(), 0.8, 100)],
+        };
+
+        let response2 = FederatedResponse {
+            results: vec![2, 3, 4],
+            rankings: vec![
+                ("2".to_string(), 0.85, 101), // Newer
+                ("3".to_string(), 0.7, 100),
+            ],
+        };
+
+        let reconciled = reconcile_crdt(vec![response1, response2]).unwrap();
+
+        // Should have all unique results
+        assert_eq!(reconciled.len(), 4);
+    }
+}

vendor/ruvector/examples/exo-ai-2025/crates/exo-federation/src/crypto.rs

@@ -0,0 +1,613 @@
+//! Post-quantum cryptography primitives
+//!
+//! This module provides cryptographic primitives for federation security:
+//! - CRYSTALS-Kyber-1024 key exchange (NIST FIPS 203)
+//! - ChaCha20-Poly1305 AEAD encryption
+//! - HKDF-SHA256 key derivation
+//! - Constant-time operations
+//! - Secure memory zeroization
+//!
+//! # Security Level
+//!
+//! All primitives provide 256-bit classical security and 128+ bit post-quantum security.
+//!
+//! # Threat Model
+//!
+//! See /docs/SECURITY.md for comprehensive threat model and security architecture.
+
+use crate::{FederationError, Result};
+use serde::{Deserialize, Serialize};
+use zeroize::{Zeroize, ZeroizeOnDrop};
+
+// Re-export for convenience
+pub use pqcrypto_kyber::kyber1024;
+use pqcrypto_traits::kem::{Ciphertext, PublicKey, SecretKey, SharedSecret as PqSharedSecret};
+
+/// Post-quantum cryptographic keypair
+///
+/// Uses CRYSTALS-Kyber-1024 for IND-CCA2 secure key encapsulation.
+///
+/// # Security Properties
+///
+/// - Public key: 1568 bytes (safe to distribute)
+/// - Secret key: 3168 bytes (MUST be protected, auto-zeroized on drop)
+/// - Post-quantum security: 256 bits (NIST Level 5)
+///
+/// # Example
+///
+/// ```ignore
+/// let keypair = PostQuantumKeypair::generate();
+/// let public_bytes = keypair.public_key();
+/// // Send public_bytes to peer
+/// ```
+#[derive(Clone)]
+pub struct PostQuantumKeypair {
+    /// Public key (safe to share)
+    pub public: Vec<u8>,
+    /// Secret key (automatically zeroized on drop)
+    secret: SecretKeyWrapper,
+}
+
+impl std::fmt::Debug for PostQuantumKeypair {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("PostQuantumKeypair")
+            .field("public", &format!("{}bytes", self.public.len()))
+            .field("secret", &"[REDACTED]")
+            .finish()
+    }
+}
+
+/// Wrapper for secret key with automatic zeroization
+#[derive(Clone, Zeroize, ZeroizeOnDrop)]
+struct SecretKeyWrapper(Vec<u8>);
+
+impl PostQuantumKeypair {
+    /// Generate a new post-quantum keypair using CRYSTALS-Kyber-1024
+    ///
+    /// # Security
+    ///
+    /// Uses OS CSPRNG (via `rand::thread_rng()`). Ensure OS has sufficient entropy.
+    ///
+    /// # Panics
+    ///
+    /// Never panics. Kyber key generation is deterministic after RNG sampling.
+    pub fn generate() -> Self {
+        let (public, secret) = kyber1024::keypair();
+
+        Self {
+            public: public.as_bytes().to_vec(),
+            secret: SecretKeyWrapper(secret.as_bytes().to_vec()),
+        }
+    }
+
+    /// Get the public key bytes
+    ///
+    /// Safe to transmit over insecure channels.
+    pub fn public_key(&self) -> &[u8] {
+        &self.public
+    }
+
+    /// Encapsulate: generate shared secret and ciphertext for recipient's public key
+    ///
+    /// # Arguments
+    ///
+    /// * `public_key` - Recipient's Kyber-1024 public key (1568 bytes)
+    ///
+    /// # Returns
+    ///
+    /// * `SharedSecret` - 32-byte shared secret (use for key derivation)
+    /// * `Vec<u8>` - 1568-byte ciphertext (send to recipient)
+    ///
+    /// # Errors
+    ///
+    /// Returns `CryptoError` if public key is invalid (wrong size or corrupted).
+    ///
+    /// # Security
+    ///
+    /// The shared secret is cryptographically strong (256-bit entropy).
+    /// The ciphertext is IND-CCA2 secure against quantum adversaries.
+    pub fn encapsulate(public_key: &[u8]) -> Result<(SharedSecret, Vec<u8>)> {
+        // Validate public key size (Kyber1024 = 1568 bytes)
+        if public_key.len() != 1568 {
+            return Err(FederationError::CryptoError(format!(
+                "Invalid public key size: expected 1568 bytes, got {}",
+                public_key.len()
+            )));
+        }
+
+        // Parse public key
+        let pk = kyber1024::PublicKey::from_bytes(public_key).map_err(|e| {
+            FederationError::CryptoError(format!("Failed to parse Kyber public key: {:?}", e))
+        })?;
+
+        // Perform KEM encapsulation
+        let (shared_secret, ciphertext) = kyber1024::encapsulate(&pk);
+
+        Ok((
+            SharedSecret(SecretBytes(shared_secret.as_bytes().to_vec())),
+            ciphertext.as_bytes().to_vec(),
+        ))
+    }
+
+    /// Decapsulate: extract shared secret from ciphertext
+    ///
+    /// # Arguments
+    ///
+    /// * `ciphertext` - 1568-byte Kyber-1024 ciphertext
+    ///
+    /// # Returns
+    ///
+    /// * `SharedSecret` - 32-byte shared secret (same as encapsulator's)
+    ///
+    /// # Errors
+    ///
+    /// Returns `CryptoError` if:
+    /// - Ciphertext is wrong size
+    /// - Ciphertext is invalid or corrupted
+    /// - Decapsulation fails (should never happen with valid inputs)
+    ///
+    /// # Security
+    ///
+    /// Timing-safe: execution time independent of secret key or ciphertext validity.
+    pub fn decapsulate(&self, ciphertext: &[u8]) -> Result<SharedSecret> {
+        // Validate ciphertext size
+        if ciphertext.len() != 1568 {
+            return Err(FederationError::CryptoError(format!(
+                "Invalid ciphertext size: expected 1568 bytes, got {}",
+                ciphertext.len()
+            )));
+        }
+
+        // Parse secret key
+        let sk = kyber1024::SecretKey::from_bytes(&self.secret.0).map_err(|e| {
+            FederationError::CryptoError(format!("Failed to parse secret key: {:?}", e))
+        })?;
+
+        // Parse ciphertext
+        let ct = kyber1024::Ciphertext::from_bytes(ciphertext).map_err(|e| {
+            FederationError::CryptoError(format!("Failed to parse Kyber ciphertext: {:?}", e))
+        })?;
+
+        // Perform KEM decapsulation
+        let shared_secret = kyber1024::decapsulate(&ct, &sk);
+
+        Ok(SharedSecret(SecretBytes(shared_secret.as_bytes().to_vec())))
+    }
+}
+
+/// Secret bytes wrapper with automatic zeroization
+#[derive(Clone, Zeroize, ZeroizeOnDrop)]
+struct SecretBytes(Vec<u8>);
+
+/// Shared secret derived from Kyber KEM
+///
+/// # Security
+///
+/// - Automatically zeroized on drop
+/// - 32 bytes of cryptographically strong key material
+/// - Suitable for HKDF key derivation
+#[derive(Clone, Zeroize, ZeroizeOnDrop)]
+pub struct SharedSecret(SecretBytes);
+
+impl std::fmt::Debug for SharedSecret {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("SharedSecret")
+            .field("bytes", &"[REDACTED]")
+            .finish()
+    }
+}
+
+impl SharedSecret {
+    /// Derive encryption and MAC keys from shared secret using HKDF-SHA256
+    ///
+    /// # Key Derivation
+    ///
+    /// ```text
+    /// shared_secret (32 bytes from Kyber)
+    ///     ↓
+    /// HKDF-Extract(salt=zeros, ikm=shared_secret) → PRK
+    ///     ↓
+    /// HKDF-Expand(PRK, info="encryption") → encryption_key (32 bytes)
+    /// HKDF-Expand(PRK, info="mac") → mac_key (32 bytes)
+    /// ```
+    ///
+    /// # Returns
+    ///
+    /// - Encryption key: 256-bit key for ChaCha20
+    /// - MAC key: 256-bit key for Poly1305
+    ///
+    /// # Security
+    ///
+    /// Keys are cryptographically independent. Compromise of one does not affect the other.
+    pub fn derive_keys(&self) -> (Vec<u8>, Vec<u8>) {
+        use hmac::{Hmac, Mac};
+        use sha2::Sha256;
+
+        type HmacSha256 = Hmac<Sha256>;
+
+        // HKDF-Extract: PRK = HMAC-SHA256(salt=zeros, ikm=shared_secret)
+        let salt = [0u8; 32]; // Zero salt is acceptable for Kyber output
+        let mut extract_hmac =
+            HmacSha256::new_from_slice(&salt).expect("HMAC-SHA256 accepts any key size");
+        extract_hmac.update(&self.0 .0);
+        let prk = extract_hmac.finalize().into_bytes();
+
+        // HKDF-Expand for encryption key
+        let mut enc_hmac = HmacSha256::new_from_slice(&prk).expect("PRK is valid HMAC key");
+        enc_hmac.update(b"encryption");
+        enc_hmac.update(&[1u8]); // Counter = 1
+        let encrypt_key = enc_hmac.finalize().into_bytes().to_vec();
+
+        // HKDF-Expand for MAC key
+        let mut mac_hmac = HmacSha256::new_from_slice(&prk).expect("PRK is valid HMAC key");
+        mac_hmac.update(b"mac");
+        mac_hmac.update(&[1u8]); // Counter = 1
+        let mac_key = mac_hmac.finalize().into_bytes().to_vec();
+
+        (encrypt_key, mac_key)
+    }
+}
+
+/// Encrypted communication channel using ChaCha20-Poly1305 AEAD
+///
+/// # Security Properties
+///
+/// - Confidentiality: ChaCha20 stream cipher (IND-CPA)
+/// - Integrity: Poly1305 MAC (SUF-CMA)
+/// - AEAD: Combined mode (IND-CCA2)
+/// - Nonce: 96-bit random + 32-bit counter (unique per message)
+///
+/// # Example
+///
+/// ```ignore
+/// let channel = EncryptedChannel::new(peer_id, shared_secret);
+/// let ciphertext = channel.encrypt(b"secret message")?;
+/// let plaintext = channel.decrypt(&ciphertext)?;
+/// ```
+#[derive(Debug, Serialize, Deserialize)]
+pub struct EncryptedChannel {
+    /// Peer identifier
+    pub peer_id: String,
+    /// Encryption key (not serialized - ephemeral)
+    #[serde(skip)]
+    encrypt_key: Vec<u8>,
+    /// MAC key for authentication (not serialized - ephemeral)
+    #[serde(skip)]
+    mac_key: Vec<u8>,
+    /// Message counter for nonce generation
+    #[serde(skip)]
+    counter: std::sync::atomic::AtomicU32,
+}
+
+impl Clone for EncryptedChannel {
+    fn clone(&self) -> Self {
+        Self {
+            peer_id: self.peer_id.clone(),
+            encrypt_key: self.encrypt_key.clone(),
+            mac_key: self.mac_key.clone(),
+            counter: std::sync::atomic::AtomicU32::new(
+                self.counter.load(std::sync::atomic::Ordering::SeqCst),
+            ),
+        }
+    }
+}
+
+impl EncryptedChannel {
+    /// Create a new encrypted channel from a shared secret
+    ///
+    /// # Arguments
+    ///
+    /// * `peer_id` - Identifier for the peer (for auditing/logging)
+    /// * `shared_secret` - Shared secret from Kyber KEM
+    ///
+    /// # Security
+    ///
+    /// Keys are derived using HKDF-SHA256 with domain separation.
+    pub fn new(peer_id: String, shared_secret: SharedSecret) -> Self {
+        let (encrypt_key, mac_key) = shared_secret.derive_keys();
+
+        Self {
+            peer_id,
+            encrypt_key,
+            mac_key,
+            counter: std::sync::atomic::AtomicU32::new(0),
+        }
+    }
+
+    /// Encrypt a message using ChaCha20-Poly1305
+    ///
+    /// # Arguments
+    ///
+    /// * `plaintext` - Message to encrypt
+    ///
+    /// # Returns
+    ///
+    /// Ciphertext format: `[nonce: 12 bytes][ciphertext][tag: 16 bytes]`
+    ///
+    /// # Errors
+    ///
+    /// Returns `CryptoError` if encryption fails (should never happen).
+    ///
+    /// # Security
+    ///
+    /// - Unique nonce per message (96-bit random + 32-bit counter)
+    /// - Authenticated encryption (modify ciphertext = detection)
+    /// - Quantum resistance: 128-bit security (Grover bound)
+    pub fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>> {
+        use chacha20poly1305::{
+            aead::{Aead, KeyInit},
+            ChaCha20Poly1305, Nonce,
+        };
+
+        // Create cipher instance
+        let key_array: [u8; 32] = self
+            .encrypt_key
+            .as_slice()
+            .try_into()
+            .map_err(|_| FederationError::CryptoError("Invalid key size".into()))?;
+        let cipher = ChaCha20Poly1305::new(&key_array.into());
+
+        // Generate unique nonce: [random: 8 bytes][counter: 4 bytes]
+        let mut nonce_bytes = [0u8; 12];
+        nonce_bytes[0..8].copy_from_slice(&rand::random::<[u8; 8]>());
+        let counter = self
+            .counter
+            .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+        nonce_bytes[8..12].copy_from_slice(&counter.to_le_bytes());
+        let nonce = Nonce::from_slice(&nonce_bytes);
+
+        // Encrypt with AEAD
+        let ciphertext = cipher.encrypt(nonce, plaintext).map_err(|e| {
+            FederationError::CryptoError(format!("ChaCha20-Poly1305 encryption failed: {}", e))
+        })?;
+
+        // Prepend nonce to ciphertext (needed for decryption)
+        let mut result = nonce_bytes.to_vec();
+        result.extend_from_slice(&ciphertext);
+
+        Ok(result)
+    }
+
+    /// Decrypt a message using ChaCha20-Poly1305
+    ///
+    /// # Arguments
+    ///
+    /// * `ciphertext` - Encrypted message (format: `[nonce: 12][ciphertext][tag: 16]`)
+    ///
+    /// # Returns
+    ///
+    /// Decrypted plaintext
+    ///
+    /// # Errors
+    ///
+    /// Returns `CryptoError` if:
+    /// - Ciphertext is too short (< 28 bytes)
+    /// - Authentication tag verification fails (tampering detected)
+    /// - Decryption fails
+    ///
+    /// # Security
+    ///
+    /// - **Constant-time**: Timing independent of plaintext content
+    /// - **Tamper-evident**: Any modification causes authentication failure
+    pub fn decrypt(&self, ciphertext: &[u8]) -> Result<Vec<u8>> {
+        use chacha20poly1305::{
+            aead::{Aead, KeyInit},
+            ChaCha20Poly1305, Nonce,
+        };
+
+        // Validate minimum size: nonce(12) + tag(16) = 28 bytes
+        if ciphertext.len() < 28 {
+            return Err(FederationError::CryptoError(format!(
+                "Ciphertext too short: {} bytes (minimum 28)",
+                ciphertext.len()
+            )));
+        }
+
+        // Extract nonce and ciphertext
+        let (nonce_bytes, ct) = ciphertext.split_at(12);
+        let nonce = Nonce::from_slice(nonce_bytes);
+
+        // Create cipher instance
+        let key_array: [u8; 32] = self
+            .encrypt_key
+            .as_slice()
+            .try_into()
+            .map_err(|_| FederationError::CryptoError("Invalid key size".into()))?;
+        let cipher = ChaCha20Poly1305::new(&key_array.into());
+
+        // Decrypt with AEAD (authentication happens here)
+        let plaintext = cipher.decrypt(nonce, ct).map_err(|e| {
+            FederationError::CryptoError(format!(
+                "ChaCha20-Poly1305 decryption failed (tampering?): {}",
+                e
+            ))
+        })?;
+
+        Ok(plaintext)
+    }
+
+    /// Sign a message with HMAC-SHA256
+    ///
+    /// # Arguments
+    ///
+    /// * `message` - Message to authenticate
+    ///
+    /// # Returns
+    ///
+    /// 32-byte HMAC tag
+    ///
+    /// # Security
+    ///
+    /// - PRF security: tag reveals nothing about key
+    /// - Quantum resistance: 128-bit security (Grover)
+    ///
+    /// # Note
+    ///
+    /// If using `encrypt()`, signatures are redundant (Poly1305 provides authentication).
+    /// Use this for non-encrypted authenticated messages.
+    pub fn sign(&self, message: &[u8]) -> Vec<u8> {
+        use hmac::{Hmac, Mac};
+        use sha2::Sha256;
+
+        let mut mac = Hmac::<Sha256>::new_from_slice(&self.mac_key)
+            .expect("HMAC-SHA256 accepts any key size");
+        mac.update(message);
+        mac.finalize().into_bytes().to_vec()
+    }
+
+    /// Verify a message signature using constant-time comparison
+    ///
+    /// # Arguments
+    ///
+    /// * `message` - Original message
+    /// * `signature` - HMAC tag to verify
+    ///
+    /// # Returns
+    ///
+    /// `true` if signature is valid, `false` otherwise
+    ///
+    /// # Security
+    ///
+    /// - **Constant-time**: Execution time independent of signature validity
+    /// - **Timing-attack resistant**: No early termination on mismatch
+    ///
+    /// # Critical Security Property
+    ///
+    /// This function MUST use constant-time comparison to prevent timing side-channels.
+    pub fn verify(&self, message: &[u8], signature: &[u8]) -> bool {
+        use subtle::ConstantTimeEq;
+
+        let expected = self.sign(message);
+
+        // Constant-time comparison (critical for security)
+        if expected.len() != signature.len() {
+            return false;
+        }
+
+        expected.ct_eq(signature).into()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_keypair_generation() {
+        let keypair = PostQuantumKeypair::generate();
+        assert_eq!(keypair.public.len(), 1568); // Kyber-1024 public key size
+    }
+
+    #[test]
+    fn test_key_exchange() {
+        let alice = PostQuantumKeypair::generate();
+        let bob = PostQuantumKeypair::generate();
+
+        // Alice encapsulates to Bob
+        let (alice_secret, ciphertext) = PostQuantumKeypair::encapsulate(bob.public_key()).unwrap();
+
+        // Bob decapsulates
+        let bob_secret = bob.decapsulate(&ciphertext).unwrap();
+
+        // Derive keys and verify they match
+        let (alice_enc, alice_mac) = alice_secret.derive_keys();
+        let (bob_enc, bob_mac) = bob_secret.derive_keys();
+
+        assert_eq!(alice_enc, bob_enc, "Encryption keys must match");
+        assert_eq!(alice_mac, bob_mac, "MAC keys must match");
+    }
+
+    #[test]
+    fn test_encrypted_channel() {
+        let keypair = PostQuantumKeypair::generate();
+        let (secret, _) = PostQuantumKeypair::encapsulate(keypair.public_key()).unwrap();
+
+        let channel = EncryptedChannel::new("peer1".to_string(), secret);
+
+        let plaintext = b"Hello, post-quantum federation!";
+        let ciphertext = channel.encrypt(plaintext).unwrap();
+
+        // Verify ciphertext is different
+        assert_ne!(&ciphertext[12..], plaintext);
+
+        // Decrypt and verify
+        let decrypted = channel.decrypt(&ciphertext).unwrap();
+        assert_eq!(plaintext, &decrypted[..]);
+    }
+
+    #[test]
+    fn test_message_signing() {
+        let keypair = PostQuantumKeypair::generate();
+        let (secret, _) = PostQuantumKeypair::encapsulate(keypair.public_key()).unwrap();
+        let channel = EncryptedChannel::new("peer1".to_string(), secret);
+
+        let message = b"Important authenticated message";
+        let signature = channel.sign(message);
+
+        // Verify valid signature
+        assert!(channel.verify(message, &signature));
+
+        // Verify invalid signature
+        assert!(!channel.verify(b"Different message", &signature));
+
+        // Verify tampered signature
+        let mut bad_sig = signature.clone();
+        bad_sig[0] ^= 1; // Flip one bit
+        assert!(!channel.verify(message, &bad_sig));
+    }
+
+    #[test]
+    fn test_decryption_tamper_detection() {
+        let keypair = PostQuantumKeypair::generate();
+        let (secret, _) = PostQuantumKeypair::encapsulate(keypair.public_key()).unwrap();
+        let channel = EncryptedChannel::new("peer1".to_string(), secret);
+
+        let plaintext = b"Secret message";
+        let mut ciphertext = channel.encrypt(plaintext).unwrap();
+
+        // Tamper with ciphertext (flip one bit in encrypted data)
+        ciphertext[20] ^= 1;
+
+        // Decryption should fail due to authentication
+        let result = channel.decrypt(&ciphertext);
+        assert!(
+            result.is_err(),
+            "Tampered ciphertext should fail authentication"
+        );
+    }
+
+    #[test]
+    fn test_invalid_public_key_size() {
+        let bad_pk = vec![0u8; 100]; // Wrong size
+        let result = PostQuantumKeypair::encapsulate(&bad_pk);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_invalid_ciphertext_size() {
+        let keypair = PostQuantumKeypair::generate();
+        let bad_ct = vec![0u8; 100]; // Wrong size
+        let result = keypair.decapsulate(&bad_ct);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_nonce_uniqueness() {
+        let keypair = PostQuantumKeypair::generate();
+        let (secret, _) = PostQuantumKeypair::encapsulate(keypair.public_key()).unwrap();
+        let channel = EncryptedChannel::new("peer1".to_string(), secret);
+
+        let plaintext = b"Test message";
+
+        // Encrypt same message twice
+        let ct1 = channel.encrypt(plaintext).unwrap();
+        let ct2 = channel.encrypt(plaintext).unwrap();
+
+        // Ciphertexts should be different (different nonces)
+        assert_ne!(ct1, ct2, "Nonces must be unique");
+
+        // Both should decrypt correctly
+        assert_eq!(channel.decrypt(&ct1).unwrap(), plaintext);
+        assert_eq!(channel.decrypt(&ct2).unwrap(), plaintext);
+    }
+}

vendor/ruvector/examples/exo-ai-2025/crates/exo-federation/src/handshake.rs

@@ -0,0 +1,265 @@
+//! Federation handshake protocol
+//!
+//! Implements the cryptographic handshake for joining a federation:
+//! 1. Post-quantum key exchange
+//! 2. Channel establishment
+//! 3. Capability negotiation
+
+use crate::{
+    crypto::{EncryptedChannel, PostQuantumKeypair},
+    FederationError, PeerAddress, Result,
+};
+use serde::{Deserialize, Serialize};
+
+/// Capabilities supported by a federation node
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Capability {
+    /// Capability name
+    pub name: String,
+    /// Capability version
+    pub version: String,
+    /// Additional parameters
+    pub params: std::collections::HashMap<String, String>,
+}
+
+impl Capability {
+    pub fn new(name: impl Into<String>, version: impl Into<String>) -> Self {
+        Self {
+            name: name.into(),
+            version: version.into(),
+            params: std::collections::HashMap::new(),
+        }
+    }
+
+    pub fn with_param(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
+        self.params.insert(key.into(), value.into());
+        self
+    }
+}
+
+/// Token granting access to a federation
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FederationToken {
+    /// Peer identifier
+    pub peer_id: String,
+    /// Negotiated capabilities
+    pub capabilities: Vec<Capability>,
+    /// Token expiry timestamp
+    pub expires: u64,
+    /// Channel secret (not serialized)
+    #[serde(skip)]
+    pub(crate) channel: Option<EncryptedChannel>,
+}
+
+impl FederationToken {
+    /// Check if token is still valid
+    pub fn is_valid(&self) -> bool {
+        use std::time::{SystemTime, UNIX_EPOCH};
+        let now = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_secs();
+        now < self.expires
+    }
+
+    /// Get the encrypted channel
+    pub fn channel(&self) -> Option<&EncryptedChannel> {
+        self.channel.as_ref()
+    }
+}
+
+/// Join a federation by performing cryptographic handshake
+///
+/// # Protocol
+///
+/// 1. Generate ephemeral keypair
+/// 2. Send public key to peer
+/// 3. Receive encapsulated shared secret
+/// 4. Establish encrypted channel
+/// 5. Exchange and negotiate capabilities
+///
+/// # Implementation from PSEUDOCODE.md
+///
+/// ```pseudocode
+/// FUNCTION JoinFederation(local_node, peer_address):
+///     (local_public, local_secret) = Kyber.KeyGen()
+///     SendMessage(peer_address, FederationRequest(local_public))
+///     response = ReceiveMessage(peer_address)
+///     shared_secret = Kyber.Decapsulate(response.ciphertext, local_secret)
+///     (encrypt_key, mac_key) = DeriveKeys(shared_secret)
+///     channel = EncryptedChannel(peer_address, encrypt_key, mac_key)
+///     local_caps = local_node.capabilities()
+///     peer_caps = channel.exchange(local_caps)
+///     terms = NegotiateFederationTerms(local_caps, peer_caps)
+///     token = FederationToken(...)
+///     RETURN token
+/// ```
+pub async fn join_federation(
+    _local_keys: &PostQuantumKeypair,
+    peer: &PeerAddress,
+) -> Result<FederationToken> {
+    // Step 1: Post-quantum key exchange
+    let (shared_secret, _ciphertext) = PostQuantumKeypair::encapsulate(&peer.public_key)?;
+
+    // Step 2: Establish encrypted channel
+    // In real implementation, we would:
+    // - Send our public key to peer
+    // - Receive peer's ciphertext
+    // - Decapsulate to get shared secret
+    // For now, we simulate both sides
+    let peer_id = generate_peer_id(&peer.host, peer.port);
+    let channel = EncryptedChannel::new(peer_id.clone(), shared_secret);
+
+    // Step 3: Exchange capabilities
+    let local_capabilities = get_local_capabilities();
+
+    // In real implementation:
+    // let peer_capabilities = channel.send_and_receive(local_capabilities).await?;
+    let peer_capabilities = simulate_peer_capabilities();
+
+    // Step 4: Negotiate federation terms
+    let capabilities = negotiate_capabilities(local_capabilities, peer_capabilities)?;
+
+    // Step 5: Create federation token
+    let token = FederationToken {
+        peer_id,
+        capabilities,
+        expires: current_timestamp() + TOKEN_VALIDITY_SECONDS,
+        channel: Some(channel),
+    };
+
+    Ok(token)
+}
+
+/// Get capabilities supported by this node
+fn get_local_capabilities() -> Vec<Capability> {
+    vec![
+        Capability::new("query", "1.0").with_param("max_results", "1000"),
+        Capability::new("consensus", "1.0").with_param("algorithm", "pbft"),
+        Capability::new("crdt", "1.0").with_param("types", "gset,lww"),
+        Capability::new("onion", "1.0").with_param("max_hops", "5"),
+    ]
+}
+
+/// Simulate peer capabilities (placeholder)
+fn simulate_peer_capabilities() -> Vec<Capability> {
+    vec![
+        Capability::new("query", "1.0").with_param("max_results", "500"),
+        Capability::new("consensus", "1.0").with_param("algorithm", "pbft"),
+        Capability::new("crdt", "1.0").with_param("types", "gset,lww,orset"),
+    ]
+}
+
+/// Negotiate capabilities between local and peer
+fn negotiate_capabilities(
+    local: Vec<Capability>,
+    peer: Vec<Capability>,
+) -> Result<Vec<Capability>> {
+    let mut negotiated = Vec::new();
+
+    // Find intersection of capabilities
+    for local_cap in &local {
+        if let Some(peer_cap) = peer.iter().find(|p| p.name == local_cap.name) {
+            // Check version compatibility
+            if is_compatible(&local_cap.version, &peer_cap.version) {
+                // Take minimum of parameters
+                let mut merged = local_cap.clone();
+
+                for (key, local_val) in &local_cap.params {
+                    if let Some(peer_val) = peer_cap.params.get(key) {
+                        // Take minimum value (more conservative)
+                        if let (Ok(local_num), Ok(peer_num)) =
+                            (local_val.parse::<u64>(), peer_val.parse::<u64>())
+                        {
+                            merged
+                                .params
+                                .insert(key.clone(), local_num.min(peer_num).to_string());
+                        }
+                    }
+                }
+
+                negotiated.push(merged);
+            }
+        }
+    }
+
+    if negotiated.is_empty() {
+        return Err(FederationError::ConsensusError(
+            "No compatible capabilities".to_string(),
+        ));
+    }
+
+    Ok(negotiated)
+}
+
+/// Check if two versions are compatible
+fn is_compatible(v1: &str, v2: &str) -> bool {
+    // Simple major version check
+    let major1 = v1.split('.').next().unwrap_or("0");
+    let major2 = v2.split('.').next().unwrap_or("0");
+    major1 == major2
+}
+
+/// Generate a peer ID from address
+fn generate_peer_id(host: &str, port: u16) -> String {
+    use sha2::{Digest, Sha256};
+    let mut hasher = Sha256::new();
+    hasher.update(host.as_bytes());
+    hasher.update(&port.to_le_bytes());
+    hex::encode(&hasher.finalize()[..16])
+}
+
+/// Get current timestamp in seconds
+fn current_timestamp() -> u64 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs()
+}
+
+/// Token validity period (1 hour)
+const TOKEN_VALIDITY_SECONDS: u64 = 3600;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_join_federation() {
+        let local_keys = PostQuantumKeypair::generate();
+        let peer_keys = PostQuantumKeypair::generate();
+
+        let peer = PeerAddress::new(
+            "localhost".to_string(),
+            8080,
+            peer_keys.public_key().to_vec(),
+        );
+
+        let token = join_federation(&local_keys, &peer).await.unwrap();
+
+        assert!(token.is_valid());
+        assert!(!token.capabilities.is_empty());
+        assert!(token.channel.is_some());
+    }
+
+    #[test]
+    fn test_capability_negotiation() {
+        let local = vec![Capability::new("test", "1.0").with_param("limit", "100")];
+
+        let peer = vec![Capability::new("test", "1.0").with_param("limit", "50")];
+
+        let result = negotiate_capabilities(local, peer).unwrap();
+
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].params.get("limit").unwrap(), "50");
+    }
+
+    #[test]
+    fn test_version_compatibility() {
+        assert!(is_compatible("1.0", "1.1"));
+        assert!(is_compatible("1.5", "1.0"));
+        assert!(!is_compatible("1.0", "2.0"));
+        assert!(!is_compatible("2.1", "1.9"));
+    }
+}

vendor/ruvector/examples/exo-ai-2025/crates/exo-federation/src/lib.rs

@@ -0,0 +1,285 @@
+//! # exo-federation: Distributed Cognitive Mesh
+//!
+//! This crate implements federated substrate networking with:
+//! - Post-quantum cryptographic handshakes
+//! - Privacy-preserving onion routing
+//! - CRDT-based eventual consistency
+//! - Byzantine fault-tolerant consensus
+//!
+//! ## Architecture
+//!
+//! ```text
+//! ┌─────────────────────────────────────────┐
+//! │      FederatedMesh (Coordinator)        │
+//! ├─────────────────────────────────────────┤
+//! │ • Local substrate instance              │
+//! │ • Consensus coordination                │
+//! │ • Federation gateway                    │
+//! │ • Cryptographic identity                │
+//! └─────────────────────────────────────────┘
+//!          │           │           │
+//!    ┌─────┘           │           └─────┐
+//!    ▼                 ▼                 ▼
+//! Handshake         Onion            CRDT
+//! Protocol          Router      Reconciliation
+//! ```
+
+use dashmap::DashMap;
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+pub mod consensus;
+pub mod crdt;
+pub mod crypto;
+pub mod handshake;
+pub mod onion;
+pub mod transfer_crdt;
+
+pub use consensus::{byzantine_commit, CommitProof};
+pub use crdt::{reconcile_crdt, GSet, LWWRegister};
+pub use crypto::{EncryptedChannel, PostQuantumKeypair};
+pub use handshake::{join_federation, Capability, FederationToken};
+pub use onion::{onion_query, OnionHeader};
+
+/// Errors that can occur in federation operations
+#[derive(Debug, thiserror::Error)]
+pub enum FederationError {
+    #[error("Cryptographic operation failed: {0}")]
+    CryptoError(String),
+
+    #[error("Network error: {0}")]
+    NetworkError(String),
+
+    #[error("Consensus failed: {0}")]
+    ConsensusError(String),
+
+    #[error("Invalid federation token")]
+    InvalidToken,
+
+    #[error("Insufficient peers for consensus: needed {needed}, got {actual}")]
+    InsufficientPeers { needed: usize, actual: usize },
+
+    #[error("CRDT reconciliation failed: {0}")]
+    ReconciliationError(String),
+
+    #[error("Peer not found: {0}")]
+    PeerNotFound(String),
+}
+
+pub type Result<T> = std::result::Result<T, FederationError>;
+
+/// Unique identifier for a peer in the federation
+#[derive(Debug, Clone, Hash, Eq, PartialEq, Serialize, Deserialize)]
+pub struct PeerId(pub String);
+
+impl PeerId {
+    pub fn new(id: String) -> Self {
+        Self(id)
+    }
+
+    pub fn generate() -> Self {
+        use sha2::{Digest, Sha256};
+        let mut hasher = Sha256::new();
+        hasher.update(rand::random::<[u8; 32]>());
+        let hash = hasher.finalize();
+        Self(hex::encode(&hash[..16]))
+    }
+}
+
+/// Network address for a peer
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PeerAddress {
+    pub host: String,
+    pub port: u16,
+    pub public_key: Vec<u8>,
+}
+
+impl PeerAddress {
+    pub fn new(host: String, port: u16, public_key: Vec<u8>) -> Self {
+        Self {
+            host,
+            port,
+            public_key,
+        }
+    }
+}
+
+/// Scope for federated queries
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum FederationScope {
+    /// Query only local instance
+    Local,
+    /// Query direct peers only
+    Direct,
+    /// Query entire federation (multi-hop)
+    Global { max_hops: usize },
+}
+
+/// Result from a federated query
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FederatedResult {
+    pub source: PeerId,
+    pub data: Vec<u8>,
+    pub score: f32,
+    pub timestamp: u64,
+}
+
+/// State update for consensus
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StateUpdate {
+    pub update_id: String,
+    pub data: Vec<u8>,
+    pub timestamp: u64,
+}
+
+/// Substrate instance placeholder (will reference exo-core types)
+pub struct SubstrateInstance {
+    // Placeholder - will integrate with actual substrate
+}
+
+/// Federated cognitive mesh coordinator
+pub struct FederatedMesh {
+    /// Unique identifier for this node
+    pub local_id: PeerId,
+
+    /// Local substrate instance
+    pub local: Arc<RwLock<SubstrateInstance>>,
+
+    /// Post-quantum cryptographic keypair
+    pub pq_keys: PostQuantumKeypair,
+
+    /// Connected peers
+    pub peers: Arc<DashMap<PeerId, PeerAddress>>,
+
+    /// Active federation tokens
+    pub tokens: Arc<DashMap<PeerId, FederationToken>>,
+
+    /// Encrypted channels to peers
+    pub channels: Arc<DashMap<PeerId, EncryptedChannel>>,
+}
+
+impl FederatedMesh {
+    /// Create a new federated mesh node
+    pub fn new(local: SubstrateInstance) -> Result<Self> {
+        let local_id = PeerId::generate();
+        let pq_keys = PostQuantumKeypair::generate();
+
+        Ok(Self {
+            local_id,
+            local: Arc::new(RwLock::new(local)),
+            pq_keys,
+            peers: Arc::new(DashMap::new()),
+            tokens: Arc::new(DashMap::new()),
+            channels: Arc::new(DashMap::new()),
+        })
+    }
+
+    /// Join a federation by connecting to a peer
+    pub async fn join_federation(&mut self, peer: &PeerAddress) -> Result<FederationToken> {
+        let token = join_federation(&self.pq_keys, peer).await?;
+
+        // Store the peer and token
+        let peer_id = PeerId::new(token.peer_id.clone());
+        self.peers.insert(peer_id.clone(), peer.clone());
+        self.tokens.insert(peer_id, token.clone());
+
+        Ok(token)
+    }
+
+    /// Execute a federated query across the mesh
+    pub async fn federated_query(
+        &self,
+        query: Vec<u8>,
+        scope: FederationScope,
+    ) -> Result<Vec<FederatedResult>> {
+        match scope {
+            FederationScope::Local => {
+                // Query only local instance
+                Ok(vec![FederatedResult {
+                    source: self.local_id.clone(),
+                    data: query, // Placeholder
+                    score: 1.0,
+                    timestamp: current_timestamp(),
+                }])
+            }
+            FederationScope::Direct => {
+                // Query direct peers
+                let mut results = Vec::new();
+
+                for entry in self.peers.iter() {
+                    let peer_id = entry.key().clone();
+                    // Placeholder: would actually send query to peer
+                    results.push(FederatedResult {
+                        source: peer_id,
+                        data: query.clone(),
+                        score: 0.8,
+                        timestamp: current_timestamp(),
+                    });
+                }
+
+                Ok(results)
+            }
+            FederationScope::Global { max_hops } => {
+                // Use onion routing for privacy
+                let _relay_nodes: Vec<_> = self
+                    .peers
+                    .iter()
+                    .take(max_hops)
+                    .map(|e| e.key().clone())
+                    .collect();
+
+                // Placeholder: would use onion_query
+                Ok(vec![])
+            }
+        }
+    }
+
+    /// Commit a state update with Byzantine consensus
+    pub async fn byzantine_commit(&self, update: StateUpdate) -> Result<CommitProof> {
+        let peer_count = self.peers.len() + 1; // +1 for local
+        byzantine_commit(update, peer_count).await
+    }
+
+    /// Get the count of peers in the federation
+    pub fn peer_count(&self) -> usize {
+        self.peers.len()
+    }
+}
+
+/// Get current timestamp in milliseconds
+fn current_timestamp() -> u64 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_millis() as u64
+}
+
+// Re-export hex for PeerId
+use hex;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_federated_mesh_creation() {
+        let substrate = SubstrateInstance {};
+        let mesh = FederatedMesh::new(substrate).unwrap();
+        assert_eq!(mesh.peer_count(), 0);
+    }
+
+    #[tokio::test]
+    async fn test_local_query() {
+        let substrate = SubstrateInstance {};
+        let mesh = FederatedMesh::new(substrate).unwrap();
+
+        let results = mesh
+            .federated_query(vec![1, 2, 3], FederationScope::Local)
+            .await
+            .unwrap();
+
+        assert_eq!(results.len(), 1);
+    }
+}

vendor/ruvector/examples/exo-ai-2025/crates/exo-federation/src/onion.rs

@@ -0,0 +1,260 @@
+//! Onion routing for privacy-preserving queries
+//!
+//! Implements multi-hop encrypted routing to hide query intent:
+//! - Layer encryption/decryption
+//! - Routing header management
+//! - Response unwrapping
+
+use crate::{FederationError, PeerId, Result};
+use serde::{Deserialize, Serialize};
+
+/// Onion routing header
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct OnionHeader {
+    /// Next hop in the route
+    pub next_hop: PeerId,
+    /// Payload type
+    pub payload_type: PayloadType,
+    /// Routing metadata
+    pub metadata: Vec<u8>,
+}
+
+/// Type of onion payload
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub enum PayloadType {
+    /// Intermediate layer (relay)
+    OnionLayer,
+    /// Final destination query
+    Query,
+    /// Response (return path)
+    Response,
+}
+
+/// Onion-wrapped message
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct OnionMessage {
+    /// Routing header
+    pub header: OnionHeader,
+    /// Encrypted payload
+    pub payload: Vec<u8>,
+}
+
+/// Execute a privacy-preserving query through onion network
+///
+/// # Protocol
+///
+/// The query is wrapped in multiple layers of encryption, each layer
+/// only decryptable by the designated relay node. Each node only knows
+/// the previous and next hop, preserving query privacy.
+///
+/// # Implementation from PSEUDOCODE.md
+///
+/// ```pseudocode
+/// FUNCTION OnionQuery(query, destination, relay_nodes, local_keys):
+///     layers = [destination] + relay_nodes
+///     current_payload = SerializeQuery(query)
+///
+///     FOR node IN layers:
+///         encrypted = AsymmetricEncrypt(current_payload, node.public_key)
+///         header = OnionHeader(next_hop = node.address, ...)
+///         current_payload = header + encrypted
+///
+///     SendMessage(first_relay, current_payload)
+///     encrypted_response = ReceiveMessage(first_relay)
+///
+///     FOR node IN reverse(relay_nodes):
+///         current_response = AsymmetricDecrypt(current_response, local_keys.secret)
+///
+///     result = DeserializeResponse(current_response)
+///     RETURN result
+/// ```
+pub async fn onion_query(
+    query: Vec<u8>,
+    destination: PeerId,
+    relay_nodes: Vec<PeerId>,
+) -> Result<Vec<u8>> {
+    // Build route: destination + relays
+    let mut route = relay_nodes.clone();
+    route.push(destination);
+
+    // Wrap in onion layers (innermost to outermost)
+    let onion_msg = wrap_onion(query, &route)?;
+
+    // Send to first relay
+    // In real implementation: send over network
+    // For now, simulate routing
+    let response = simulate_routing(onion_msg, &route).await?;
+
+    // Unwrap response layers
+    let result = unwrap_onion(response, relay_nodes.len())?;
+
+    Ok(result)
+}
+
+/// Wrap a message in onion layers
+fn wrap_onion(query: Vec<u8>, route: &[PeerId]) -> Result<OnionMessage> {
+    let mut current_payload = query;
+
+    // Wrap from destination back to first relay
+    for (i, peer_id) in route.iter().enumerate().rev() {
+        // Encrypt payload (placeholder - would use actual public key crypto)
+        let encrypted = encrypt_layer(&current_payload, peer_id)?;
+
+        // Create header
+        let header = OnionHeader {
+            next_hop: peer_id.clone(),
+            payload_type: if i == route.len() - 1 {
+                PayloadType::Query
+            } else {
+                PayloadType::OnionLayer
+            },
+            metadata: vec![],
+        };
+
+        // Combine header and encrypted payload
+        current_payload = serialize_message(&OnionMessage {
+            header: header.clone(),
+            payload: encrypted,
+        })?;
+    }
+
+    // Final message to send to first relay
+    deserialize_message(&current_payload)
+}
+
+/// Unwrap onion response layers
+fn unwrap_onion(response: Vec<u8>, num_layers: usize) -> Result<Vec<u8>> {
+    let mut current = response;
+
+    // Decrypt each layer
+    for _ in 0..num_layers {
+        current = decrypt_layer(&current)?;
+    }
+
+    Ok(current)
+}
+
+/// Encrypt a layer for a specific peer
+///
+/// # Placeholder Implementation
+///
+/// Real implementation would use the peer's public key for
+/// asymmetric encryption (e.g., using their Kyber public key).
+fn encrypt_layer(data: &[u8], peer_id: &PeerId) -> Result<Vec<u8>> {
+    use sha2::{Digest, Sha256};
+
+    // Derive a key from peer ID (placeholder)
+    let mut hasher = Sha256::new();
+    hasher.update(peer_id.0.as_bytes());
+    let key = hasher.finalize();
+
+    // XOR encryption (placeholder)
+    let encrypted: Vec<u8> = data
+        .iter()
+        .zip(key.iter().cycle())
+        .map(|(d, k)| d ^ k)
+        .collect();
+
+    Ok(encrypted)
+}
+
+/// Decrypt an onion layer
+fn decrypt_layer(data: &[u8]) -> Result<Vec<u8>> {
+    // Placeholder: would use local secret key
+    // For XOR cipher, decrypt is same as encrypt
+    use sha2::{Digest, Sha256};
+
+    let mut hasher = Sha256::new();
+    hasher.update(b"local_key");
+    let key = hasher.finalize();
+
+    let decrypted: Vec<u8> = data
+        .iter()
+        .zip(key.iter().cycle())
+        .map(|(d, k)| d ^ k)
+        .collect();
+
+    Ok(decrypted)
+}
+
+/// Serialize an onion message
+fn serialize_message(msg: &OnionMessage) -> Result<Vec<u8>> {
+    serde_json::to_vec(msg).map_err(|e| FederationError::NetworkError(e.to_string()))
+}
+
+/// Deserialize an onion message
+fn deserialize_message(data: &[u8]) -> Result<OnionMessage> {
+    serde_json::from_slice(data).map_err(|e| FederationError::NetworkError(e.to_string()))
+}
+
+/// Simulate routing through the onion network
+///
+/// In real implementation, this would:
+/// 1. Send to first relay
+/// 2. Each relay decrypts one layer
+/// 3. Each relay forwards to next hop
+/// 4. Destination processes query
+/// 5. Response routes back through same path
+async fn simulate_routing(_message: OnionMessage, _route: &[PeerId]) -> Result<Vec<u8>> {
+    // Placeholder: return simulated response
+    Ok(vec![42, 43, 44]) // Dummy response data
+}
+
+/// Peel one layer from an onion message
+///
+/// This function would be called by relay nodes to:
+/// 1. Decrypt the outer layer
+/// 2. Extract the next hop
+/// 3. Forward the remaining layers
+pub fn peel_layer(message: &OnionMessage, _local_secret: &[u8]) -> Result<(PeerId, OnionMessage)> {
+    let next_hop = message.header.next_hop.clone();
+
+    // Decrypt the payload to get inner message
+    let decrypted = decrypt_layer(&message.payload)?;
+    let inner_message = deserialize_message(&decrypted)?;
+
+    Ok((next_hop, inner_message))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_onion_query() {
+        let query = vec![1, 2, 3, 4, 5];
+        let destination = PeerId::new("dest".to_string());
+        let relays = vec![
+            PeerId::new("relay1".to_string()),
+            PeerId::new("relay2".to_string()),
+        ];
+
+        let result = onion_query(query, destination, relays).await.unwrap();
+        assert!(!result.is_empty());
+    }
+
+    #[test]
+    fn test_layer_encryption() {
+        let data = vec![1, 2, 3, 4];
+        let peer = PeerId::new("test_peer".to_string());
+
+        let encrypted = encrypt_layer(&data, &peer).unwrap();
+        assert_ne!(encrypted, data);
+
+        // For XOR cipher, encrypting twice returns original
+        let double_encrypted = encrypt_layer(&encrypted, &peer).unwrap();
+        assert_eq!(double_encrypted, data);
+    }
+
+    #[test]
+    fn test_onion_wrapping() {
+        let query = vec![1, 2, 3];
+        let route = vec![
+            PeerId::new("relay1".to_string()),
+            PeerId::new("dest".to_string()),
+        ];
+
+        let wrapped = wrap_onion(query.clone(), &route).unwrap();
+        assert_eq!(wrapped.header.next_hop, route[0]);
+    }
+}

vendor/ruvector/examples/exo-ai-2025/crates/exo-federation/src/transfer_crdt.rs

@@ -0,0 +1,218 @@
+//! Phase 4 – Transfer CRDT
+//!
+//! Distributed transfer-prior propagation using LWW-Map and G-Set CRDTs.
+//!
+//! * `publish_prior` – writes a local prior (cycle = LWW timestamp).
+//! * `merge_peer`    – merges a peer node's state (last-writer-wins).
+//! * `promote_via_consensus` – runs Byzantine commit before accepting a prior.
+
+use ruvector_domain_expansion::DomainId;
+use serde::{Deserialize, Serialize};
+
+use crate::consensus::{byzantine_commit, CommitProof};
+use crate::crdt::{GSet, LWWMap};
+use crate::{FederationError, Result, StateUpdate};
+
+// ─── types ────────────────────────────────────────────────────────────────────
+
+/// Compact summary of a transfer prior for LWW replication.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TransferPriorSummary {
+    pub src_domain: String,
+    pub dst_domain: String,
+    /// Mean reward improvement from the transfer (positive = helpful).
+    pub improvement: f32,
+    /// Confidence in the estimate (higher = more observations).
+    pub confidence: f32,
+    /// Training cycle at which this summary was captured.
+    pub cycle: u64,
+}
+
+// ─── TransferCrdt ─────────────────────────────────────────────────────────────
+
+/// Distributed transfer-prior store using LWW-Map + G-Set CRDTs.
+///
+/// Multiple federation nodes each maintain their own `TransferCrdt`; calling
+/// `merge_peer` synchronises state using last-writer-wins semantics keyed by
+/// cycle count, guaranteeing eventual consistency without coordination.
+pub struct TransferCrdt {
+    /// LWW-Map: key = `"src:dst"`, value = best known prior summary.
+    priors: LWWMap<String, TransferPriorSummary>,
+    /// G-Set: all domain IDs ever observed by this node.
+    domains: GSet<String>,
+}
+
+impl TransferCrdt {
+    pub fn new() -> Self {
+        Self {
+            priors: LWWMap::new(),
+            domains: GSet::new(),
+        }
+    }
+
+    /// Publish a local transfer prior.
+    ///
+    /// `cycle` acts as the LWW timestamp so newer cycles always win
+    /// without requiring wall-clock synchronisation.
+    pub fn publish_prior(
+        &mut self,
+        src: &DomainId,
+        dst: &DomainId,
+        improvement: f32,
+        confidence: f32,
+        cycle: u64,
+    ) {
+        let key = format!("{}:{}", src.0, dst.0);
+        let summary = TransferPriorSummary {
+            src_domain: src.0.clone(),
+            dst_domain: dst.0.clone(),
+            improvement,
+            confidence,
+            cycle,
+        };
+        self.priors.set(key, summary, cycle);
+        self.domains.add(src.0.clone());
+        self.domains.add(dst.0.clone());
+    }
+
+    /// Merge a peer's CRDT state into this node (idempotent, commutative).
+    pub fn merge_peer(&mut self, other: &TransferCrdt) {
+        self.priors.merge(&other.priors);
+        self.domains.merge(&other.domains);
+    }
+
+    /// Retrieve the best known prior for a domain pair (if any).
+    pub fn best_prior_for(&self, src: &DomainId, dst: &DomainId) -> Option<&TransferPriorSummary> {
+        let key = format!("{}:{}", src.0, dst.0);
+        self.priors.get(&key)
+    }
+
+    /// All domain IDs known to this node.
+    pub fn known_domains(&self) -> Vec<String> {
+        self.domains.elements().cloned().collect()
+    }
+
+    /// Run Byzantine consensus before promoting a prior across the federation.
+    ///
+    /// Serialises the prior summary as the `StateUpdate` payload and calls the
+    /// PBFT-style commit protocol. Requires `peer_count + 1 >= 4` total nodes.
+    pub async fn promote_via_consensus(
+        &self,
+        src: &DomainId,
+        dst: &DomainId,
+        peer_count: usize,
+    ) -> Result<CommitProof> {
+        let key = format!("{}:{}", src.0, dst.0);
+        let summary = self
+            .priors
+            .get(&key)
+            .ok_or_else(|| FederationError::PeerNotFound(format!("no prior for {key}")))?;
+
+        let data = serde_json::to_vec(summary)
+            .map_err(|e| FederationError::ReconciliationError(e.to_string()))?;
+
+        let update = StateUpdate {
+            update_id: key,
+            data,
+            timestamp: current_millis(),
+        };
+
+        byzantine_commit(update, peer_count + 1).await
+    }
+}
+
+impl Default for TransferCrdt {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+fn current_millis() -> u64 {
+    use std::time::{SystemTime, UNIX_EPOCH};
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_publish_and_retrieve() {
+        let mut crdt = TransferCrdt::new();
+        let src = DomainId("retrieval".to_string());
+        let dst = DomainId("graph".to_string());
+
+        crdt.publish_prior(&src, &dst, 0.15, 0.8, 10);
+        let p = crdt.best_prior_for(&src, &dst).unwrap();
+        assert_eq!(p.cycle, 10);
+        assert!((p.improvement - 0.15).abs() < 1e-5);
+    }
+
+    #[test]
+    fn test_lww_newer_wins() {
+        let mut node_a = TransferCrdt::new();
+        let mut node_b = TransferCrdt::new();
+        let src = DomainId("x".to_string());
+        let dst = DomainId("y".to_string());
+
+        node_a.publish_prior(&src, &dst, 0.1, 0.5, 5); // older cycle
+        node_b.publish_prior(&src, &dst, 0.2, 0.9, 10); // newer wins
+
+        node_a.merge_peer(&node_b);
+        let p = node_a.best_prior_for(&src, &dst).unwrap();
+        assert_eq!(p.cycle, 10);
+        assert!((p.improvement - 0.2).abs() < 1e-5);
+    }
+
+    #[test]
+    fn test_merge_idempotent() {
+        let mut crdt = TransferCrdt::new();
+        let src = DomainId("a".to_string());
+        let dst = DomainId("b".to_string());
+        crdt.publish_prior(&src, &dst, 0.3, 0.7, 5);
+
+        let snapshot = TransferCrdt::new(); // empty peer
+        crdt.merge_peer(&snapshot);
+
+        // Still has original data
+        assert!(crdt.best_prior_for(&src, &dst).is_some());
+    }
+
+    #[test]
+    fn test_gset_domain_discovery() {
+        let mut crdt = TransferCrdt::new();
+        crdt.publish_prior(
+            &DomainId("a".to_string()),
+            &DomainId("b".to_string()),
+            0.1,
+            0.5,
+            1,
+        );
+        crdt.publish_prior(
+            &DomainId("b".to_string()),
+            &DomainId("c".to_string()),
+            0.2,
+            0.6,
+            2,
+        );
+        let domains = crdt.known_domains();
+        assert!(domains.contains(&"a".to_string()));
+        assert!(domains.contains(&"b".to_string()));
+        assert!(domains.contains(&"c".to_string()));
+    }
+
+    #[tokio::test]
+    async fn test_promote_via_consensus() {
+        let mut crdt = TransferCrdt::new();
+        let src = DomainId("retrieval".to_string());
+        let dst = DomainId("graph".to_string());
+        crdt.publish_prior(&src, &dst, 0.3, 0.9, 20);
+
+        // 6 peers + 1 local = 7 total nodes; for n=7: f=2, threshold=5, verify=(16/3)=5 ✓
+        let proof = crdt.promote_via_consensus(&src, &dst, 6).await.unwrap();
+        assert!(proof.verify(7));
+    }
+}