ruv-neural Crate System: Security and Performance Review

Date: 2026-03-09 Version: 0.1.0 Scope: All 12 workspace crates in the ruv-neural system Status: Implementation checklist for v0.1 and v0.2 milestones

Table of Contents

1. Crate Inventory
2. Security Review
   • Input Validation
   • Memory Safety
   • Data Privacy
   • Network Security (ESP32)
   • Supply Chain
   • Findings from Code Audit
3. Performance Review
   • Computational Complexity
   • Memory Usage
   • Optimization Opportunities
   • ESP32 Constraints
   • Benchmarking Recommendations
   • Performance Findings from Code Audit
4. Action Items

Crate Inventory

Security Review

Input Validation

All public APIs must validate their inputs at system boundaries. This section catalogs each validation requirement and its current status.

Sensor Data Validation

Recommendation: Add a SensorChannel::new() constructor that validates sensitivity_ft_sqrt_hz > 0, sample_rate_hz > 0, and that the orientation vector is a unit normal. Add sample_rate_hz > 0 and sample_rate_hz.is_finite() checks to MultiChannelTimeSeries::new. Add a validate_finite() utility for signal data.

Graph Construction Validation

Recommendation: Add a BrainGraph::validate() method that checks all edge indices are within bounds, weights are finite, and no self-loops exist. Call it from stoer_wagner_mincut, spectral_bisection, and SpectralEmbedder::embed. Consider making adjacency_matrix() return Result with an error for out-of-bounds edges instead of silently ignoring them.

RVF Format Validation

Recommendation: Add maximum size limits for metadata_json_len (e.g., 16 MB) and total payload size. Validate that num_entries * entry_size_for_type <= data.len() after reading. Use Read::take() to cap reads.

Embedding Validation

Memory Store Validation

JSON Parsing

Memory Safety

Recommendation: Add a validation check on resolution_bits in AdcConfig (must be <= 15 for i16 representation, or switch to u16/i32). Consider migrating Vec<Vec<f64>> matrix representations to ndarray::Array2<f64> for better cache performance and built-in bounds checking.

Data Privacy

Neural data is among the most sensitive personal data categories. This section covers data handling practices.

Recommendations:

• Implement a Redactable trait for types that may contain PII, providing redact() and anonymize() methods.
• Use the zeroize crate to zero sensitive data on drop for NeuralEmbedding, NeuralMemoryStore, and MultiChannelTimeSeries.
• Add a strip_pii() method to RvfFile that removes or hashes identifiers before export.
• Document privacy responsibilities in each crate's module documentation.
• For v0.2: Add optional encryption-at-rest for NeuralMemoryStore using ring or aes-gcm.

Network Security (ESP32)

Recommendations for v0.2 TDM Protocol:

• Authenticate node IDs using a pre-shared key or challenge-response.
• Add CRC32 or CRC32-C to every data packet.
• Set maximum packet size to 1460 bytes (single WiFi frame MTU).
• Use DTLS or TLS 1.3 for encryption when available.
• Rate-limit incoming packets per node to prevent flooding.
• Validate all fields in received packets before processing.

Supply Chain

Recommendation: Run cargo deny check to audit for known vulnerabilities. Remove unused workspace dependencies (petgraph, tokio, ruvector-* crates) to minimize attack surface. Add cargo audit to CI.

Findings from Code Audit

SEC-001: RVF Unbounded Allocation (Severity: Medium)

Location: ruv-neural-core/src/rvf.rs, line 193

let mut meta_bytes = vec![0u8; header.metadata_json_len as usize];

A crafted RVF file with metadata_json_len = 0xFFFFFFFF allocates 4 GB. Similarly, read_to_end on line 201 reads unbounded data.

Fix: Add maximum size constants and validate before allocating:

const MAX_METADATA_LEN: u32 = 16 * 1024 * 1024; // 16 MB
const MAX_PAYLOAD_LEN: usize = 256 * 1024 * 1024; // 256 MB

if header.metadata_json_len > MAX_METADATA_LEN {
    return Err(RuvNeuralError::Serialization(
        format!("metadata_json_len {} exceeds maximum {}", header.metadata_json_len, MAX_METADATA_LEN)
    ));
}

SEC-002: Missing Sample Rate Validation (Severity: Medium)

Location: ruv-neural-core/src/signal.rs, MultiChannelTimeSeries::new

The sample_rate_hz parameter is not validated. A value of 0.0 causes division by zero in duration_s(). A negative or NaN value causes incorrect spectral analysis throughout the pipeline.

Fix: Add validation in the constructor:

if sample_rate_hz <= 0.0 || !sample_rate_hz.is_finite() {
    return Err(RuvNeuralError::Signal(
        format!("sample_rate_hz must be positive and finite, got {}", sample_rate_hz)
    ));
}

SEC-003: NaN Propagation in Signal Processing (Severity: Low)

Location: ruv-neural-signal/src/connectivity.rs, all functions

If either input signal contains NaN, the Hilbert transform produces NaN outputs, which propagate silently through PLV, coherence, and all connectivity metrics. The result is a brain graph with NaN edge weights, which causes undefined behavior in Stoer-Wagner (infinite loops or wrong results).

Fix: Add a validate_signal helper and call it at entry points:

fn validate_signal(signal: &[f64]) -> Result<()> {
    if signal.iter().any(|x| !x.is_finite()) {
        return Err(RuvNeuralError::Signal("Signal contains NaN or Inf values".into()));
    }
    Ok(())
}

SEC-004: Integer Overflow in ADC (Severity: Low)

Location: ruv-neural-esp32/src/adc.rs, AdcConfig::max_raw_value

pub fn max_raw_value(&self) -> i16 {
    ((1u32 << self.resolution_bits) - 1) as i16
}

For resolution_bits = 16, this computes 65535 as i16 = -1, which causes incorrect voltage conversion (division by -1 flips sign).

Fix: Change return type to u16 or i32, or validate resolution_bits <= 15.

SEC-005: HNSW Visited Array Allocation (Severity: Low)

Location: ruv-neural-memory/src/hnsw.rs, search_layer, line 261

let mut visited = vec![false; self.embeddings.len()];

This allocates a visited array proportional to the total number of embeddings on every search call. For large indices (100K+ embeddings), this causes unnecessary allocation pressure. More critically, if entry is >= self.embeddings.len(), the indexing on line 262 panics.

Fix: Use a HashSet<usize> instead of a boolean array for sparse visitation. Add bounds check on entry.

Performance Review

Computational Complexity

Memory Usage

Optimization Opportunities

Immediate (v0.1)

1. Eliminate redundant Hilbert transforms in connectivity matrix

   • compute_all_pairs calls hilbert_transform twice per channel pair.
   • For 68 channels, this means 68 x 67 = 4,556 Hilbert transforms instead of 68.
   • Fix: Pre-compute analytic signals for all channels, then compute metrics pairwise.
   • Expected speedup: ~67x for connectivity matrix computation.

2. Replace Vec<Vec<f64>> with flat Vec<f64> for adjacency matrices

   • Current Vec<Vec<f64>> has poor cache locality due to heap-allocated inner Vecs.
   • Fix: Use Vec<f64> with manual row-major indexing, or migrate to ndarray::Array2<f64>.
   • Expected speedup: 2-4x for matrix-heavy operations (Stoer-Wagner, Laplacian).

3. Avoid Vec::remove(0) in eviction

   • NeuralMemoryStore::evict_oldest calls self.embeddings.remove(0), which is O(n).
   • Fix: Use a VecDeque or circular buffer.
   • Expected speedup: O(1) eviction instead of O(n).

4. Pre-allocate FFT planner

   • compute_psd, compute_stft, and hilbert_transform each create a new FftPlanner per call.
   • Fix: Cache the planner or use a thread-local planner.
   • Expected speedup: Eliminates repeated plan computation.

Medium-term (v0.2)

5. Rayon for parallel channel processing

   • compute_all_pairs iterates channel pairs sequentially.
   • Fix: Use rayon::par_iter for the outer loop.
   • Expected speedup: Linear with core count for connectivity computation.

6. SIMD for distance computations in HNSW

   • Euclidean distance in HnswIndex::distance uses scalar iteration.
   • Fix: Use packed_simd2 or auto-vectorization hints.
   • Expected speedup: 4-8x for 256-d vectors on AVX2.

7. Sparse graph representation

   • Dense adjacency matrix wastes memory for sparse brain graphs.
   • For Schaefer400, storing all 160K entries when only ~10K edges exist is wasteful.
   • Fix: Use compressed sparse row (CSR) format or petgraph's sparse graph.

8. Quantized embeddings for WASM

   • f64 embeddings are unnecessarily precise for browser-based applications.
   • Fix: Support f32 embeddings in WASM builds, halving memory and transfer size.

Long-term (v0.3+)

9. Streaming signal processing

   • Current design loads entire time windows into memory.
   • Fix: Implement ring-buffer based streaming for real-time operation.

10. GPU acceleration for large-scale spectral analysis

    • For Schaefer400 atlas, eigendecomposition of 400x400 matrices benefits from GPU.
    • Fix: Optional wgpu or vulkano backend for matrix operations.

ESP32 Constraints

Recommendations:

• Use fixed-point arithmetic (i16 or Q15) instead of f64 on ESP32.
• Implement delta encoding or simple compression for data packets.
• Limit on-device processing to ADC readout and basic quality checks.
• Move all signal processing (FFT, connectivity, graph construction) to the host.
• Profile binary size with cargo bloat to ensure it fits in 4 MB flash.
• Consider reducing ring buffer size for multi-channel configurations.

Benchmarking Recommendations

Per-Crate Microbenchmarks (criterion)

# Add to each crate's Cargo.toml
[[bench]]
name = "benchmarks"
harness = false

[dev-dependencies]
criterion = { workspace = true }

Full Pipeline Profiling

# Generate a flamegraph of the full pipeline
cargo flamegraph --bench full_pipeline -- --bench

# Memory profiling with DHAT
cargo test --features dhat-heap -- --test full_pipeline

WASM Performance

// When ruv-neural-wasm is implemented, measure with:
performance.mark('embed-start');
const embedding = ruv_neural.embed(graphData);
performance.mark('embed-end');
performance.measure('embed', 'embed-start', 'embed-end');

ESP32 Hardware Timing

// Use esp-idf-hal's timer for hardware-level benchmarks
let start = esp_idf_hal::timer::now();
let samples = reader.read_samples(1000)?;
let elapsed_us = esp_idf_hal::timer::now() - start;

Performance Findings from Code Audit

PERF-001: Redundant Hilbert Transforms (Severity: High)

Location: ruv-neural-signal/src/connectivity.rs, compute_all_pairs

Each call to phase_locking_value, coherence, imaginary_coherence, or amplitude_envelope_correlation independently calls hilbert_transform on both input signals. In compute_all_pairs with 68 channels, each channel's analytic signal is computed 67 times.

Impact: For 68 channels x 1024 samples, this means 4,556 FFTs instead of 68. Estimated waste: ~98.5% of FFT compute in the connectivity matrix.

Fix: Pre-compute all analytic signals, then pass slices to pairwise metrics:

pub fn compute_all_pairs_optimized(channels: &[Vec<f64>], metric: &ConnectivityMetric) -> Vec<Vec<f64>> {
    let analytics: Vec<Vec<Complex<f64>>> = channels.iter()
        .map(|ch| hilbert_transform(ch))
        .collect();
    // ... use pre-computed analytics for all pair computations
}

PERF-002: O(n) Eviction in Memory Store (Severity: Medium)

Location: ruv-neural-memory/src/store.rs, evict_oldest

fn evict_oldest(&mut self) {
    self.embeddings.remove(0);  // O(n) shift
    self.rebuild_index();       // O(n) rebuild
}

For a store with 10K embeddings, every insertion at capacity triggers an O(n) shift and full index rebuild.

Fix: Use VecDeque<NeuralEmbedding> and maintain the index incrementally.

PERF-003: FFT Planner Re-creation (Severity: Medium)

Location: ruv-neural-signal/src/spectral.rs (lines 12-13), hilbert.rs (lines 25-27)

A new FftPlanner is created on every function call. rustfft caches FFT plans internally in the planner, but creating a new planner discards the cache.

Fix: Use a thread-local or static planner:

thread_local! {
    static FFT_PLANNER: RefCell<FftPlanner<f64>> = RefCell::new(FftPlanner::new());
}

PERF-004: Dense Adjacency for Sparse Graphs (Severity: Low)

Location: ruv-neural-core/src/graph.rs, adjacency_matrix

Always allocates an N x N matrix even when the graph has far fewer edges. For Schaefer400 with ~5K edges, this allocates 1.25 MB for a matrix that is ~97% zeros.

Fix: Return a sparse representation for large graphs, or provide both adjacency_matrix() and sparse_adjacency().

PERF-005: Power Iteration Convergence Not Checked (Severity: Low)

Location: ruv-neural-mincut/src/spectral_cut.rs, largest_eigenvalue

Runs a fixed 200 iterations regardless of convergence. Many graphs converge in 20-50 iterations.

Fix: Add early termination when eigenvalue change < epsilon:

if (eigenvalue - prev_eigenvalue).abs() < 1e-12 {
    break;
}

Note: fiedler_decomposition already has this check, but largest_eigenvalue does not.

Action Items

Critical (Must fix before v0.1 release)

• SEC-001: Add maximum size limits to RVF deserialization
• SEC-002: Validate sample_rate_hz > 0 and is_finite() in MultiChannelTimeSeries::new
• SEC-004: Fix integer overflow in AdcConfig::max_raw_value
• PERF-001: Pre-compute Hilbert transforms in compute_all_pairs

Important (Should fix before v0.1 release)

• SEC-003: Add NaN/Inf validation for signal data at pipeline entry points
• SEC-005: Add bounds check on HNSW entry point index
• PERF-002: Replace Vec::remove(0) with VecDeque in memory store
• PERF-003: Cache FFT planner across calls
• Add BrainGraph::validate() for edge index bounds and weight finiteness
• Add dimension consistency check to NeuralMemoryStore::store
• Remove unused workspace dependencies (petgraph, tokio, ruvector-*)

Recommended (Fix in v0.2)

• Implement zeroize-on-drop for NeuralEmbedding and NeuralMemoryStore
• Add strip_pii() to RvfFile
• Migrate Vec<Vec<f64>> matrices to ndarray::Array2<f64>
• Add Rayon parallelism for connectivity matrix computation
• Add criterion benchmarks for all crates
• Implement TDM protocol with CRC32 and node authentication
• Add cargo deny and cargo audit to CI
• Profile and optimize binary size for ESP32

Future (v0.3+)

• Encryption-at-rest for NeuralMemoryStore
• DTLS/TLS for ESP32 network protocol
• Sparse graph representation for large atlases
• f32 quantized embeddings for WASM
• Streaming signal processing pipeline
• GPU backend for large-scale spectral analysis

This document should be reviewed and updated after each milestone. All security findings should be verified as resolved before the corresponding release.