ruvix_vecgraph/
lib.rs

1//! Kernel-Resident Vector and Graph Stores for RuVix Cognition Kernel.
2//!
3//! This crate implements the Vector/Graph Kernel Objects from ADR-087 Section 4.3.
4//! Unlike conventional kernels where all data structures are userspace constructs,
5//! RuVix makes vector stores and graph stores kernel-resident objects.
6//!
7//! # Design Principles
8//!
9//! - Vector data lives in kernel-managed slab regions with capability protection
10//! - HNSW index nodes are slab-allocated (fixed-size slots, zero allocator overhead)
11//! - Coherence metadata is co-located with each vector
12//! - All mutations are proof-gated (no proof, no mutation)
13//! - Every successful mutation emits a witness attestation
14//!
15//! # Syscalls Implemented
16//!
17//! - `vector_get`: Read vector data and coherence metadata (capability-gated, no proof required)
18//! - `vector_put_proved`: Write vector with proof verification (proof-gated, PROVE right required)
19//! - `graph_apply_proved`: Apply graph mutation with proof verification (proof-gated)
20//!
21//! # Example
22//!
23//! ```rust,ignore
24//! use ruvix_vecgraph::{KernelVectorStore, VectorStoreBuilder};
25//! use ruvix_types::{VectorKey, ProofToken, CapRights};
26//!
27//! // Create a vector store with 768 dimensions and 10000 capacity
28//! let store = VectorStoreBuilder::new(768, 10000)
29//!     .with_proof_policy(ProofPolicy::standard())
30//!     .build(backing)?;
31//!
32//! // Read a vector (no proof required)
33//! let (data, meta) = store.vector_get(key, cap)?;
34//!
35//! // Write a vector (proof required)
36//! let attestation = store.vector_put_proved(key, &data, proof, cap)?;
37//! ```
38//!
39//! # Features
40//!
41//! - `std`: Enable standard library support (default)
42//! - `stats`: Enable statistics collection
43//! - `coherence`: Enable coherence scoring
44
45#![cfg_attr(not(feature = "std"), no_std)]
46#![deny(unsafe_op_in_unsafe_fn)]
47#![warn(missing_docs)]
48
49#[cfg(feature = "alloc")]
50extern crate alloc;
51
52pub mod coherence;
53pub mod graph_store;
54pub mod hnsw;
55pub mod proof_policy;
56pub mod simd_distance;
57pub mod vector_store;
58pub mod witness;
59
60// Re-exports
61pub use coherence::{CoherenceConfig, CoherenceTracker};
62pub use graph_store::{GraphMutationResult, GraphStoreBuilder, KernelGraphStore, PartitionMeta};
63pub use hnsw::{HnswConfig, HnswNode, HnswRegion};
64pub use proof_policy::{NonceTracker, ProofPolicy, ProofVerifier};
65pub use vector_store::{KernelVectorStore, VectorEntry, VectorStoreBuilder};
66pub use witness::{WitnessEntry, WitnessLog};
67pub use simd_distance::{
68    cosine_similarity, dot_product, euclidean_distance_squared, l2_norm,
69    SimdCapabilities,
70};
71
72/// Result type for vecgraph operations.
73pub type Result<T> = core::result::Result<T, ruvix_types::KernelError>;
74
75/// Statistics for vector store operations.
76#[cfg(feature = "stats")]
77#[derive(Debug, Clone, Default)]
78pub struct VecGraphStats {
79    /// Total vector reads.
80    pub vector_reads: u64,
81    /// Total vector writes.
82    pub vector_writes: u64,
83    /// Total vector writes rejected (proof failed).
84    pub vector_writes_rejected: u64,
85    /// Total graph mutations.
86    pub graph_mutations: u64,
87    /// Total graph mutations rejected (proof failed).
88    pub graph_mutations_rejected: u64,
89    /// Total witness entries emitted.
90    pub witness_entries: u64,
91}
92
93#[cfg(test)]
94mod tests {
95    #[test]
96    fn test_module_compiles() {
97        // Basic compilation test
98        assert!(true);
99    }
100}
ruvix_vecgraph/lib.rs

ruvix_vecgraph/
lib.rs
