Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/examples/exo-ai-2025/crates/exo-federation/README.md

@@ -0,0 +1,80 @@
+# exo-federation
+
+Federated cognitive mesh with post-quantum cryptographic sovereignty for
+distributed AI consciousness. Lets multiple EXO-AI substrates collaborate
+across trust boundaries without sacrificing autonomy or security.
+
+## Features
+
+- **CRDT-based state replication** -- uses Last-Writer-Wins Maps
+  (LWW-Map) and Grow-Only Sets (G-Set) for conflict-free convergence
+  of shared cognitive state across nodes.
+- **Byzantine consensus (PBFT)** -- Practical Byzantine Fault Tolerance
+  ensures agreement even when up to f of 3f+1 nodes are faulty or
+  adversarial.
+- **Kyber post-quantum key exchange** -- establishes shared secrets
+  resilient to quantum attacks using the NIST-standardised ML-KEM
+  (Kyber) scheme.
+- **Onion-routed messaging** -- wraps messages in layered encryption so
+  intermediate relay nodes cannot observe payload or final destination.
+- **Transfer CRDT** -- a purpose-built CRDT that merges cross-domain
+  knowledge transfer records without coordination.
+
+## Quick Start
+
+Add the dependency to your `Cargo.toml`:
+
+```toml
+[dependencies]
+exo-federation = "0.1"
+```
+
+Basic usage:
+
+```rust
+use exo_federation::{FederatedMesh, FederationScope, PeerAddress};
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let substrate = SubstrateInstance {};
+    let mut mesh = FederatedMesh::new(substrate)?;
+
+    // Join a federation via post-quantum handshake
+    let peer = PeerAddress::new("peer.example.com", 8080, peer_key);
+    let token = mesh.join_federation(&peer).await?;
+
+    // Execute a federated query across the mesh
+    let results = mesh.federated_query(
+        query_data,
+        FederationScope::Global { max_hops: 5 },
+    ).await?;
+
+    // Commit state update with Byzantine consensus
+    let proof = mesh.byzantine_commit(update).await?;
+    Ok(())
+}
+```
+
+## Crate Layout
+
+| Module       | Purpose                                     |
+|--------------|---------------------------------------------|
+| `crdt`       | LWW-Map, G-Set, and transfer CRDT impls     |
+| `consensus`  | PBFT protocol engine                         |
+| `crypto`     | Kyber key exchange and onion routing         |
+| `handshake`  | Federation joining protocol                  |
+| `mesh`       | Peer discovery and connection management     |
+
+## Requirements
+
+- Rust 1.78+
+- Depends on `exo-core`, `tokio`
+
+## Links
+
+- [GitHub](https://github.com/ruvnet/ruvector)
+- [EXO-AI Documentation](https://github.com/ruvnet/ruvector/tree/main/examples/exo-ai-2025)
+
+## License
+
+MIT OR Apache-2.0