Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

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

@@ -0,0 +1,75 @@
+# exo-hypergraph
+
+Hypergraph substrate for higher-order relational reasoning with persistent
+homology and sheaf theory. Enables cognitive representations that go beyond
+pairwise edges to capture n-ary relationships natively.
+
+## Features
+
+- **Hyperedge storage** -- first-class support for edges that connect
+  arbitrary sets of nodes, stored in a compressed sparse format.
+- **Sheaf sections** -- attach typed data (sections) to nodes and edges
+  with consistency conditions enforced by sheaf restriction maps.
+- **Sparse persistent homology (PPR-based O(n/epsilon))** -- computes
+  topological features efficiently using personalised PageRank
+  sparsification.
+- **Betti number computation** -- extracts Betti-0 (connected components),
+  Betti-1 (loops), and higher Betti numbers to summarise structural
+  topology.
+
+## Quick Start
+
+Add the dependency to your `Cargo.toml`:
+
+```toml
+[dependencies]
+exo-hypergraph = "0.1"
+```
+
+Basic usage:
+
+```rust
+use exo_hypergraph::{HypergraphSubstrate, HypergraphConfig};
+use exo_core::{EntityId, Relation, RelationType};
+
+let config = HypergraphConfig::default();
+let mut hg = HypergraphSubstrate::new(config);
+
+let e1 = EntityId::new();
+let e2 = EntityId::new();
+let e3 = EntityId::new();
+
+// Create a 3-way hyperedge
+let relation = Relation {
+    relation_type: RelationType::new("collaboration"),
+    properties: serde_json::json!({"project": "EXO-AI"}),
+};
+hg.create_hyperedge(&[e1, e2, e3], &relation).unwrap();
+
+// Compute topological invariants
+let betti = hg.betti_numbers(2);
+println!("Betti numbers: {:?}", betti);
+```
+
+## Crate Layout
+
+| Module      | Purpose                                    |
+|-------------|--------------------------------------------|
+| `graph`     | Core hypergraph data structure              |
+| `sheaf`     | Sheaf sections and restriction maps         |
+| `homology`  | Sparse persistent homology pipeline         |
+| `betti`     | Betti number extraction and summarisation   |
+
+## Requirements
+
+- Rust 1.78+
+- Depends on `exo-core`
+
+## 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