Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/crates/sona/src/engine.rs

@@ -0,0 +1,405 @@
+//! SONA Engine - Main interface for self-optimizing neural architecture
+
+use crate::loops::coordinator::{CoordinatorStats, LoopCoordinator};
+use crate::trajectory::TrajectoryBuilder;
+use crate::types::{QueryTrajectory, SonaConfig};
+
+/// Main SONA engine integrating all components
+pub struct SonaEngine {
+    /// Loop coordinator
+    coordinator: LoopCoordinator,
+    /// Configuration
+    config: SonaConfig,
+    /// Whether engine is enabled
+    enabled: bool,
+}
+
+impl std::fmt::Debug for SonaEngine {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("SonaEngine")
+            .field("config", &self.config)
+            .field("enabled", &self.enabled)
+            .finish_non_exhaustive()
+    }
+}
+
+impl SonaEngine {
+    /// Create new SONA engine with default config
+    pub fn new(hidden_dim: usize) -> Self {
+        Self::with_config(SonaConfig {
+            hidden_dim,
+            embedding_dim: hidden_dim,
+            ..Default::default()
+        })
+    }
+
+    /// Create with custom config
+    pub fn with_config(config: SonaConfig) -> Self {
+        Self {
+            coordinator: LoopCoordinator::with_config(config.clone()),
+            config,
+            enabled: true,
+        }
+    }
+
+    /// Start trajectory recording for a query
+    pub fn begin_trajectory(&self, query_embedding: Vec<f32>) -> TrajectoryBuilder {
+        let id = self.coordinator.next_trajectory_id();
+        TrajectoryBuilder::new(id, query_embedding)
+    }
+
+    /// Complete trajectory and submit for learning
+    pub fn end_trajectory(&self, builder: TrajectoryBuilder, quality: f32) {
+        if !self.enabled {
+            return;
+        }
+
+        let trajectory = builder.build(quality);
+        self.coordinator.on_inference(trajectory);
+    }
+
+    /// Submit pre-built trajectory
+    pub fn submit_trajectory(&self, trajectory: QueryTrajectory) {
+        if self.enabled {
+            self.coordinator.on_inference(trajectory);
+        }
+    }
+
+    /// Apply micro-LoRA to hidden states
+    pub fn apply_micro_lora(&self, input: &[f32], output: &mut [f32]) {
+        if !self.enabled {
+            return;
+        }
+
+        if let Some(lora) = self.coordinator.micro_lora().try_read() {
+            lora.forward(input, output);
+        }
+    }
+
+    /// Apply base-LoRA to layer output
+    pub fn apply_base_lora(&self, layer_idx: usize, input: &[f32], output: &mut [f32]) {
+        if !self.enabled {
+            return;
+        }
+
+        if let Some(lora) = self.coordinator.base_lora().try_read() {
+            lora.forward_layer(layer_idx, input, output);
+        }
+    }
+
+    /// Run background learning cycle if due
+    pub fn tick(&self) -> Option<String> {
+        if !self.enabled {
+            return None;
+        }
+
+        if let Some(result) = self.coordinator.maybe_run_background() {
+            Some(format!(
+                "Background cycle: {} trajectories -> {} patterns in {:?}",
+                result.trajectories_processed, result.patterns_extracted, result.elapsed
+            ))
+        } else {
+            None
+        }
+    }
+
+    /// Force background learning cycle
+    pub fn force_learn(&self) -> String {
+        let result = self.coordinator.force_background();
+        format!(
+            "Forced learning: {} trajectories -> {} patterns, status: {}",
+            result.trajectories_processed, result.patterns_extracted, result.status
+        )
+    }
+
+    /// Flush instant loop updates
+    pub fn flush(&self) {
+        self.coordinator.flush_instant();
+    }
+
+    /// Find similar patterns to query
+    pub fn find_patterns(&self, query_embedding: &[f32], k: usize) -> Vec<crate::LearnedPattern> {
+        self.coordinator
+            .reasoning_bank()
+            .read()
+            .find_similar(query_embedding, k)
+            .into_iter()
+            .cloned()
+            .collect()
+    }
+
+    /// Get engine statistics
+    pub fn stats(&self) -> CoordinatorStats {
+        self.coordinator.stats()
+    }
+
+    /// Enable/disable engine
+    pub fn set_enabled(&mut self, enabled: bool) {
+        self.enabled = enabled;
+    }
+
+    /// Check if enabled
+    pub fn is_enabled(&self) -> bool {
+        self.enabled
+    }
+
+    /// Get config
+    pub fn config(&self) -> &SonaConfig {
+        &self.config
+    }
+
+    /// Get all learned patterns from the reasoning bank
+    #[cfg(feature = "serde-support")]
+    pub fn get_all_patterns(&self) -> Vec<crate::LearnedPattern> {
+        self.coordinator.reasoning_bank().read().get_all_patterns()
+    }
+
+    /// Export LoRA state for serialization
+    #[cfg(feature = "serde-support")]
+    pub fn export_lora_state(&self) -> crate::export::safetensors::LoRAState {
+        use crate::export::safetensors::{LoRALayerState, LoRAState};
+
+        let mut state = LoRAState::default();
+
+        // Export MicroLoRA (single layer)
+        if let Some(lora) = self.coordinator.micro_lora().try_read() {
+            let (down, up) = lora.get_weights();
+            state.micro_lora_layers.push(LoRALayerState {
+                lora_a: down.clone(),
+                lora_b: up.clone(),
+                rank: self.config.micro_lora_rank,
+                input_dim: self.config.hidden_dim,
+                output_dim: self.config.hidden_dim,
+            });
+        }
+
+        // Export BaseLoRA (multi-layer)
+        if let Some(lora) = self.coordinator.base_lora().try_read() {
+            for idx in 0..lora.num_layers() {
+                if let Some((down, up)) = lora.get_layer_weights(idx) {
+                    state.base_lora_layers.push(LoRALayerState {
+                        lora_a: down.clone(),
+                        lora_b: up.clone(),
+                        rank: lora.rank,
+                        input_dim: lora.hidden_dim,
+                        output_dim: lora.hidden_dim,
+                    });
+                }
+            }
+        }
+
+        state
+    }
+
+    /// Get quality trajectories for preference learning export
+    #[cfg(feature = "serde-support")]
+    pub fn get_quality_trajectories(&self) -> Vec<crate::export::dataset::QualityTrajectory> {
+        use crate::export::dataset::QualityTrajectory;
+
+        // Get buffered trajectories from the instant loop via coordinator
+        let trajectories = self.coordinator.reasoning_bank().read().get_all_patterns();
+
+        trajectories
+            .iter()
+            .map(|p| {
+                QualityTrajectory {
+                    query_embedding: p.centroid.clone(),
+                    response_embedding: p.centroid.clone(), // Use centroid as proxy
+                    route: p.pattern_type.to_string(),
+                    quality: p.avg_quality,
+                    context_ids: vec![],
+                }
+            })
+            .collect()
+    }
+
+    /// Get routing decisions for distillation export
+    #[cfg(feature = "serde-support")]
+    pub fn get_routing_decisions(&self) -> Vec<crate::export::dataset::RoutingDecision> {
+        use crate::export::dataset::RoutingDecision;
+
+        let patterns = self.coordinator.reasoning_bank().read().get_all_patterns();
+
+        patterns
+            .iter()
+            .map(|p| {
+                RoutingDecision {
+                    query_embedding: p.centroid.clone(),
+                    routing_logits: vec![p.avg_quality], // Simplified
+                    selected_route: p.pattern_type.to_string(),
+                    confidence: p.avg_quality,
+                    quality: p.avg_quality,
+                }
+            })
+            .collect()
+    }
+}
+
+/// Builder for SonaEngine
+pub struct SonaEngineBuilder {
+    config: SonaConfig,
+}
+
+impl SonaEngineBuilder {
+    /// Create new builder
+    pub fn new() -> Self {
+        Self {
+            config: SonaConfig::default(),
+        }
+    }
+
+    /// Set hidden dimension
+    pub fn hidden_dim(mut self, dim: usize) -> Self {
+        self.config.hidden_dim = dim;
+        self.config.embedding_dim = dim;
+        self
+    }
+
+    /// Set micro-LoRA rank
+    pub fn micro_lora_rank(mut self, rank: usize) -> Self {
+        self.config.micro_lora_rank = rank.clamp(1, 2);
+        self
+    }
+
+    /// Set base-LoRA rank
+    pub fn base_lora_rank(mut self, rank: usize) -> Self {
+        self.config.base_lora_rank = rank;
+        self
+    }
+
+    /// Set micro-LoRA learning rate
+    pub fn micro_lr(mut self, lr: f32) -> Self {
+        self.config.micro_lora_lr = lr;
+        self
+    }
+
+    /// Set base-LoRA learning rate
+    pub fn base_lr(mut self, lr: f32) -> Self {
+        self.config.base_lora_lr = lr;
+        self
+    }
+
+    /// Set EWC lambda
+    pub fn ewc_lambda(mut self, lambda: f32) -> Self {
+        self.config.ewc_lambda = lambda;
+        self
+    }
+
+    /// Set pattern clusters
+    pub fn pattern_clusters(mut self, k: usize) -> Self {
+        self.config.pattern_clusters = k;
+        self
+    }
+
+    /// Set trajectory buffer capacity
+    pub fn buffer_capacity(mut self, capacity: usize) -> Self {
+        self.config.trajectory_capacity = capacity;
+        self
+    }
+
+    /// Set quality threshold
+    pub fn quality_threshold(mut self, threshold: f32) -> Self {
+        self.config.quality_threshold = threshold;
+        self
+    }
+
+    /// Build the engine
+    pub fn build(self) -> SonaEngine {
+        SonaEngine::with_config(self.config)
+    }
+}
+
+impl Default for SonaEngineBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::types::TrajectoryStep;
+
+    #[test]
+    fn test_engine_creation() {
+        let engine = SonaEngine::new(256);
+        assert!(engine.is_enabled());
+    }
+
+    #[test]
+    fn test_builder() {
+        let engine = SonaEngineBuilder::new()
+            .hidden_dim(512)
+            .micro_lora_rank(2)
+            .base_lora_rank(16)
+            .micro_lr(0.002)
+            .ewc_lambda(500.0)
+            .build();
+
+        assert_eq!(engine.config().hidden_dim, 512);
+        assert_eq!(engine.config().micro_lora_rank, 2);
+    }
+
+    #[test]
+    fn test_trajectory_workflow() {
+        let engine = SonaEngine::new(64);
+
+        // Begin trajectory
+        let mut builder = engine.begin_trajectory(vec![0.1; 64]);
+        builder.add_step(vec![0.5; 64], vec![], 0.8);
+        builder.add_step(vec![0.6; 64], vec![], 0.9);
+
+        // End trajectory
+        engine.end_trajectory(builder, 0.85);
+
+        let stats = engine.stats();
+        assert_eq!(stats.trajectories_buffered, 1);
+    }
+
+    #[test]
+    fn test_micro_lora_application() {
+        let engine = SonaEngine::new(64);
+
+        // Train a bit first
+        for i in 0..10 {
+            let mut builder = engine.begin_trajectory(vec![0.1; 64]);
+            builder.add_step(vec![0.5; 64], vec![], 0.8);
+            engine.end_trajectory(builder, 0.8);
+        }
+        engine.flush();
+
+        // Apply LoRA
+        let input = vec![1.0; 64];
+        let mut output = vec![0.0; 64];
+        engine.apply_micro_lora(&input, &mut output);
+
+        // Output may or may not be modified depending on accumulated gradients
+    }
+
+    #[test]
+    fn test_force_learn() {
+        let engine = SonaEngine::new(256);
+
+        for i in 0..150 {
+            let mut builder = engine.begin_trajectory(vec![0.1; 256]);
+            builder.add_step(vec![0.5; 256], vec![], 0.8);
+            engine.end_trajectory(builder, 0.8);
+        }
+
+        let result = engine.force_learn();
+        assert!(result.contains("150 trajectories"));
+    }
+
+    #[test]
+    fn test_disabled_engine() {
+        let mut engine = SonaEngine::new(64);
+        engine.set_enabled(false);
+
+        let builder = engine.begin_trajectory(vec![0.1; 64]);
+        engine.end_trajectory(builder, 0.8);
+
+        // Should not record when disabled
+        let stats = engine.stats();
+        assert_eq!(stats.trajectories_buffered, 0);
+    }
+}

vendor/ruvector/crates/sona/src/ewc.rs

@@ -0,0 +1,499 @@
+//! EWC++ (Enhanced Elastic Weight Consolidation) for SONA
+//!
+//! Prevents catastrophic forgetting with:
+//! - Online Fisher information estimation
+//! - Multi-task memory with circular buffer
+//! - Automatic task boundary detection
+//! - Adaptive lambda scheduling
+
+use serde::{Deserialize, Serialize};
+use std::collections::VecDeque;
+
+/// EWC++ configuration
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct EwcConfig {
+    /// Number of parameters
+    pub param_count: usize,
+    /// Maximum tasks to remember
+    pub max_tasks: usize,
+    /// Initial lambda
+    pub initial_lambda: f32,
+    /// Minimum lambda
+    pub min_lambda: f32,
+    /// Maximum lambda
+    pub max_lambda: f32,
+    /// Fisher EMA decay factor
+    pub fisher_ema_decay: f32,
+    /// Task boundary detection threshold
+    pub boundary_threshold: f32,
+    /// Gradient history for boundary detection
+    pub gradient_history_size: usize,
+}
+
+impl Default for EwcConfig {
+    fn default() -> Self {
+        // OPTIMIZED DEFAULTS based on @ruvector/sona v0.1.1 benchmarks:
+        // - Lambda 2000 optimal for catastrophic forgetting prevention
+        // - Higher max_lambda (15000) for aggressive protection when needed
+        Self {
+            param_count: 1000,
+            max_tasks: 10,
+            initial_lambda: 2000.0, // OPTIMIZED: Better forgetting prevention
+            min_lambda: 100.0,
+            max_lambda: 15000.0, // OPTIMIZED: Higher ceiling for multi-task
+            fisher_ema_decay: 0.999,
+            boundary_threshold: 2.0,
+            gradient_history_size: 100,
+        }
+    }
+}
+
+/// Task-specific Fisher information
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TaskFisher {
+    /// Task ID
+    pub task_id: usize,
+    /// Fisher diagonal
+    pub fisher: Vec<f32>,
+    /// Optimal weights for this task
+    pub optimal_weights: Vec<f32>,
+    /// Task importance (for weighted consolidation)
+    pub importance: f32,
+}
+
+/// EWC++ implementation
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct EwcPlusPlus {
+    /// Configuration
+    config: EwcConfig,
+    /// Current Fisher information (online estimate)
+    current_fisher: Vec<f32>,
+    /// Current optimal weights
+    current_weights: Vec<f32>,
+    /// Task memory (circular buffer)
+    task_memory: VecDeque<TaskFisher>,
+    /// Current task ID
+    current_task_id: usize,
+    /// Current lambda
+    lambda: f32,
+    /// Gradient history for boundary detection
+    gradient_history: VecDeque<Vec<f32>>,
+    /// Running gradient mean
+    gradient_mean: Vec<f32>,
+    /// Running gradient variance
+    gradient_var: Vec<f32>,
+    /// Samples seen for current task
+    samples_seen: u64,
+}
+
+impl EwcPlusPlus {
+    /// Create new EWC++
+    pub fn new(config: EwcConfig) -> Self {
+        let param_count = config.param_count;
+        let initial_lambda = config.initial_lambda;
+
+        Self {
+            config: config.clone(),
+            current_fisher: vec![0.0; param_count],
+            current_weights: vec![0.0; param_count],
+            task_memory: VecDeque::with_capacity(config.max_tasks),
+            current_task_id: 0,
+            lambda: initial_lambda,
+            gradient_history: VecDeque::with_capacity(config.gradient_history_size),
+            gradient_mean: vec![0.0; param_count],
+            gradient_var: vec![1.0; param_count],
+            samples_seen: 0,
+        }
+    }
+
+    /// Update Fisher information online using EMA
+    pub fn update_fisher(&mut self, gradients: &[f32]) {
+        if gradients.len() != self.config.param_count {
+            return;
+        }
+
+        let decay = self.config.fisher_ema_decay;
+
+        // Online Fisher update: F_t = decay * F_{t-1} + (1 - decay) * g^2
+        for (i, &g) in gradients.iter().enumerate() {
+            self.current_fisher[i] = decay * self.current_fisher[i] + (1.0 - decay) * g * g;
+        }
+
+        // Update gradient statistics for boundary detection
+        self.update_gradient_stats(gradients);
+        self.samples_seen += 1;
+    }
+
+    /// Update gradient statistics for boundary detection
+    fn update_gradient_stats(&mut self, gradients: &[f32]) {
+        // Store in history
+        if self.gradient_history.len() >= self.config.gradient_history_size {
+            self.gradient_history.pop_front();
+        }
+        self.gradient_history.push_back(gradients.to_vec());
+
+        // Update running mean and variance (Welford's algorithm)
+        let n = self.samples_seen as f32 + 1.0;
+
+        for (i, &g) in gradients.iter().enumerate() {
+            let delta = g - self.gradient_mean[i];
+            self.gradient_mean[i] += delta / n;
+            let delta2 = g - self.gradient_mean[i];
+            self.gradient_var[i] += delta * delta2;
+        }
+    }
+
+    /// Detect task boundary using distribution shift
+    pub fn detect_task_boundary(&self, gradients: &[f32]) -> bool {
+        if self.samples_seen < 50 || gradients.len() != self.config.param_count {
+            return false;
+        }
+
+        // Compute z-score of current gradients vs running stats
+        let mut z_score_sum = 0.0f32;
+        let mut count = 0;
+
+        for (i, &g) in gradients.iter().enumerate() {
+            let var = self.gradient_var[i] / self.samples_seen as f32;
+            if var > 1e-8 {
+                let std = var.sqrt();
+                let z = (g - self.gradient_mean[i]).abs() / std;
+                z_score_sum += z;
+                count += 1;
+            }
+        }
+
+        if count == 0 {
+            return false;
+        }
+
+        let avg_z = z_score_sum / count as f32;
+        avg_z > self.config.boundary_threshold
+    }
+
+    /// Start new task - saves current Fisher to memory
+    pub fn start_new_task(&mut self) {
+        // Save current task's Fisher
+        let task_fisher = TaskFisher {
+            task_id: self.current_task_id,
+            fisher: self.current_fisher.clone(),
+            optimal_weights: self.current_weights.clone(),
+            importance: 1.0,
+        };
+
+        // Add to circular buffer
+        if self.task_memory.len() >= self.config.max_tasks {
+            self.task_memory.pop_front();
+        }
+        self.task_memory.push_back(task_fisher);
+
+        // Reset for new task
+        self.current_task_id += 1;
+        self.current_fisher.fill(0.0);
+        self.gradient_history.clear();
+        self.gradient_mean.fill(0.0);
+        self.gradient_var.fill(1.0);
+        self.samples_seen = 0;
+
+        // Adapt lambda based on task count
+        self.adapt_lambda();
+    }
+
+    /// Adapt lambda based on accumulated tasks
+    fn adapt_lambda(&mut self) {
+        let task_count = self.task_memory.len();
+        if task_count == 0 {
+            return;
+        }
+
+        // Increase lambda as more tasks accumulate (more to protect)
+        let scale = 1.0 + 0.1 * task_count as f32;
+        self.lambda = (self.config.initial_lambda * scale)
+            .clamp(self.config.min_lambda, self.config.max_lambda);
+    }
+
+    /// Apply EWC++ constraints to gradients
+    pub fn apply_constraints(&self, gradients: &[f32]) -> Vec<f32> {
+        if gradients.len() != self.config.param_count {
+            return gradients.to_vec();
+        }
+
+        let mut constrained = gradients.to_vec();
+
+        // Apply constraint from each remembered task
+        for task in &self.task_memory {
+            for (i, g) in constrained.iter_mut().enumerate() {
+                // Penalty: lambda * F_i * (w_i - w*_i)
+                // Gradient of penalty: lambda * F_i
+                // Project gradient to preserve important weights
+                let importance = task.fisher[i] * task.importance;
+                if importance > 1e-8 {
+                    let penalty_grad = self.lambda * importance;
+                    // Reduce gradient magnitude for important parameters
+                    *g *= 1.0 / (1.0 + penalty_grad);
+                }
+            }
+        }
+
+        // Also apply current task's Fisher (online)
+        for (i, g) in constrained.iter_mut().enumerate() {
+            if self.current_fisher[i] > 1e-8 {
+                let penalty_grad = self.lambda * self.current_fisher[i] * 0.1; // Lower weight for current
+                *g *= 1.0 / (1.0 + penalty_grad);
+            }
+        }
+
+        constrained
+    }
+
+    /// Compute EWC regularization loss
+    pub fn regularization_loss(&self, current_weights: &[f32]) -> f32 {
+        if current_weights.len() != self.config.param_count {
+            return 0.0;
+        }
+
+        let mut loss = 0.0f32;
+
+        for task in &self.task_memory {
+            for ((&cw, &ow), &fi) in current_weights
+                .iter()
+                .zip(task.optimal_weights.iter())
+                .zip(task.fisher.iter())
+                .take(self.config.param_count)
+            {
+                let diff = cw - ow;
+                loss += fi * diff * diff * task.importance;
+            }
+        }
+
+        self.lambda * loss / 2.0
+    }
+
+    /// Update optimal weights reference
+    pub fn set_optimal_weights(&mut self, weights: &[f32]) {
+        if weights.len() == self.config.param_count {
+            self.current_weights.copy_from_slice(weights);
+        }
+    }
+
+    /// Consolidate all tasks (merge Fisher information)
+    pub fn consolidate_all_tasks(&mut self) {
+        if self.task_memory.is_empty() {
+            return;
+        }
+
+        // Compute weighted average of Fisher matrices
+        let mut consolidated_fisher = vec![0.0f32; self.config.param_count];
+        let mut total_importance = 0.0f32;
+
+        for task in &self.task_memory {
+            for (i, &f) in task.fisher.iter().enumerate() {
+                consolidated_fisher[i] += f * task.importance;
+            }
+            total_importance += task.importance;
+        }
+
+        if total_importance > 0.0 {
+            for f in &mut consolidated_fisher {
+                *f /= total_importance;
+            }
+        }
+
+        // Store as single consolidated task
+        let consolidated = TaskFisher {
+            task_id: 0,
+            fisher: consolidated_fisher,
+            optimal_weights: self.current_weights.clone(),
+            importance: total_importance,
+        };
+
+        self.task_memory.clear();
+        self.task_memory.push_back(consolidated);
+    }
+
+    /// Get current lambda
+    pub fn lambda(&self) -> f32 {
+        self.lambda
+    }
+
+    /// Set lambda manually
+    pub fn set_lambda(&mut self, lambda: f32) {
+        self.lambda = lambda.clamp(self.config.min_lambda, self.config.max_lambda);
+    }
+
+    /// Get task count
+    pub fn task_count(&self) -> usize {
+        self.task_memory.len()
+    }
+
+    /// Get current task ID
+    pub fn current_task_id(&self) -> usize {
+        self.current_task_id
+    }
+
+    /// Get samples seen for current task
+    pub fn samples_seen(&self) -> u64 {
+        self.samples_seen
+    }
+
+    /// Get parameter importance scores
+    pub fn importance_scores(&self) -> Vec<f32> {
+        let mut scores = self.current_fisher.clone();
+
+        for task in &self.task_memory {
+            for (i, &f) in task.fisher.iter().enumerate() {
+                scores[i] += f * task.importance;
+            }
+        }
+
+        scores
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_ewc_creation() {
+        let config = EwcConfig {
+            param_count: 100,
+            ..Default::default()
+        };
+        let ewc = EwcPlusPlus::new(config);
+
+        assert_eq!(ewc.task_count(), 0);
+        assert_eq!(ewc.current_task_id(), 0);
+    }
+
+    #[test]
+    fn test_fisher_update() {
+        let config = EwcConfig {
+            param_count: 10,
+            ..Default::default()
+        };
+        let mut ewc = EwcPlusPlus::new(config);
+
+        let gradients = vec![0.5; 10];
+        ewc.update_fisher(&gradients);
+
+        assert!(ewc.samples_seen() > 0);
+        assert!(ewc.current_fisher.iter().any(|&f| f > 0.0));
+    }
+
+    #[test]
+    fn test_task_boundary() {
+        let config = EwcConfig {
+            param_count: 10,
+            gradient_history_size: 10,
+            boundary_threshold: 2.0,
+            ..Default::default()
+        };
+        let mut ewc = EwcPlusPlus::new(config);
+
+        // Train on consistent gradients
+        for _ in 0..60 {
+            let gradients = vec![0.1; 10];
+            ewc.update_fisher(&gradients);
+        }
+
+        // Normal gradient should not trigger boundary
+        let normal = vec![0.1; 10];
+        assert!(!ewc.detect_task_boundary(&normal));
+
+        // Very different gradient might trigger boundary
+        let different = vec![10.0; 10];
+        // May or may not trigger depending on variance
+    }
+
+    #[test]
+    fn test_constraint_application() {
+        let config = EwcConfig {
+            param_count: 5,
+            ..Default::default()
+        };
+        let mut ewc = EwcPlusPlus::new(config);
+
+        // Build up some Fisher information
+        for _ in 0..10 {
+            ewc.update_fisher(&vec![1.0; 5]);
+        }
+        ewc.start_new_task();
+
+        // Apply constraints
+        let gradients = vec![1.0; 5];
+        let constrained = ewc.apply_constraints(&gradients);
+
+        // Constrained gradients should be smaller
+        let orig_mag: f32 = gradients.iter().map(|x| x.abs()).sum();
+        let const_mag: f32 = constrained.iter().map(|x| x.abs()).sum();
+        assert!(const_mag <= orig_mag);
+    }
+
+    #[test]
+    fn test_regularization_loss() {
+        let config = EwcConfig {
+            param_count: 5,
+            initial_lambda: 100.0,
+            ..Default::default()
+        };
+        let mut ewc = EwcPlusPlus::new(config);
+
+        // Set up optimal weights and Fisher
+        ewc.set_optimal_weights(&vec![0.0; 5]);
+        for _ in 0..10 {
+            ewc.update_fisher(&vec![1.0; 5]);
+        }
+        ewc.start_new_task();
+
+        // Loss should be zero when at optimal
+        let at_optimal = ewc.regularization_loss(&vec![0.0; 5]);
+
+        // Loss should be positive when deviated
+        let deviated = ewc.regularization_loss(&vec![1.0; 5]);
+        assert!(deviated > at_optimal);
+    }
+
+    #[test]
+    fn test_task_consolidation() {
+        let config = EwcConfig {
+            param_count: 5,
+            max_tasks: 5,
+            ..Default::default()
+        };
+        let mut ewc = EwcPlusPlus::new(config);
+
+        // Create multiple tasks
+        for _ in 0..3 {
+            for _ in 0..10 {
+                ewc.update_fisher(&vec![1.0; 5]);
+            }
+            ewc.start_new_task();
+        }
+
+        assert_eq!(ewc.task_count(), 3);
+
+        ewc.consolidate_all_tasks();
+        assert_eq!(ewc.task_count(), 1);
+    }
+
+    #[test]
+    fn test_lambda_adaptation() {
+        let config = EwcConfig {
+            param_count: 5,
+            initial_lambda: 1000.0,
+            ..Default::default()
+        };
+        let mut ewc = EwcPlusPlus::new(config);
+
+        let initial_lambda = ewc.lambda();
+
+        // Add tasks
+        for _ in 0..5 {
+            ewc.start_new_task();
+        }
+
+        // Lambda should have increased
+        assert!(ewc.lambda() >= initial_lambda);
+    }
+}

vendor/ruvector/crates/sona/src/export/dataset.rs

@@ -0,0 +1,406 @@
+//! Dataset Export - HuggingFace-compatible dataset formats
+//!
+//! Exports SONA's learned patterns and preference pairs as JSONL datasets
+//! compatible with HuggingFace's datasets library.
+
+use super::{ExportConfig, ExportError, ExportResult, ExportType};
+use crate::engine::SonaEngine;
+use std::io::{BufWriter, Write};
+use std::path::Path;
+
+#[cfg(feature = "serde-support")]
+use serde::{Deserialize, Serialize};
+
+/// Dataset exporter for patterns and preferences
+pub struct DatasetExporter<'a> {
+    config: &'a ExportConfig,
+}
+
+impl<'a> DatasetExporter<'a> {
+    /// Create new dataset exporter
+    pub fn new(config: &'a ExportConfig) -> Self {
+        Self { config }
+    }
+
+    /// Export learned patterns as JSONL dataset
+    pub fn export_patterns<P: AsRef<Path>>(
+        &self,
+        engine: &SonaEngine,
+        output_path: P,
+    ) -> Result<ExportResult, ExportError> {
+        let output_path = output_path.as_ref();
+
+        // Ensure parent directory exists
+        if let Some(parent) = output_path.parent() {
+            std::fs::create_dir_all(parent).map_err(ExportError::Io)?;
+        }
+
+        let file = std::fs::File::create(output_path).map_err(ExportError::Io)?;
+        let mut writer = BufWriter::new(file);
+
+        let patterns = engine.get_all_patterns();
+        let mut items_exported = 0;
+
+        for pattern in patterns {
+            // Filter by quality threshold
+            if pattern.avg_quality < self.config.min_quality_threshold {
+                continue;
+            }
+
+            let record = PatternRecord {
+                id: pattern.id.to_string(),
+                embedding: pattern.centroid.clone(),
+                cluster_size: pattern.cluster_size,
+                avg_quality: pattern.avg_quality,
+                pattern_type: pattern.pattern_type.to_string(),
+                access_count: pattern.access_count as u64,
+                metadata: PatternMetadata {
+                    source: "sona".to_string(),
+                    version: env!("CARGO_PKG_VERSION").to_string(),
+                    target_model: self.config.target_architecture.clone(),
+                },
+            };
+
+            let json = serde_json::to_string(&record).map_err(ExportError::Serialization)?;
+            writeln!(writer, "{}", json).map_err(ExportError::Io)?;
+            items_exported += 1;
+        }
+
+        writer.flush().map_err(ExportError::Io)?;
+
+        let size_bytes = std::fs::metadata(output_path).map(|m| m.len()).unwrap_or(0);
+
+        Ok(ExportResult {
+            export_type: ExportType::PatternsDataset,
+            items_exported,
+            output_path: output_path.to_string_lossy().to_string(),
+            size_bytes,
+        })
+    }
+
+    /// Export preference pairs for DPO/RLHF training
+    pub fn export_preferences<P: AsRef<Path>>(
+        &self,
+        engine: &SonaEngine,
+        output_path: P,
+    ) -> Result<ExportResult, ExportError> {
+        let output_path = output_path.as_ref();
+
+        // Ensure parent directory exists
+        if let Some(parent) = output_path.parent() {
+            std::fs::create_dir_all(parent).map_err(ExportError::Io)?;
+        }
+
+        let file = std::fs::File::create(output_path).map_err(ExportError::Io)?;
+        let mut writer = BufWriter::new(file);
+
+        let trajectories = engine.get_quality_trajectories();
+        let mut items_exported = 0;
+
+        // Generate preference pairs from trajectories
+        // Sort by quality and pair high-quality with low-quality
+        let mut sorted_trajectories = trajectories.clone();
+        sorted_trajectories.sort_by(|a, b| {
+            b.quality
+                .partial_cmp(&a.quality)
+                .unwrap_or(std::cmp::Ordering::Equal)
+        });
+
+        let mid = sorted_trajectories.len() / 2;
+        let (high_quality, low_quality) = sorted_trajectories.split_at(mid);
+
+        for (chosen, rejected) in high_quality.iter().zip(low_quality.iter().rev()) {
+            // Skip if quality difference is too small
+            if (chosen.quality - rejected.quality).abs() < 0.1 {
+                continue;
+            }
+
+            let pair = PreferencePair {
+                prompt: PreferencePrompt {
+                    embedding: chosen.query_embedding.clone(),
+                    context: chosen.context_ids.clone(),
+                },
+                chosen: PreferenceResponse {
+                    route: chosen.route.clone(),
+                    quality: chosen.quality,
+                    embedding: chosen.response_embedding.clone(),
+                },
+                rejected: PreferenceResponse {
+                    route: rejected.route.clone(),
+                    quality: rejected.quality,
+                    embedding: rejected.response_embedding.clone(),
+                },
+                metadata: PreferenceMetadata {
+                    quality_delta: chosen.quality - rejected.quality,
+                    source: "sona".to_string(),
+                    version: env!("CARGO_PKG_VERSION").to_string(),
+                },
+            };
+
+            let json = serde_json::to_string(&pair).map_err(ExportError::Serialization)?;
+            writeln!(writer, "{}", json).map_err(ExportError::Io)?;
+            items_exported += 1;
+        }
+
+        writer.flush().map_err(ExportError::Io)?;
+
+        let size_bytes = std::fs::metadata(output_path).map(|m| m.len()).unwrap_or(0);
+
+        Ok(ExportResult {
+            export_type: ExportType::PreferencePairs,
+            items_exported,
+            output_path: output_path.to_string_lossy().to_string(),
+            size_bytes,
+        })
+    }
+
+    /// Export distillation targets for knowledge distillation
+    pub fn export_distillation_targets<P: AsRef<Path>>(
+        &self,
+        engine: &SonaEngine,
+        output_path: P,
+    ) -> Result<ExportResult, ExportError> {
+        let output_path = output_path.as_ref();
+
+        // Ensure parent directory exists
+        if let Some(parent) = output_path.parent() {
+            std::fs::create_dir_all(parent).map_err(ExportError::Io)?;
+        }
+
+        let file = std::fs::File::create(output_path).map_err(ExportError::Io)?;
+        let mut writer = BufWriter::new(file);
+
+        let routing_decisions = engine.get_routing_decisions();
+        let mut items_exported = 0;
+
+        for decision in routing_decisions {
+            // Filter by quality
+            if decision.quality < self.config.min_quality_threshold {
+                continue;
+            }
+
+            let target = DistillationTarget {
+                input_embedding: decision.query_embedding.clone(),
+                teacher_logits: decision.routing_logits.clone(),
+                selected_route: decision.selected_route.clone(),
+                confidence: decision.confidence,
+                quality: decision.quality,
+                metadata: DistillationMetadata {
+                    source: "sona".to_string(),
+                    version: env!("CARGO_PKG_VERSION").to_string(),
+                    temperature: 1.0,
+                },
+            };
+
+            let json = serde_json::to_string(&target).map_err(ExportError::Serialization)?;
+            writeln!(writer, "{}", json).map_err(ExportError::Io)?;
+            items_exported += 1;
+        }
+
+        writer.flush().map_err(ExportError::Io)?;
+
+        let size_bytes = std::fs::metadata(output_path).map(|m| m.len()).unwrap_or(0);
+
+        Ok(ExportResult {
+            export_type: ExportType::DistillationTargets,
+            items_exported,
+            output_path: output_path.to_string_lossy().to_string(),
+            size_bytes,
+        })
+    }
+}
+
+/// Pattern record for JSONL export
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct PatternRecord {
+    /// Pattern ID
+    pub id: String,
+    /// Embedding vector
+    pub embedding: Vec<f32>,
+    /// Number of trajectories in cluster
+    pub cluster_size: usize,
+    /// Average quality score
+    pub avg_quality: f32,
+    /// Pattern type (routing, reasoning, etc.)
+    pub pattern_type: String,
+    /// Access count
+    pub access_count: u64,
+    /// Export metadata
+    pub metadata: PatternMetadata,
+}
+
+/// Pattern export metadata
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct PatternMetadata {
+    /// Source system
+    pub source: String,
+    /// Version
+    pub version: String,
+    /// Target model architecture
+    pub target_model: String,
+}
+
+/// Preference pair for DPO/RLHF
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct PreferencePair {
+    /// Input prompt
+    pub prompt: PreferencePrompt,
+    /// Chosen (preferred) response
+    pub chosen: PreferenceResponse,
+    /// Rejected response
+    pub rejected: PreferenceResponse,
+    /// Metadata
+    pub metadata: PreferenceMetadata,
+}
+
+/// Preference prompt
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct PreferencePrompt {
+    /// Query embedding
+    pub embedding: Vec<f32>,
+    /// Context IDs
+    pub context: Vec<String>,
+}
+
+/// Preference response
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct PreferenceResponse {
+    /// Model route
+    pub route: String,
+    /// Quality score
+    pub quality: f32,
+    /// Response embedding
+    pub embedding: Vec<f32>,
+}
+
+/// Preference pair metadata
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct PreferenceMetadata {
+    /// Quality difference between chosen and rejected
+    pub quality_delta: f32,
+    /// Source system
+    pub source: String,
+    /// Version
+    pub version: String,
+}
+
+/// Distillation target for knowledge distillation
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct DistillationTarget {
+    /// Input embedding
+    pub input_embedding: Vec<f32>,
+    /// Teacher model logits
+    pub teacher_logits: Vec<f32>,
+    /// Selected route
+    pub selected_route: String,
+    /// Confidence score
+    pub confidence: f32,
+    /// Quality score
+    pub quality: f32,
+    /// Metadata
+    pub metadata: DistillationMetadata,
+}
+
+/// Distillation metadata
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct DistillationMetadata {
+    /// Source system
+    pub source: String,
+    /// Version
+    pub version: String,
+    /// Temperature for softmax
+    pub temperature: f32,
+}
+
+/// Quality trajectory for preference learning
+#[derive(Clone, Debug)]
+pub struct QualityTrajectory {
+    /// Query embedding
+    pub query_embedding: Vec<f32>,
+    /// Response embedding
+    pub response_embedding: Vec<f32>,
+    /// Model route
+    pub route: String,
+    /// Quality score
+    pub quality: f32,
+    /// Context IDs
+    pub context_ids: Vec<String>,
+}
+
+/// Routing decision for distillation
+#[derive(Clone, Debug)]
+pub struct RoutingDecision {
+    /// Query embedding
+    pub query_embedding: Vec<f32>,
+    /// Routing logits
+    pub routing_logits: Vec<f32>,
+    /// Selected route
+    pub selected_route: String,
+    /// Confidence
+    pub confidence: f32,
+    /// Quality
+    pub quality: f32,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_pattern_record() {
+        let record = PatternRecord {
+            id: "test-pattern".to_string(),
+            embedding: vec![0.1, 0.2, 0.3],
+            cluster_size: 10,
+            avg_quality: 0.85,
+            pattern_type: "routing".to_string(),
+            access_count: 100,
+            metadata: PatternMetadata {
+                source: "sona".to_string(),
+                version: "0.1.0".to_string(),
+                target_model: "phi-4".to_string(),
+            },
+        };
+
+        let json = serde_json::to_string(&record).unwrap();
+        assert!(json.contains("test-pattern"));
+        assert!(json.contains("0.85"));
+    }
+
+    #[test]
+    fn test_preference_pair() {
+        let pair = PreferencePair {
+            prompt: PreferencePrompt {
+                embedding: vec![0.1, 0.2],
+                context: vec!["ctx1".to_string()],
+            },
+            chosen: PreferenceResponse {
+                route: "gpt-4".to_string(),
+                quality: 0.9,
+                embedding: vec![0.3, 0.4],
+            },
+            rejected: PreferenceResponse {
+                route: "gpt-3.5".to_string(),
+                quality: 0.6,
+                embedding: vec![0.5, 0.6],
+            },
+            metadata: PreferenceMetadata {
+                quality_delta: 0.3,
+                source: "sona".to_string(),
+                version: "0.1.0".to_string(),
+            },
+        };
+
+        let json = serde_json::to_string(&pair).unwrap();
+        assert!(json.contains("gpt-4"));
+        assert!(json.contains("0.9"));
+    }
+}

vendor/ruvector/crates/sona/src/export/huggingface_hub.rs

@@ -0,0 +1,485 @@
+//! HuggingFace Hub Integration
+//!
+//! Direct integration with HuggingFace Hub API for uploading SONA models,
+//! patterns, and datasets.
+
+use super::{
+    DatasetExporter, ExportConfig, ExportError, ExportResult, ExportType, SafeTensorsExporter,
+};
+use crate::engine::SonaEngine;
+use std::path::Path;
+
+#[cfg(feature = "serde-support")]
+use serde::{Deserialize, Serialize};
+
+/// HuggingFace Hub client
+pub struct HuggingFaceHub {
+    /// API token (optional for public repos)
+    token: Option<String>,
+    /// API base URL
+    api_url: String,
+}
+
+impl HuggingFaceHub {
+    /// Create new Hub client
+    pub fn new(token: Option<&str>) -> Self {
+        Self {
+            token: token.map(|t| t.to_string()),
+            api_url: "https://huggingface.co/api".to_string(),
+        }
+    }
+
+    /// Create Hub client from environment variable
+    pub fn from_env() -> Self {
+        let token = std::env::var("HF_TOKEN")
+            .or_else(|_| std::env::var("HUGGING_FACE_HUB_TOKEN"))
+            .ok();
+        Self::new(token.as_deref())
+    }
+
+    /// Push all exports to HuggingFace Hub
+    pub fn push_all(
+        &self,
+        engine: &SonaEngine,
+        config: &ExportConfig,
+        repo_id: &str,
+    ) -> Result<ExportResult, ExportError> {
+        // Create temporary directory for exports
+        let temp_dir = std::env::temp_dir().join(format!("sona-export-{}", uuid_v4()));
+        std::fs::create_dir_all(&temp_dir).map_err(ExportError::Io)?;
+
+        // Export all components to temp directory
+        let safetensors_exporter = SafeTensorsExporter::new(config);
+        let dataset_exporter = DatasetExporter::new(config);
+
+        let mut total_items = 0;
+        let mut total_size = 0u64;
+
+        // Export LoRA weights
+        if config.include_lora {
+            let result = safetensors_exporter.export_engine(engine, temp_dir.join("lora"))?;
+            total_items += result.items_exported;
+            total_size += result.size_bytes;
+        }
+
+        // Export patterns
+        if config.include_patterns {
+            let result =
+                dataset_exporter.export_patterns(engine, temp_dir.join("patterns.jsonl"))?;
+            total_items += result.items_exported;
+            total_size += result.size_bytes;
+        }
+
+        // Export preferences
+        if config.include_preferences {
+            let result =
+                dataset_exporter.export_preferences(engine, temp_dir.join("preferences.jsonl"))?;
+            total_items += result.items_exported;
+            total_size += result.size_bytes;
+        }
+
+        // Create model card
+        let readme = self.create_model_card(engine, config);
+        let readme_path = temp_dir.join("README.md");
+        std::fs::write(&readme_path, readme).map_err(ExportError::Io)?;
+
+        // Create adapter config
+        let adapter_config = self.create_adapter_config(engine, config);
+        let config_path = temp_dir.join("adapter_config.json");
+        let config_json = serde_json::to_string_pretty(&adapter_config)?;
+        std::fs::write(&config_path, config_json).map_err(ExportError::Io)?;
+
+        // Upload to Hub (using git LFS approach)
+        self.upload_directory(&temp_dir, repo_id)?;
+
+        // Cleanup
+        let _ = std::fs::remove_dir_all(&temp_dir);
+
+        Ok(ExportResult {
+            export_type: ExportType::SafeTensors,
+            items_exported: total_items,
+            output_path: format!("https://huggingface.co/{}", repo_id),
+            size_bytes: total_size,
+        })
+    }
+
+    /// Upload directory to HuggingFace Hub
+    fn upload_directory(&self, local_path: &Path, repo_id: &str) -> Result<(), ExportError> {
+        // Check for git and git-lfs
+        let has_git = std::process::Command::new("git")
+            .arg("--version")
+            .output()
+            .is_ok();
+
+        if !has_git {
+            return Err(ExportError::HubError(
+                "git is required for HuggingFace Hub upload. Install git and git-lfs.".to_string(),
+            ));
+        }
+
+        // Clone or create repo
+        let repo_url = if let Some(ref token) = self.token {
+            format!("https://{}@huggingface.co/{}", token, repo_id)
+        } else {
+            format!("https://huggingface.co/{}", repo_id)
+        };
+
+        let clone_dir = local_path.parent().unwrap().join("hf-repo");
+
+        // Try to clone existing repo
+        let clone_result = std::process::Command::new("git")
+            .args(["clone", &repo_url, clone_dir.to_str().unwrap()])
+            .output();
+
+        if clone_result.is_err() {
+            // Create new repo via API
+            self.create_repo(repo_id)?;
+
+            // Try cloning again
+            std::process::Command::new("git")
+                .args(["clone", &repo_url, clone_dir.to_str().unwrap()])
+                .output()
+                .map_err(|e| ExportError::HubError(format!("Failed to clone repo: {}", e)))?;
+        }
+
+        // Copy files to cloned repo
+        copy_dir_recursive(local_path, &clone_dir)?;
+
+        // Add, commit, and push
+        std::process::Command::new("git")
+            .args(["-C", clone_dir.to_str().unwrap(), "add", "-A"])
+            .output()
+            .map_err(|e| ExportError::HubError(format!("git add failed: {}", e)))?;
+
+        std::process::Command::new("git")
+            .args([
+                "-C",
+                clone_dir.to_str().unwrap(),
+                "commit",
+                "-m",
+                "Upload SONA adapter",
+            ])
+            .output()
+            .map_err(|e| ExportError::HubError(format!("git commit failed: {}", e)))?;
+
+        let push_result = std::process::Command::new("git")
+            .args(["-C", clone_dir.to_str().unwrap(), "push"])
+            .output()
+            .map_err(|e| ExportError::HubError(format!("git push failed: {}", e)))?;
+
+        if !push_result.status.success() {
+            let stderr = String::from_utf8_lossy(&push_result.stderr);
+            return Err(ExportError::HubError(format!(
+                "git push failed: {}",
+                stderr
+            )));
+        }
+
+        // Cleanup
+        let _ = std::fs::remove_dir_all(&clone_dir);
+
+        Ok(())
+    }
+
+    /// Create a new repository on HuggingFace Hub
+    fn create_repo(&self, repo_id: &str) -> Result<(), ExportError> {
+        let token = self.token.as_ref().ok_or_else(|| {
+            ExportError::HubError("HuggingFace token required to create repos".to_string())
+        })?;
+
+        // Parse repo_id (org/name or just name)
+        let (organization, name) = if let Some(idx) = repo_id.find('/') {
+            (Some(&repo_id[..idx]), &repo_id[idx + 1..])
+        } else {
+            (None, repo_id)
+        };
+
+        let create_request = CreateRepoRequest {
+            name: name.to_string(),
+            organization: organization.map(|s| s.to_string()),
+            private: false,
+            repo_type: "model".to_string(),
+        };
+
+        let url = format!("{}/repos/create", self.api_url);
+
+        // Use simple HTTP client approach (blocking for simplicity)
+        // In production, you'd use reqwest or similar
+        let body = serde_json::to_string(&create_request)?;
+
+        let output = std::process::Command::new("curl")
+            .args([
+                "-X",
+                "POST",
+                "-H",
+                &format!("Authorization: Bearer {}", token),
+                "-H",
+                "Content-Type: application/json",
+                "-d",
+                &body,
+                &url,
+            ])
+            .output()
+            .map_err(|e| ExportError::HubError(format!("curl failed: {}", e)))?;
+
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            // Repo might already exist, which is fine
+            if !stderr.contains("already exists") {
+                return Err(ExportError::HubError(format!(
+                    "Failed to create repo: {}",
+                    stderr
+                )));
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Create model card content
+    fn create_model_card(&self, engine: &SonaEngine, config: &ExportConfig) -> String {
+        let stats = engine.stats();
+        format!(
+            r#"---
+license: mit
+library_name: peft
+base_model: {}
+tags:
+  - sona
+  - lora
+  - adaptive-learning
+  - ruvector
+---
+
+# {} SONA Adapter
+
+This adapter was generated using [SONA (Self-Optimizing Neural Architecture)](https://github.com/ruvnet/ruvector/tree/main/crates/sona) - a runtime-adaptive learning system.
+
+## Model Details
+
+- **Base Model**: {}
+- **PEFT Type**: LoRA (Two-Tier)
+- **MicroLoRA Rank**: {} (instant adaptation)
+- **BaseLoRA Rank**: {} (background learning)
+- **Patterns Learned**: {}
+- **Trajectories Processed**: {}
+
+## SONA Features
+
+### Two-Tier LoRA Architecture
+- **MicroLoRA**: Rank 1-2 for instant adaptation (<0.5ms latency)
+- **BaseLoRA**: Rank 4-16 for background learning
+
+### EWC++ (Elastic Weight Consolidation)
+Prevents catastrophic forgetting when learning new patterns.
+
+### ReasoningBank
+K-means++ clustering for efficient pattern storage and retrieval.
+
+## Performance Benchmarks
+
+| Metric | Value |
+|--------|-------|
+| Throughput | 2211 ops/sec |
+| Latency | <0.5ms per layer |
+| Quality Improvement | +55% max |
+
+## Usage with PEFT
+
+```python
+from peft import PeftModel, PeftConfig
+from transformers import AutoModelForCausalLM
+
+# Load adapter
+config = PeftConfig.from_pretrained("your-username/{}")
+model = AutoModelForCausalLM.from_pretrained(config.base_model_name_or_path)
+model = PeftModel.from_pretrained(model, "your-username/{}")
+
+# Use for inference
+outputs = model.generate(input_ids)
+```
+
+## Training with Included Datasets
+
+### Patterns Dataset
+```python
+from datasets import load_dataset
+
+patterns = load_dataset("json", data_files="patterns.jsonl")
+```
+
+### Preference Pairs (for DPO/RLHF)
+```python
+preferences = load_dataset("json", data_files="preferences.jsonl")
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+Generated with [ruvector-sona](https://crates.io/crates/ruvector-sona) v{}
+"#,
+            config.target_architecture,
+            config.model_name,
+            config.target_architecture,
+            engine.config().micro_lora_rank,
+            engine.config().base_lora_rank,
+            stats.patterns_stored,
+            stats.trajectories_buffered,
+            config.model_name,
+            config.model_name,
+            env!("CARGO_PKG_VERSION"),
+        )
+    }
+
+    /// Create PEFT-compatible adapter config
+    fn create_adapter_config(
+        &self,
+        engine: &SonaEngine,
+        config: &ExportConfig,
+    ) -> AdapterConfigJson {
+        let sona_config = engine.config();
+        AdapterConfigJson {
+            peft_type: "LORA".to_string(),
+            auto_mapping: None,
+            base_model_name_or_path: config.target_architecture.clone(),
+            revision: None,
+            task_type: "CAUSAL_LM".to_string(),
+            inference_mode: true,
+            r: sona_config.base_lora_rank,
+            lora_alpha: sona_config.base_lora_rank as f32,
+            lora_dropout: 0.0,
+            fan_in_fan_out: false,
+            bias: "none".to_string(),
+            target_modules: vec![
+                "q_proj".to_string(),
+                "k_proj".to_string(),
+                "v_proj".to_string(),
+                "o_proj".to_string(),
+            ],
+            modules_to_save: None,
+            layers_to_transform: None,
+            layers_pattern: None,
+        }
+    }
+}
+
+/// Request to create a new repo
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+struct CreateRepoRequest {
+    name: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    organization: Option<String>,
+    private: bool,
+    #[serde(rename = "type")]
+    repo_type: String,
+}
+
+/// PEFT adapter config for JSON export
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct AdapterConfigJson {
+    pub peft_type: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub auto_mapping: Option<serde_json::Value>,
+    pub base_model_name_or_path: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub revision: Option<String>,
+    pub task_type: String,
+    pub inference_mode: bool,
+    pub r: usize,
+    pub lora_alpha: f32,
+    pub lora_dropout: f32,
+    pub fan_in_fan_out: bool,
+    pub bias: String,
+    pub target_modules: Vec<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub modules_to_save: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub layers_to_transform: Option<Vec<usize>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub layers_pattern: Option<String>,
+}
+
+/// Simple UUID v4 generator
+fn uuid_v4() -> String {
+    use rand::Rng;
+    let mut rng = rand::thread_rng();
+    let bytes: [u8; 16] = rng.gen();
+    format!(
+        "{:02x}{:02x}{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}{:02x}{:02x}{:02x}{:02x}",
+        bytes[0], bytes[1], bytes[2], bytes[3],
+        bytes[4], bytes[5],
+        (bytes[6] & 0x0f) | 0x40, bytes[7],
+        (bytes[8] & 0x3f) | 0x80, bytes[9],
+        bytes[10], bytes[11], bytes[12], bytes[13], bytes[14], bytes[15]
+    )
+}
+
+/// Copy directory recursively
+fn copy_dir_recursive(src: &Path, dst: &Path) -> Result<(), ExportError> {
+    if !dst.exists() {
+        std::fs::create_dir_all(dst).map_err(ExportError::Io)?;
+    }
+
+    for entry in std::fs::read_dir(src).map_err(ExportError::Io)? {
+        let entry = entry.map_err(ExportError::Io)?;
+        let path = entry.path();
+        let file_name = path.file_name().unwrap();
+        let dest_path = dst.join(file_name);
+
+        if path.is_dir() {
+            copy_dir_recursive(&path, &dest_path)?;
+        } else {
+            std::fs::copy(&path, &dest_path).map_err(ExportError::Io)?;
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_hub_from_env() {
+        // Just ensure it doesn't panic
+        let _hub = HuggingFaceHub::from_env();
+    }
+
+    #[test]
+    fn test_uuid_v4() {
+        let uuid = uuid_v4();
+        assert_eq!(uuid.len(), 36);
+        assert!(uuid.contains('-'));
+    }
+
+    #[test]
+    fn test_adapter_config_json() {
+        let config = AdapterConfigJson {
+            peft_type: "LORA".to_string(),
+            auto_mapping: None,
+            base_model_name_or_path: "microsoft/phi-4".to_string(),
+            revision: None,
+            task_type: "CAUSAL_LM".to_string(),
+            inference_mode: true,
+            r: 8,
+            lora_alpha: 8.0,
+            lora_dropout: 0.0,
+            fan_in_fan_out: false,
+            bias: "none".to_string(),
+            target_modules: vec!["q_proj".to_string()],
+            modules_to_save: None,
+            layers_to_transform: None,
+            layers_pattern: None,
+        };
+
+        let json = serde_json::to_string_pretty(&config).unwrap();
+        assert!(json.contains("LORA"));
+        assert!(json.contains("phi-4"));
+    }
+}

vendor/ruvector/crates/sona/src/export/mod.rs

@@ -0,0 +1,392 @@
+//! SONA Export Module - HuggingFace Integration
+//!
+//! Export learned patterns, LoRA weights, and trajectories to HuggingFace-compatible formats
+//! for pretraining, fine-tuning, and knowledge distillation.
+//!
+//! # Supported Export Formats
+//!
+//! - **SafeTensors**: LoRA adapter weights in PEFT-compatible format
+//! - **JSONL Dataset**: ReasoningBank patterns as HuggingFace datasets
+//! - **Preference Pairs**: Quality trajectories for DPO/RLHF training
+//! - **Distillation Targets**: Routing decisions for knowledge distillation
+//!
+//! # Example
+//!
+//! ```rust,ignore
+//! use ruvector_sona::export::{HuggingFaceExporter, ExportConfig};
+//!
+//! let exporter = HuggingFaceExporter::new(&engine);
+//!
+//! // Export LoRA weights
+//! exporter.export_lora_safetensors("./lora_weights")?;
+//!
+//! // Export patterns as dataset
+//! exporter.export_patterns_jsonl("./patterns.jsonl")?;
+//!
+//! // Export preference pairs for RLHF
+//! exporter.export_preference_pairs("./preferences.jsonl")?;
+//! ```
+
+pub mod dataset;
+pub mod huggingface_hub;
+pub mod pretrain;
+pub mod safetensors;
+
+pub use dataset::DatasetExporter;
+pub use huggingface_hub::HuggingFaceHub;
+pub use pretrain::{PretrainConfig, PretrainPipeline};
+pub use safetensors::SafeTensorsExporter;
+
+use crate::engine::SonaEngine;
+use serde::{Deserialize, Serialize};
+use std::path::Path;
+
+/// Export configuration
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct ExportConfig {
+    /// Model name for HuggingFace
+    pub model_name: String,
+    /// Organization/user on HuggingFace
+    pub organization: Option<String>,
+    /// Target model architecture (e.g., "phi-4", "llama-7b", "mistral-7b")
+    pub target_architecture: String,
+    /// Include patterns in export
+    pub include_patterns: bool,
+    /// Include LoRA weights
+    pub include_lora: bool,
+    /// Include preference pairs
+    pub include_preferences: bool,
+    /// Minimum quality threshold for exports
+    pub min_quality_threshold: f32,
+    /// Compress outputs
+    pub compress: bool,
+}
+
+impl Default for ExportConfig {
+    fn default() -> Self {
+        Self {
+            model_name: "sona-adapter".to_string(),
+            organization: None,
+            target_architecture: "phi-4".to_string(),
+            include_patterns: true,
+            include_lora: true,
+            include_preferences: true,
+            min_quality_threshold: 0.5,
+            compress: false,
+        }
+    }
+}
+
+/// Main HuggingFace exporter
+pub struct HuggingFaceExporter<'a> {
+    /// Reference to SONA engine
+    engine: &'a SonaEngine,
+    /// Export configuration
+    config: ExportConfig,
+}
+
+impl<'a> HuggingFaceExporter<'a> {
+    /// Create new exporter
+    pub fn new(engine: &'a SonaEngine) -> Self {
+        Self {
+            engine,
+            config: ExportConfig::default(),
+        }
+    }
+
+    /// Create with custom config
+    pub fn with_config(engine: &'a SonaEngine, config: ExportConfig) -> Self {
+        Self { engine, config }
+    }
+
+    /// Export LoRA weights in SafeTensors format (PEFT-compatible)
+    pub fn export_lora_safetensors<P: AsRef<Path>>(
+        &self,
+        output_dir: P,
+    ) -> Result<ExportResult, ExportError> {
+        let exporter = SafeTensorsExporter::new(&self.config);
+        exporter.export_engine(self.engine, output_dir)
+    }
+
+    /// Export patterns as JSONL dataset
+    pub fn export_patterns_jsonl<P: AsRef<Path>>(
+        &self,
+        output_path: P,
+    ) -> Result<ExportResult, ExportError> {
+        let exporter = DatasetExporter::new(&self.config);
+        exporter.export_patterns(self.engine, output_path)
+    }
+
+    /// Export preference pairs for DPO/RLHF training
+    pub fn export_preference_pairs<P: AsRef<Path>>(
+        &self,
+        output_path: P,
+    ) -> Result<ExportResult, ExportError> {
+        let exporter = DatasetExporter::new(&self.config);
+        exporter.export_preferences(self.engine, output_path)
+    }
+
+    /// Export all to HuggingFace Hub
+    pub fn push_to_hub(
+        &self,
+        repo_id: &str,
+        token: Option<&str>,
+    ) -> Result<ExportResult, ExportError> {
+        let hub = HuggingFaceHub::new(token);
+        hub.push_all(self.engine, &self.config, repo_id)
+    }
+
+    /// Export complete package (LoRA + patterns + config)
+    pub fn export_all<P: AsRef<Path>>(
+        &self,
+        output_dir: P,
+    ) -> Result<Vec<ExportResult>, ExportError> {
+        let output_dir = output_dir.as_ref();
+        std::fs::create_dir_all(output_dir).map_err(ExportError::Io)?;
+
+        let mut results = Vec::new();
+
+        if self.config.include_lora {
+            results.push(self.export_lora_safetensors(output_dir.join("lora"))?);
+        }
+
+        if self.config.include_patterns {
+            results.push(self.export_patterns_jsonl(output_dir.join("patterns.jsonl"))?);
+        }
+
+        if self.config.include_preferences {
+            results.push(self.export_preference_pairs(output_dir.join("preferences.jsonl"))?);
+        }
+
+        // Export config
+        let config_path = output_dir.join("adapter_config.json");
+        let config_json = serde_json::to_string_pretty(&self.create_adapter_config())?;
+        std::fs::write(&config_path, config_json).map_err(ExportError::Io)?;
+
+        // Export README
+        let readme_path = output_dir.join("README.md");
+        let readme = self.generate_readme();
+        std::fs::write(&readme_path, readme).map_err(ExportError::Io)?;
+
+        Ok(results)
+    }
+
+    /// Create PEFT-compatible adapter config
+    fn create_adapter_config(&self) -> AdapterConfig {
+        let sona_config = self.engine.config();
+        AdapterConfig {
+            peft_type: "LORA".to_string(),
+            auto_mapping: None,
+            base_model_name_or_path: self.config.target_architecture.clone(),
+            revision: None,
+            task_type: "CAUSAL_LM".to_string(),
+            inference_mode: true,
+            r: sona_config.micro_lora_rank,
+            lora_alpha: sona_config.micro_lora_rank as f32,
+            lora_dropout: 0.0,
+            fan_in_fan_out: false,
+            bias: "none".to_string(),
+            target_modules: vec![
+                "q_proj".to_string(),
+                "k_proj".to_string(),
+                "v_proj".to_string(),
+                "o_proj".to_string(),
+            ],
+            modules_to_save: None,
+            layers_to_transform: None,
+            layers_pattern: None,
+        }
+    }
+
+    /// Generate README for HuggingFace model card
+    fn generate_readme(&self) -> String {
+        let stats = self.engine.stats();
+        format!(
+            r#"---
+license: mit
+library_name: peft
+base_model: {}
+tags:
+  - sona
+  - lora
+  - adaptive-learning
+  - ruvector
+---
+
+# {} SONA Adapter
+
+This adapter was generated using [SONA (Self-Optimizing Neural Architecture)](https://github.com/ruvnet/ruvector/tree/main/crates/sona).
+
+## Model Details
+
+- **Base Model**: {}
+- **PEFT Type**: LoRA
+- **Rank**: {}
+- **Patterns Learned**: {}
+- **Trajectories Processed**: {}
+
+## Training Details
+
+SONA uses two-tier LoRA adaptation:
+- **MicroLoRA**: Rank 1-2 for instant adaptation (<0.5ms)
+- **BaseLoRA**: Rank 4-16 for background learning
+
+### Performance Benchmarks
+
+| Metric | Value |
+|--------|-------|
+| Throughput | 2211 ops/sec |
+| Latency | <0.5ms per layer |
+| Quality Improvement | +55% max |
+
+## Usage
+
+```python
+from peft import PeftModel, PeftConfig
+from transformers import AutoModelForCausalLM
+
+# Load adapter
+config = PeftConfig.from_pretrained("your-username/{}")
+model = AutoModelForCausalLM.from_pretrained(config.base_model_name_or_path)
+model = PeftModel.from_pretrained(model, "your-username/{}")
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+Generated with [ruvector-sona](https://crates.io/crates/ruvector-sona) v0.1.0
+"#,
+            self.config.target_architecture,
+            self.config.model_name,
+            self.config.target_architecture,
+            self.engine.config().micro_lora_rank,
+            stats.patterns_stored,
+            stats.trajectories_buffered,
+            self.config.model_name,
+            self.config.model_name,
+        )
+    }
+}
+
+/// PEFT-compatible adapter configuration
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AdapterConfig {
+    pub peft_type: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub auto_mapping: Option<serde_json::Value>,
+    pub base_model_name_or_path: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub revision: Option<String>,
+    pub task_type: String,
+    pub inference_mode: bool,
+    pub r: usize,
+    pub lora_alpha: f32,
+    pub lora_dropout: f32,
+    pub fan_in_fan_out: bool,
+    pub bias: String,
+    pub target_modules: Vec<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub modules_to_save: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub layers_to_transform: Option<Vec<usize>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub layers_pattern: Option<String>,
+}
+
+/// Export result
+#[derive(Clone, Debug)]
+pub struct ExportResult {
+    /// Export type
+    pub export_type: ExportType,
+    /// Number of items exported
+    pub items_exported: usize,
+    /// Output path
+    pub output_path: String,
+    /// File size in bytes
+    pub size_bytes: u64,
+}
+
+/// Export type enum
+#[derive(Clone, Debug)]
+pub enum ExportType {
+    SafeTensors,
+    PatternsDataset,
+    PreferencePairs,
+    DistillationTargets,
+    AdapterConfig,
+}
+
+/// Export errors
+#[derive(Debug)]
+pub enum ExportError {
+    Io(std::io::Error),
+    Serialization(serde_json::Error),
+    InvalidData(String),
+    HubError(String),
+}
+
+impl From<std::io::Error> for ExportError {
+    fn from(e: std::io::Error) -> Self {
+        ExportError::Io(e)
+    }
+}
+
+impl From<serde_json::Error> for ExportError {
+    fn from(e: serde_json::Error) -> Self {
+        ExportError::Serialization(e)
+    }
+}
+
+impl std::fmt::Display for ExportError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ExportError::Io(e) => write!(f, "IO error: {}", e),
+            ExportError::Serialization(e) => write!(f, "Serialization error: {}", e),
+            ExportError::InvalidData(msg) => write!(f, "Invalid data: {}", msg),
+            ExportError::HubError(msg) => write!(f, "HuggingFace Hub error: {}", msg),
+        }
+    }
+}
+
+impl std::error::Error for ExportError {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_export_config_default() {
+        let config = ExportConfig::default();
+        assert_eq!(config.model_name, "sona-adapter");
+        assert!(config.include_patterns);
+        assert!(config.include_lora);
+    }
+
+    #[test]
+    fn test_adapter_config_serialization() {
+        let config = AdapterConfig {
+            peft_type: "LORA".to_string(),
+            auto_mapping: None,
+            base_model_name_or_path: "microsoft/phi-4".to_string(),
+            revision: None,
+            task_type: "CAUSAL_LM".to_string(),
+            inference_mode: true,
+            r: 2,
+            lora_alpha: 2.0,
+            lora_dropout: 0.0,
+            fan_in_fan_out: false,
+            bias: "none".to_string(),
+            target_modules: vec!["q_proj".to_string()],
+            modules_to_save: None,
+            layers_to_transform: None,
+            layers_pattern: None,
+        };
+
+        let json = serde_json::to_string_pretty(&config).unwrap();
+        assert!(json.contains("LORA"));
+        assert!(json.contains("phi-4"));
+    }
+}

vendor/ruvector/crates/sona/src/export/pretrain.rs

@@ -0,0 +1,666 @@
+//! Pretraining Pipeline - SONA-optimized model pretraining configuration
+//!
+//! Generates optimal pretraining configurations based on SONA benchmark results:
+//! - 2211 ops/sec throughput
+//! - <0.5ms latency per layer
+//! - +55% quality improvement
+//! - 134 tests passing
+
+use std::path::Path;
+
+#[cfg(feature = "serde-support")]
+use serde::{Deserialize, Serialize};
+
+use super::{ExportConfig, ExportError, ExportResult, HuggingFaceExporter};
+use crate::engine::SonaEngine;
+
+/// Pretraining configuration based on SONA benchmarks
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct PretrainConfig {
+    /// Base model to fine-tune
+    pub base_model: String,
+
+    /// LoRA configuration
+    pub lora: LoraPretrainConfig,
+
+    /// Training hyperparameters
+    pub training: TrainingConfig,
+
+    /// Dataset configuration
+    pub dataset: DatasetConfig,
+
+    /// Hardware configuration
+    pub hardware: HardwareConfig,
+
+    /// SONA-specific optimizations
+    pub sona: SonaOptimizations,
+}
+
+/// LoRA pretraining configuration
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct LoraPretrainConfig {
+    /// LoRA rank (benchmark optimal: 2)
+    pub rank: usize,
+    /// LoRA alpha (typically equals rank)
+    pub alpha: f32,
+    /// Dropout rate (benchmark: 0.0)
+    pub dropout: f32,
+    /// Target modules
+    pub target_modules: Vec<String>,
+    /// Use RSLoRA scaling
+    pub use_rslora: bool,
+}
+
+/// Training hyperparameters
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct TrainingConfig {
+    /// Learning rate (benchmark optimal: 0.002)
+    pub learning_rate: f64,
+    /// Batch size (benchmark optimal: 32)
+    pub batch_size: usize,
+    /// Gradient accumulation steps
+    pub gradient_accumulation_steps: usize,
+    /// Number of epochs
+    pub num_epochs: usize,
+    /// Warmup ratio
+    pub warmup_ratio: f32,
+    /// Weight decay
+    pub weight_decay: f32,
+    /// Max gradient norm
+    pub max_grad_norm: f32,
+    /// LR scheduler type
+    pub lr_scheduler_type: String,
+    /// Save steps
+    pub save_steps: usize,
+    /// Evaluation steps
+    pub eval_steps: usize,
+    /// Logging steps
+    pub logging_steps: usize,
+}
+
+/// Dataset configuration
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct DatasetConfig {
+    /// Path to patterns dataset
+    pub patterns_path: Option<String>,
+    /// Path to preferences dataset
+    pub preferences_path: Option<String>,
+    /// Path to distillation targets
+    pub distillation_path: Option<String>,
+    /// Maximum sequence length
+    pub max_seq_length: usize,
+    /// Train/validation split ratio
+    pub validation_split: f32,
+}
+
+/// Hardware configuration
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct HardwareConfig {
+    /// Use mixed precision (fp16/bf16)
+    pub mixed_precision: String,
+    /// Number of GPUs
+    pub num_gpus: usize,
+    /// Enable gradient checkpointing
+    pub gradient_checkpointing: bool,
+    /// Enable DeepSpeed
+    pub deepspeed: Option<String>,
+    /// Enable FSDP
+    pub fsdp: bool,
+}
+
+/// SONA-specific optimizations
+#[cfg_attr(feature = "serde-support", derive(Serialize, Deserialize))]
+#[derive(Clone, Debug)]
+pub struct SonaOptimizations {
+    /// Enable two-tier LoRA (MicroLoRA + BaseLoRA)
+    pub two_tier_lora: bool,
+    /// MicroLoRA rank (1-2)
+    pub micro_lora_rank: usize,
+    /// Enable EWC++ for catastrophic forgetting prevention
+    pub ewc_enabled: bool,
+    /// EWC lambda (benchmark optimal: 1000)
+    pub ewc_lambda: f32,
+    /// Number of pattern clusters (benchmark optimal: 100)
+    pub pattern_clusters: usize,
+    /// Enable SIMD optimizations
+    pub enable_simd: bool,
+}
+
+impl Default for PretrainConfig {
+    fn default() -> Self {
+        Self {
+            base_model: "microsoft/phi-4".to_string(),
+            lora: LoraPretrainConfig::default(),
+            training: TrainingConfig::default(),
+            dataset: DatasetConfig::default(),
+            hardware: HardwareConfig::default(),
+            sona: SonaOptimizations::default(),
+        }
+    }
+}
+
+impl Default for LoraPretrainConfig {
+    fn default() -> Self {
+        Self {
+            // Benchmark optimal: rank 2
+            rank: 2,
+            alpha: 2.0,
+            dropout: 0.0,
+            target_modules: vec![
+                "q_proj".to_string(),
+                "k_proj".to_string(),
+                "v_proj".to_string(),
+                "o_proj".to_string(),
+            ],
+            use_rslora: false,
+        }
+    }
+}
+
+impl Default for TrainingConfig {
+    fn default() -> Self {
+        Self {
+            // Benchmark optimal: 0.002
+            learning_rate: 0.002,
+            // Benchmark optimal: 32
+            batch_size: 32,
+            gradient_accumulation_steps: 4,
+            num_epochs: 3,
+            warmup_ratio: 0.1,
+            weight_decay: 0.01,
+            max_grad_norm: 1.0,
+            lr_scheduler_type: "cosine".to_string(),
+            save_steps: 500,
+            eval_steps: 100,
+            logging_steps: 10,
+        }
+    }
+}
+
+impl Default for DatasetConfig {
+    fn default() -> Self {
+        Self {
+            patterns_path: None,
+            preferences_path: None,
+            distillation_path: None,
+            max_seq_length: 2048,
+            validation_split: 0.1,
+        }
+    }
+}
+
+impl Default for HardwareConfig {
+    fn default() -> Self {
+        Self {
+            mixed_precision: "bf16".to_string(),
+            num_gpus: 1,
+            gradient_checkpointing: true,
+            deepspeed: None,
+            fsdp: false,
+        }
+    }
+}
+
+impl Default for SonaOptimizations {
+    fn default() -> Self {
+        Self {
+            two_tier_lora: true,
+            micro_lora_rank: 1,
+            ewc_enabled: true,
+            // Benchmark optimal: 1000
+            ewc_lambda: 1000.0,
+            // Benchmark optimal: 100
+            pattern_clusters: 100,
+            enable_simd: true,
+        }
+    }
+}
+
+/// Pretraining pipeline orchestrator
+pub struct PretrainPipeline<'a> {
+    /// Reference to SONA engine
+    engine: &'a SonaEngine,
+    /// Pipeline configuration
+    config: PretrainConfig,
+}
+
+impl<'a> PretrainPipeline<'a> {
+    /// Create new pretraining pipeline
+    pub fn new(engine: &'a SonaEngine) -> Self {
+        Self {
+            engine,
+            config: PretrainConfig::default(),
+        }
+    }
+
+    /// Create with custom configuration
+    pub fn with_config(engine: &'a SonaEngine, config: PretrainConfig) -> Self {
+        Self { engine, config }
+    }
+
+    /// Generate optimal config from SONA engine stats
+    pub fn from_engine_stats(engine: &'a SonaEngine) -> Self {
+        let sona_config = engine.config();
+
+        let config = PretrainConfig {
+            lora: LoraPretrainConfig {
+                rank: sona_config.base_lora_rank,
+                alpha: sona_config.base_lora_rank as f32,
+                ..Default::default()
+            },
+            sona: SonaOptimizations {
+                micro_lora_rank: sona_config.micro_lora_rank,
+                ewc_lambda: sona_config.ewc_lambda,
+                pattern_clusters: sona_config.pattern_clusters,
+                ..Default::default()
+            },
+            ..Default::default()
+        };
+
+        Self { engine, config }
+    }
+
+    /// Export complete pretraining package
+    pub fn export_package<P: AsRef<Path>>(
+        &self,
+        output_dir: P,
+    ) -> Result<PretrainPackage, ExportError> {
+        let output_dir = output_dir.as_ref();
+        std::fs::create_dir_all(output_dir).map_err(ExportError::Io)?;
+
+        // Export using HuggingFaceExporter
+        let export_config = ExportConfig {
+            model_name: self.config.base_model.replace('/', "-"),
+            target_architecture: self.config.base_model.clone(),
+            include_patterns: true,
+            include_lora: true,
+            include_preferences: true,
+            min_quality_threshold: 0.5,
+            ..Default::default()
+        };
+
+        let exporter = HuggingFaceExporter::with_config(self.engine, export_config);
+        let export_results = exporter.export_all(output_dir)?;
+
+        // Generate training script
+        let script_path = output_dir.join("train.py");
+        let script = self.generate_training_script();
+        std::fs::write(&script_path, script).map_err(ExportError::Io)?;
+
+        // Generate config files
+        let config_path = output_dir.join("pretrain_config.json");
+        let config_json = serde_json::to_string_pretty(&self.config)?;
+        std::fs::write(&config_path, config_json).map_err(ExportError::Io)?;
+
+        // Generate requirements
+        let requirements_path = output_dir.join("requirements.txt");
+        let requirements = self.generate_requirements();
+        std::fs::write(&requirements_path, requirements).map_err(ExportError::Io)?;
+
+        // Generate accelerate config
+        let accelerate_path = output_dir.join("accelerate_config.yaml");
+        let accelerate_config = self.generate_accelerate_config();
+        std::fs::write(&accelerate_path, accelerate_config).map_err(ExportError::Io)?;
+
+        Ok(PretrainPackage {
+            output_dir: output_dir.to_string_lossy().to_string(),
+            export_results,
+            script_path: script_path.to_string_lossy().to_string(),
+            config_path: config_path.to_string_lossy().to_string(),
+        })
+    }
+
+    /// Generate Python training script
+    fn generate_training_script(&self) -> String {
+        format!(
+            r#"#!/usr/bin/env python3
+"""
+SONA-Optimized Pretraining Script
+
+Based on SONA benchmark results:
+- Throughput: 2211 ops/sec
+- Latency: <0.5ms per layer
+- Quality improvement: +55%
+
+Configuration optimized for:
+- LoRA Rank: {}
+- Learning Rate: {}
+- Batch Size: {}
+- EWC Lambda: {}
+- Pattern Clusters: {}
+"""
+
+import os
+import json
+import torch
+from datasets import load_dataset
+from transformers import (
+    AutoModelForCausalLM,
+    AutoTokenizer,
+    TrainingArguments,
+    Trainer,
+    DataCollatorForLanguageModeling,
+)
+from peft import (
+    LoraConfig,
+    get_peft_model,
+    prepare_model_for_kbit_training,
+    TaskType,
+)
+
+# Load SONA config
+with open("pretrain_config.json", "r") as f:
+    CONFIG = json.load(f)
+
+def main():
+    # Load base model
+    print(f"Loading base model: {{CONFIG['base_model']}}")
+    model = AutoModelForCausalLM.from_pretrained(
+        CONFIG["base_model"],
+        torch_dtype=torch.bfloat16 if CONFIG["hardware"]["mixed_precision"] == "bf16" else torch.float16,
+        device_map="auto",
+        trust_remote_code=True,
+    )
+
+    tokenizer = AutoTokenizer.from_pretrained(CONFIG["base_model"])
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    # Configure LoRA with SONA-optimal settings
+    lora_config = LoraConfig(
+        r=CONFIG["lora"]["rank"],
+        lora_alpha=CONFIG["lora"]["alpha"],
+        lora_dropout=CONFIG["lora"]["dropout"],
+        target_modules=CONFIG["lora"]["target_modules"],
+        task_type=TaskType.CAUSAL_LM,
+        bias="none",
+    )
+
+    # Prepare model
+    if CONFIG["hardware"]["gradient_checkpointing"]:
+        model.gradient_checkpointing_enable()
+
+    model = get_peft_model(model, lora_config)
+    model.print_trainable_parameters()
+
+    # Load SONA datasets
+    datasets = {{}}
+
+    if CONFIG["dataset"]["patterns_path"] and os.path.exists(CONFIG["dataset"]["patterns_path"]):
+        print("Loading patterns dataset...")
+        datasets["patterns"] = load_dataset("json", data_files=CONFIG["dataset"]["patterns_path"])
+
+    if CONFIG["dataset"]["preferences_path"] and os.path.exists(CONFIG["dataset"]["preferences_path"]):
+        print("Loading preferences dataset...")
+        datasets["preferences"] = load_dataset("json", data_files=CONFIG["dataset"]["preferences_path"])
+
+    # Use patterns dataset for pretraining if available
+    if "patterns" in datasets:
+        train_dataset = datasets["patterns"]["train"]
+    else:
+        # Fall back to sample data
+        print("Warning: No patterns dataset found, using sample data")
+        train_dataset = None
+
+    # Training arguments with SONA-optimal settings
+    training_args = TrainingArguments(
+        output_dir="./sona-output",
+        num_train_epochs=CONFIG["training"]["num_epochs"],
+        per_device_train_batch_size=CONFIG["training"]["batch_size"],
+        gradient_accumulation_steps=CONFIG["training"]["gradient_accumulation_steps"],
+        learning_rate=CONFIG["training"]["learning_rate"],
+        warmup_ratio=CONFIG["training"]["warmup_ratio"],
+        weight_decay=CONFIG["training"]["weight_decay"],
+        max_grad_norm=CONFIG["training"]["max_grad_norm"],
+        lr_scheduler_type=CONFIG["training"]["lr_scheduler_type"],
+        save_steps=CONFIG["training"]["save_steps"],
+        eval_steps=CONFIG["training"]["eval_steps"],
+        logging_steps=CONFIG["training"]["logging_steps"],
+        bf16=CONFIG["hardware"]["mixed_precision"] == "bf16",
+        fp16=CONFIG["hardware"]["mixed_precision"] == "fp16",
+        gradient_checkpointing=CONFIG["hardware"]["gradient_checkpointing"],
+        report_to="tensorboard",
+        save_total_limit=3,
+        push_to_hub=False,
+    )
+
+    # Data collator
+    data_collator = DataCollatorForLanguageModeling(
+        tokenizer=tokenizer,
+        mlm=False,
+    )
+
+    if train_dataset:
+        # Initialize trainer
+        trainer = Trainer(
+            model=model,
+            args=training_args,
+            train_dataset=train_dataset,
+            data_collator=data_collator,
+        )
+
+        # Train
+        print("Starting SONA-optimized training...")
+        trainer.train()
+
+        # Save
+        print("Saving model...")
+        trainer.save_model("./sona-output/final")
+        tokenizer.save_pretrained("./sona-output/final")
+    else:
+        print("No training data available. Please provide patterns.jsonl or preferences.jsonl")
+
+    print("Done!")
+
+if __name__ == "__main__":
+    main()
+"#,
+            self.config.lora.rank,
+            self.config.training.learning_rate,
+            self.config.training.batch_size,
+            self.config.sona.ewc_lambda,
+            self.config.sona.pattern_clusters,
+        )
+    }
+
+    /// Generate requirements.txt
+    fn generate_requirements(&self) -> String {
+        r#"# SONA Pretraining Requirements
+torch>=2.0.0
+transformers>=4.35.0
+datasets>=2.14.0
+peft>=0.6.0
+accelerate>=0.24.0
+bitsandbytes>=0.41.0
+safetensors>=0.4.0
+tensorboard>=2.14.0
+scipy>=1.11.0
+scikit-learn>=1.3.0
+tqdm>=4.66.0
+"#
+        .to_string()
+    }
+
+    /// Generate accelerate config
+    fn generate_accelerate_config(&self) -> String {
+        format!(
+            r#"compute_environment: LOCAL_MACHINE
+debug: false
+distributed_type: {}
+downcast_bf16: 'no'
+gpu_ids: all
+machine_rank: 0
+main_training_function: main
+mixed_precision: {}
+num_machines: 1
+num_processes: {}
+rdzv_backend: static
+same_network: true
+tpu_env: []
+tpu_use_cluster: false
+tpu_use_sudo: false
+use_cpu: false
+"#,
+            if self.config.hardware.num_gpus > 1 {
+                "MULTI_GPU"
+            } else {
+                "NO"
+            },
+            self.config.hardware.mixed_precision,
+            self.config.hardware.num_gpus,
+        )
+    }
+
+    /// Generate DPO training script for preference learning
+    pub fn generate_dpo_script(&self) -> String {
+        r#"#!/usr/bin/env python3
+"""
+SONA DPO (Direct Preference Optimization) Training Script
+
+Uses preference pairs exported from SONA ReasoningBank for RLHF-style training
+without requiring a reward model.
+"""
+
+import json
+import torch
+from datasets import load_dataset
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from trl import DPOTrainer, DPOConfig
+from peft import LoraConfig, get_peft_model
+
+# Load config
+with open("pretrain_config.json", "r") as f:
+    CONFIG = json.load(f)
+
+def main():
+    # Load model
+    model = AutoModelForCausalLM.from_pretrained(
+        CONFIG["base_model"],
+        torch_dtype=torch.bfloat16,
+        device_map="auto",
+    )
+
+    tokenizer = AutoTokenizer.from_pretrained(CONFIG["base_model"])
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    # Configure LoRA
+    lora_config = LoraConfig(
+        r=CONFIG["lora"]["rank"],
+        lora_alpha=CONFIG["lora"]["alpha"],
+        lora_dropout=CONFIG["lora"]["dropout"],
+        target_modules=CONFIG["lora"]["target_modules"],
+        bias="none",
+    )
+
+    model = get_peft_model(model, lora_config)
+
+    # Load preference dataset
+    if CONFIG["dataset"]["preferences_path"]:
+        dataset = load_dataset("json", data_files=CONFIG["dataset"]["preferences_path"])
+    else:
+        raise ValueError("Preferences dataset required for DPO training")
+
+    # DPO config
+    dpo_config = DPOConfig(
+        output_dir="./sona-dpo-output",
+        num_train_epochs=CONFIG["training"]["num_epochs"],
+        per_device_train_batch_size=CONFIG["training"]["batch_size"] // 2,
+        gradient_accumulation_steps=CONFIG["training"]["gradient_accumulation_steps"],
+        learning_rate=CONFIG["training"]["learning_rate"] / 10,  # Lower LR for DPO
+        warmup_ratio=CONFIG["training"]["warmup_ratio"],
+        bf16=True,
+        logging_steps=CONFIG["training"]["logging_steps"],
+        save_steps=CONFIG["training"]["save_steps"],
+        beta=0.1,  # DPO temperature
+    )
+
+    # Initialize DPO trainer
+    trainer = DPOTrainer(
+        model=model,
+        args=dpo_config,
+        train_dataset=dataset["train"],
+        tokenizer=tokenizer,
+    )
+
+    # Train
+    print("Starting SONA DPO training...")
+    trainer.train()
+
+    # Save
+    trainer.save_model("./sona-dpo-output/final")
+    print("Done!")
+
+if __name__ == "__main__":
+    main()
+"#
+        .to_string()
+    }
+}
+
+/// Pretraining package result
+#[derive(Clone, Debug)]
+pub struct PretrainPackage {
+    /// Output directory
+    pub output_dir: String,
+    /// Export results
+    pub export_results: Vec<ExportResult>,
+    /// Path to training script
+    pub script_path: String,
+    /// Path to config file
+    pub config_path: String,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_pretrain_config_default() {
+        let config = PretrainConfig::default();
+
+        // Verify benchmark-optimal values
+        assert_eq!(config.lora.rank, 2);
+        assert_eq!(config.training.learning_rate, 0.002);
+        assert_eq!(config.training.batch_size, 32);
+        assert_eq!(config.sona.ewc_lambda, 1000.0);
+        assert_eq!(config.sona.pattern_clusters, 100);
+    }
+
+    #[test]
+    fn test_config_serialization() {
+        let config = PretrainConfig::default();
+        let json = serde_json::to_string_pretty(&config).unwrap();
+
+        assert!(json.contains("\"rank\": 2"));
+        assert!(json.contains("\"learning_rate\": 0.002"));
+        assert!(json.contains("\"batch_size\": 32"));
+    }
+
+    #[test]
+    fn test_lora_config_default() {
+        let config = LoraPretrainConfig::default();
+
+        assert_eq!(config.rank, 2);
+        assert_eq!(config.alpha, 2.0);
+        assert_eq!(config.dropout, 0.0);
+        assert!(config.target_modules.contains(&"q_proj".to_string()));
+    }
+
+    #[test]
+    fn test_sona_optimizations_default() {
+        let config = SonaOptimizations::default();
+
+        assert!(config.two_tier_lora);
+        assert_eq!(config.micro_lora_rank, 1);
+        assert!(config.ewc_enabled);
+        assert_eq!(config.ewc_lambda, 1000.0);
+        assert_eq!(config.pattern_clusters, 100);
+        assert!(config.enable_simd);
+    }
+}

vendor/ruvector/crates/sona/src/export/safetensors.rs

@@ -0,0 +1,337 @@
+//! SafeTensors Export - PEFT-compatible LoRA weight serialization
+//!
+//! Exports SONA's learned LoRA weights in SafeTensors format for use with
+//! HuggingFace's PEFT library and transformers ecosystem.
+
+use super::{ExportConfig, ExportError, ExportResult, ExportType};
+use crate::engine::SonaEngine;
+use std::collections::HashMap;
+use std::path::Path;
+
+#[cfg(feature = "serde-support")]
+use serde::{Deserialize, Serialize};
+
+/// SafeTensors exporter for LoRA weights
+pub struct SafeTensorsExporter<'a> {
+    _config: &'a ExportConfig,
+}
+
+impl<'a> SafeTensorsExporter<'a> {
+    /// Create new SafeTensors exporter
+    pub fn new(config: &'a ExportConfig) -> Self {
+        Self { _config: config }
+    }
+
+    /// Export engine's LoRA weights to SafeTensors format
+    pub fn export_engine<P: AsRef<Path>>(
+        &self,
+        engine: &SonaEngine,
+        output_dir: P,
+    ) -> Result<ExportResult, ExportError> {
+        let output_dir = output_dir.as_ref();
+        std::fs::create_dir_all(output_dir).map_err(ExportError::Io)?;
+
+        // Get LoRA state from engine
+        let lora_state = engine.export_lora_state();
+
+        // Build tensor data map
+        let mut tensors: HashMap<String, TensorData> = HashMap::new();
+
+        // Export MicroLoRA weights (rank 1-2)
+        for (i, layer) in lora_state.micro_lora_layers.iter().enumerate() {
+            let a_key = format!(
+                "base_model.model.layers.{}.self_attn.micro_lora_A.weight",
+                i
+            );
+            let b_key = format!(
+                "base_model.model.layers.{}.self_attn.micro_lora_B.weight",
+                i
+            );
+
+            tensors.insert(
+                a_key,
+                TensorData {
+                    data: layer.lora_a.clone(),
+                    shape: vec![layer.rank, layer.input_dim],
+                    dtype: "F32".to_string(),
+                },
+            );
+
+            tensors.insert(
+                b_key,
+                TensorData {
+                    data: layer.lora_b.clone(),
+                    shape: vec![layer.output_dim, layer.rank],
+                    dtype: "F32".to_string(),
+                },
+            );
+        }
+
+        // Export BaseLoRA weights (rank 4-16)
+        for (i, layer) in lora_state.base_lora_layers.iter().enumerate() {
+            // Q projection
+            let q_a_key = format!(
+                "base_model.model.layers.{}.self_attn.q_proj.lora_A.weight",
+                i
+            );
+            let q_b_key = format!(
+                "base_model.model.layers.{}.self_attn.q_proj.lora_B.weight",
+                i
+            );
+
+            tensors.insert(
+                q_a_key,
+                TensorData {
+                    data: layer.lora_a.clone(),
+                    shape: vec![layer.rank, layer.input_dim],
+                    dtype: "F32".to_string(),
+                },
+            );
+
+            tensors.insert(
+                q_b_key,
+                TensorData {
+                    data: layer.lora_b.clone(),
+                    shape: vec![layer.output_dim, layer.rank],
+                    dtype: "F32".to_string(),
+                },
+            );
+
+            // K projection
+            let k_a_key = format!(
+                "base_model.model.layers.{}.self_attn.k_proj.lora_A.weight",
+                i
+            );
+            let k_b_key = format!(
+                "base_model.model.layers.{}.self_attn.k_proj.lora_B.weight",
+                i
+            );
+
+            tensors.insert(
+                k_a_key,
+                TensorData {
+                    data: layer.lora_a.clone(),
+                    shape: vec![layer.rank, layer.input_dim],
+                    dtype: "F32".to_string(),
+                },
+            );
+
+            tensors.insert(
+                k_b_key,
+                TensorData {
+                    data: layer.lora_b.clone(),
+                    shape: vec![layer.output_dim, layer.rank],
+                    dtype: "F32".to_string(),
+                },
+            );
+
+            // V projection
+            let v_a_key = format!(
+                "base_model.model.layers.{}.self_attn.v_proj.lora_A.weight",
+                i
+            );
+            let v_b_key = format!(
+                "base_model.model.layers.{}.self_attn.v_proj.lora_B.weight",
+                i
+            );
+
+            tensors.insert(
+                v_a_key,
+                TensorData {
+                    data: layer.lora_a.clone(),
+                    shape: vec![layer.rank, layer.input_dim],
+                    dtype: "F32".to_string(),
+                },
+            );
+
+            tensors.insert(
+                v_b_key,
+                TensorData {
+                    data: layer.lora_b.clone(),
+                    shape: vec![layer.output_dim, layer.rank],
+                    dtype: "F32".to_string(),
+                },
+            );
+
+            // O projection
+            let o_a_key = format!(
+                "base_model.model.layers.{}.self_attn.o_proj.lora_A.weight",
+                i
+            );
+            let o_b_key = format!(
+                "base_model.model.layers.{}.self_attn.o_proj.lora_B.weight",
+                i
+            );
+
+            tensors.insert(
+                o_a_key,
+                TensorData {
+                    data: layer.lora_a.clone(),
+                    shape: vec![layer.rank, layer.input_dim],
+                    dtype: "F32".to_string(),
+                },
+            );
+
+            tensors.insert(
+                o_b_key,
+                TensorData {
+                    data: layer.lora_b.clone(),
+                    shape: vec![layer.output_dim, layer.rank],
+                    dtype: "F32".to_string(),
+                },
+            );
+        }
+
+        // Serialize to SafeTensors format
+        let safetensors_path = output_dir.join("adapter_model.safetensors");
+        let bytes = self.serialize_safetensors(&tensors)?;
+        std::fs::write(&safetensors_path, &bytes).map_err(ExportError::Io)?;
+
+        let size_bytes = bytes.len() as u64;
+
+        Ok(ExportResult {
+            export_type: ExportType::SafeTensors,
+            items_exported: tensors.len(),
+            output_path: safetensors_path.to_string_lossy().to_string(),
+            size_bytes,
+        })
+    }
+
+    /// Serialize tensors to SafeTensors binary format
+    fn serialize_safetensors(
+        &self,
+        tensors: &HashMap<String, TensorData>,
+    ) -> Result<Vec<u8>, ExportError> {
+        // SafeTensors format:
+        // 8 bytes: header size (little endian u64)
+        // N bytes: JSON header with tensor metadata
+        // ... tensor data (aligned to 8 bytes)
+
+        let mut header_data: HashMap<String, TensorMetadata> = HashMap::new();
+        let mut tensor_bytes: Vec<u8> = Vec::new();
+
+        // Sort keys for deterministic output
+        let mut keys: Vec<_> = tensors.keys().collect();
+        keys.sort();
+
+        for key in keys {
+            let tensor = &tensors[key];
+
+            // Align to 8 bytes
+            let padding = (8 - (tensor_bytes.len() % 8)) % 8;
+            tensor_bytes.extend(vec![0u8; padding]);
+
+            let start_offset = tensor_bytes.len();
+
+            // Write tensor data
+            for &val in &tensor.data {
+                tensor_bytes.extend_from_slice(&val.to_le_bytes());
+            }
+
+            let end_offset = tensor_bytes.len();
+
+            header_data.insert(
+                key.clone(),
+                TensorMetadata {
+                    dtype: tensor.dtype.clone(),
+                    shape: tensor.shape.clone(),
+                    data_offsets: [start_offset, end_offset],
+                },
+            );
+        }
+
+        // Serialize header to JSON
+        let header_json =
+            serde_json::to_string(&header_data).map_err(ExportError::Serialization)?;
+        let header_bytes = header_json.as_bytes();
+
+        // Build final buffer
+        let mut result = Vec::new();
+
+        // Header size (8 bytes, little endian)
+        result.extend_from_slice(&(header_bytes.len() as u64).to_le_bytes());
+
+        // Header JSON
+        result.extend_from_slice(header_bytes);
+
+        // Tensor data
+        result.extend(tensor_bytes);
+
+        Ok(result)
+    }
+}
+
+/// Tensor data for export
+#[derive(Clone, Debug)]
+pub struct TensorData {
+    /// Flattened tensor values
+    pub data: Vec<f32>,
+    /// Tensor shape
+    pub shape: Vec<usize>,
+    /// Data type (F32, F16, BF16, etc.)
+    pub dtype: String,
+}
+
+/// Tensor metadata for SafeTensors header
+#[cfg(feature = "serde-support")]
+#[derive(Clone, Debug, Serialize, Deserialize)]
+struct TensorMetadata {
+    dtype: String,
+    shape: Vec<usize>,
+    data_offsets: [usize; 2],
+}
+
+/// LoRA layer state for export
+#[derive(Clone, Debug)]
+pub struct LoRALayerState {
+    /// LoRA A matrix (rank x input_dim)
+    pub lora_a: Vec<f32>,
+    /// LoRA B matrix (output_dim x rank)
+    pub lora_b: Vec<f32>,
+    /// LoRA rank
+    pub rank: usize,
+    /// Input dimension
+    pub input_dim: usize,
+    /// Output dimension
+    pub output_dim: usize,
+}
+
+/// Complete LoRA state for export
+#[derive(Clone, Debug, Default)]
+pub struct LoRAState {
+    /// MicroLoRA layers (instant adaptation)
+    pub micro_lora_layers: Vec<LoRALayerState>,
+    /// BaseLoRA layers (background learning)
+    pub base_lora_layers: Vec<LoRALayerState>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_tensor_data_creation() {
+        let tensor = TensorData {
+            data: vec![1.0, 2.0, 3.0, 4.0],
+            shape: vec![2, 2],
+            dtype: "F32".to_string(),
+        };
+
+        assert_eq!(tensor.data.len(), 4);
+        assert_eq!(tensor.shape, vec![2, 2]);
+    }
+
+    #[test]
+    fn test_lora_layer_state() {
+        let state = LoRALayerState {
+            lora_a: vec![0.1, 0.2, 0.3, 0.4],
+            lora_b: vec![0.5, 0.6, 0.7, 0.8],
+            rank: 2,
+            input_dim: 2,
+            output_dim: 2,
+        };
+
+        assert_eq!(state.rank, 2);
+        assert_eq!(state.lora_a.len(), 4);
+    }
+}

vendor/ruvector/crates/sona/src/lib.rs

@@ -0,0 +1,96 @@
+//! SONA (Self-Optimizing Neural Architecture)
+//!
+//! A lightweight adaptive learning system with ReasoningBank integration.
+//!
+//! ## Features
+//!
+//! - **Micro-LoRA**: Ultra-low rank (1-2) LoRA for instant learning
+//! - **Base-LoRA**: Standard LoRA for background learning
+//! - **EWC++**: Elastic Weight Consolidation to prevent catastrophic forgetting
+//! - **ReasoningBank**: Pattern extraction and similarity search
+//! - **Three Learning Loops**: Instant, Background, and Coordination loops
+//! - **WASM Support**: Run in browsers and edge devices (enable `wasm` feature)
+//!
+//! ## Example
+//!
+//! ```rust,ignore
+//! use sona::{SonaEngine, SonaConfig};
+//!
+//! // Create engine
+//! let engine = SonaEngine::new(SonaConfig {
+//!     hidden_dim: 256,
+//!     embedding_dim: 256,
+//!     ..Default::default()
+//! });
+//!
+//! // Begin trajectory
+//! let mut builder = engine.begin_trajectory(vec![0.1; 256]);
+//! builder.add_step(vec![0.5; 256], vec![], 0.8);
+//!
+//! // End trajectory
+//! engine.end_trajectory(builder, 0.85);
+//!
+//! // Apply learned transformations
+//! let input = vec![1.0; 256];
+//! let mut output = vec![0.0; 256];
+//! engine.apply_micro_lora(&input, &mut output);
+//! ```
+//!
+//! ## WASM Usage
+//!
+//! Enable the `wasm` feature and build with:
+//! ```bash
+//! wasm-pack build --target web --features wasm
+//! ```
+
+#![allow(missing_docs)]
+
+pub mod engine;
+pub mod ewc;
+pub mod loops;
+pub mod lora;
+pub mod reasoning_bank;
+pub mod time_compat;
+pub mod trajectory;
+pub mod types;
+
+#[cfg(feature = "serde-support")]
+pub mod export;
+
+#[cfg(feature = "serde-support")]
+pub mod training;
+
+#[cfg(feature = "wasm")]
+pub mod wasm;
+
+#[cfg(feature = "napi")]
+pub mod napi_simple;
+
+// Re-export main types
+pub use engine::SonaEngine;
+pub use ewc::{EwcConfig, EwcPlusPlus, TaskFisher};
+pub use loops::{BackgroundLoop, InstantLoop, LoopCoordinator};
+pub use lora::{BaseLoRA, LoRAEngine, LoRALayer, MicroLoRA};
+pub use reasoning_bank::{PatternConfig, ReasoningBank};
+pub use trajectory::{TrajectoryBuffer, TrajectoryBuilder, TrajectoryIdGen};
+pub use types::{
+    LearnedPattern, LearningSignal, PatternType, QueryTrajectory, SignalMetadata, SonaConfig,
+    TrajectoryStep,
+};
+
+#[cfg(feature = "serde-support")]
+pub use export::{
+    DatasetExporter, ExportConfig, ExportError, ExportResult, ExportType, HuggingFaceExporter,
+    HuggingFaceHub, PretrainConfig, PretrainPipeline, SafeTensorsExporter,
+};
+
+#[cfg(feature = "serde-support")]
+pub use training::{
+    AgentExport, AgentFactory, AgentHandle, AgentStats, AgentType, AggregationResult, BatchConfig,
+    CoordinatorStats, DataSizeHint, EphemeralAgent, EpochStats, FederatedCoordinator,
+    FederatedTopology, ManagedAgent, PipelineStage, TaskDomain, TemplatePreset, TrainingMethod,
+    TrainingMetrics, TrainingPipeline, TrainingResult, TrainingTemplate, VerticalConfig,
+};
+
+#[cfg(feature = "wasm")]
+pub use wasm::WasmSonaEngine;

vendor/ruvector/crates/sona/src/loops/background.rs

@@ -0,0 +1,234 @@
+//! Loop B - Background Learning
+//!
+//! Hourly pattern extraction and base LoRA updates.
+
+use crate::ewc::EwcPlusPlus;
+use crate::lora::BaseLoRA;
+use crate::reasoning_bank::ReasoningBank;
+use crate::time_compat::Instant;
+use crate::types::{LearnedPattern, QueryTrajectory, SonaConfig};
+use parking_lot::RwLock;
+use std::sync::Arc;
+use std::time::Duration;
+
+/// Background loop configuration
+#[derive(Clone, Debug)]
+pub struct BackgroundLoopConfig {
+    /// Minimum trajectories to process
+    pub min_trajectories: usize,
+    /// Base LoRA learning rate
+    pub base_lora_lr: f32,
+    /// EWC lambda
+    pub ewc_lambda: f32,
+    /// Pattern extraction interval
+    pub extraction_interval: Duration,
+}
+
+impl Default for BackgroundLoopConfig {
+    fn default() -> Self {
+        Self {
+            min_trajectories: 100,
+            base_lora_lr: 0.0001,
+            ewc_lambda: 1000.0,
+            extraction_interval: Duration::from_secs(3600),
+        }
+    }
+}
+
+impl From<&SonaConfig> for BackgroundLoopConfig {
+    fn from(config: &SonaConfig) -> Self {
+        Self {
+            min_trajectories: 100,
+            base_lora_lr: config.base_lora_lr,
+            ewc_lambda: config.ewc_lambda,
+            extraction_interval: Duration::from_millis(config.background_interval_ms),
+        }
+    }
+}
+
+/// Background cycle result
+#[derive(Debug)]
+pub struct BackgroundResult {
+    pub trajectories_processed: usize,
+    pub patterns_extracted: usize,
+    pub ewc_updated: bool,
+    pub elapsed: Duration,
+    pub status: String,
+}
+
+impl BackgroundResult {
+    fn skipped(reason: &str) -> Self {
+        Self {
+            trajectories_processed: 0,
+            patterns_extracted: 0,
+            ewc_updated: false,
+            elapsed: Duration::ZERO,
+            status: format!("skipped: {}", reason),
+        }
+    }
+}
+
+/// Background learning loop (Loop B)
+pub struct BackgroundLoop {
+    /// Configuration
+    config: BackgroundLoopConfig,
+    /// ReasoningBank for pattern storage
+    reasoning_bank: Arc<RwLock<ReasoningBank>>,
+    /// EWC++ for forgetting prevention
+    ewc: Arc<RwLock<EwcPlusPlus>>,
+    /// Base LoRA
+    base_lora: Arc<RwLock<BaseLoRA>>,
+    /// Last extraction time
+    last_extraction: RwLock<Instant>,
+}
+
+impl BackgroundLoop {
+    /// Create new background loop
+    pub fn new(
+        config: BackgroundLoopConfig,
+        reasoning_bank: Arc<RwLock<ReasoningBank>>,
+        ewc: Arc<RwLock<EwcPlusPlus>>,
+        base_lora: Arc<RwLock<BaseLoRA>>,
+    ) -> Self {
+        Self {
+            config,
+            reasoning_bank,
+            ewc,
+            base_lora,
+            last_extraction: RwLock::new(Instant::now()),
+        }
+    }
+
+    /// Check if it's time for background cycle
+    pub fn should_run(&self) -> bool {
+        self.last_extraction.read().elapsed() >= self.config.extraction_interval
+    }
+
+    /// Run background learning cycle
+    pub fn run_cycle(&self, trajectories: Vec<QueryTrajectory>) -> BackgroundResult {
+        if trajectories.len() < self.config.min_trajectories {
+            return BackgroundResult::skipped("insufficient trajectories");
+        }
+
+        let start = Instant::now();
+
+        // 1. Add trajectories to reasoning bank
+        {
+            let mut bank = self.reasoning_bank.write();
+            for trajectory in &trajectories {
+                bank.add_trajectory(trajectory);
+            }
+        }
+
+        // 2. Extract patterns
+        let patterns = {
+            let mut bank = self.reasoning_bank.write();
+            bank.extract_patterns()
+        };
+
+        // 3. Compute gradients from patterns
+        let gradients = self.compute_pattern_gradients(&patterns);
+
+        // 4. Apply EWC++ constraints
+        let constrained_gradients = {
+            let ewc = self.ewc.read();
+            ewc.apply_constraints(&gradients)
+        };
+
+        // 5. Check for task boundary
+        let task_boundary = {
+            let ewc = self.ewc.read();
+            ewc.detect_task_boundary(&gradients)
+        };
+
+        if task_boundary {
+            let mut ewc = self.ewc.write();
+            ewc.start_new_task();
+        }
+
+        // 6. Update EWC++ Fisher
+        {
+            let mut ewc = self.ewc.write();
+            ewc.update_fisher(&constrained_gradients);
+        }
+
+        // 7. Update base LoRA
+        self.update_base_lora(&constrained_gradients);
+
+        // Update last extraction time
+        *self.last_extraction.write() = Instant::now();
+
+        BackgroundResult {
+            trajectories_processed: trajectories.len(),
+            patterns_extracted: patterns.len(),
+            ewc_updated: true,
+            elapsed: start.elapsed(),
+            status: "completed".to_string(),
+        }
+    }
+
+    fn compute_pattern_gradients(&self, patterns: &[LearnedPattern]) -> Vec<f32> {
+        if patterns.is_empty() {
+            return Vec::new();
+        }
+
+        let dim = patterns[0].centroid.len();
+        let mut gradient = vec![0.0f32; dim];
+        let mut total_weight = 0.0f32;
+
+        for pattern in patterns {
+            let weight = pattern.avg_quality * pattern.cluster_size as f32;
+            for (i, &v) in pattern.centroid.iter().enumerate() {
+                if i < dim {
+                    gradient[i] += v * weight;
+                }
+            }
+            total_weight += weight;
+        }
+
+        if total_weight > 0.0 {
+            for g in &mut gradient {
+                *g /= total_weight;
+            }
+        }
+
+        gradient
+    }
+
+    fn update_base_lora(&self, gradients: &[f32]) {
+        let mut lora = self.base_lora.write();
+        let num_layers = lora.num_layers();
+
+        if num_layers == 0 || gradients.is_empty() {
+            return;
+        }
+
+        let per_layer = gradients.len() / num_layers;
+
+        for (layer_idx, layer) in lora.layers.iter_mut().enumerate() {
+            let start = layer_idx * per_layer;
+            let end = (start + per_layer).min(gradients.len());
+
+            for (i, &grad) in gradients[start..end].iter().enumerate() {
+                if i < layer.up_proj.len() {
+                    layer.up_proj[i] += grad * self.config.base_lora_lr;
+                }
+            }
+        }
+    }
+
+    /// Get reasoning bank reference
+    pub fn reasoning_bank(&self) -> &Arc<RwLock<ReasoningBank>> {
+        &self.reasoning_bank
+    }
+
+    /// Get EWC reference
+    pub fn ewc(&self) -> &Arc<RwLock<EwcPlusPlus>> {
+        &self.ewc
+    }
+
+    /// Get base LoRA reference
+    pub fn base_lora(&self) -> &Arc<RwLock<BaseLoRA>> {
+        &self.base_lora
+    }
+}

vendor/ruvector/crates/sona/src/loops/coordinator.rs

@@ -0,0 +1,225 @@
+//! Loop Coordinator - Orchestrates all learning loops
+
+use crate::ewc::{EwcConfig, EwcPlusPlus};
+use crate::loops::background::{BackgroundLoop, BackgroundLoopConfig, BackgroundResult};
+use crate::loops::instant::InstantLoop;
+use crate::lora::{BaseLoRA, MicroLoRA};
+use crate::reasoning_bank::{PatternConfig, ReasoningBank};
+use crate::types::{QueryTrajectory, SonaConfig};
+use parking_lot::RwLock;
+use std::sync::Arc;
+
+/// Loop coordinator managing all learning loops
+pub struct LoopCoordinator {
+    /// Configuration
+    _config: SonaConfig,
+    /// Instant loop (Loop A)
+    instant: InstantLoop,
+    /// Background loop (Loop B)
+    background: BackgroundLoop,
+    /// Shared components
+    reasoning_bank: Arc<RwLock<ReasoningBank>>,
+    ewc: Arc<RwLock<EwcPlusPlus>>,
+    base_lora: Arc<RwLock<BaseLoRA>>,
+    /// Enabled flags
+    instant_enabled: bool,
+    background_enabled: bool,
+}
+
+impl LoopCoordinator {
+    /// Create new coordinator with default config
+    pub fn new(hidden_dim: usize) -> Self {
+        Self::with_config(SonaConfig {
+            hidden_dim,
+            embedding_dim: hidden_dim,
+            ..Default::default()
+        })
+    }
+
+    /// Create with custom config
+    pub fn with_config(config: SonaConfig) -> Self {
+        let reasoning_bank = Arc::new(RwLock::new(ReasoningBank::new(PatternConfig {
+            embedding_dim: config.embedding_dim,
+            k_clusters: config.pattern_clusters,
+            ..Default::default()
+        })));
+
+        let ewc = Arc::new(RwLock::new(EwcPlusPlus::new(EwcConfig {
+            param_count: config.hidden_dim * config.base_lora_rank * 2,
+            initial_lambda: config.ewc_lambda,
+            ..Default::default()
+        })));
+
+        let base_lora = Arc::new(RwLock::new(BaseLoRA::new(
+            config.hidden_dim,
+            config.base_lora_rank,
+            12, // Default number of layers
+        )));
+
+        let instant = InstantLoop::from_sona_config(&config);
+        let background = BackgroundLoop::new(
+            BackgroundLoopConfig::from(&config),
+            reasoning_bank.clone(),
+            ewc.clone(),
+            base_lora.clone(),
+        );
+
+        Self {
+            _config: config,
+            instant,
+            background,
+            reasoning_bank,
+            ewc,
+            base_lora,
+            instant_enabled: true,
+            background_enabled: true,
+        }
+    }
+
+    /// Process inference trajectory (Loop A)
+    pub fn on_inference(&self, trajectory: QueryTrajectory) {
+        if self.instant_enabled {
+            self.instant.on_trajectory(trajectory);
+        }
+    }
+
+    /// Generate next trajectory ID
+    pub fn next_trajectory_id(&self) -> u64 {
+        self.instant.next_id()
+    }
+
+    /// Run background cycle if needed (Loop B)
+    pub fn maybe_run_background(&self) -> Option<BackgroundResult> {
+        if !self.background_enabled {
+            return None;
+        }
+
+        if self.background.should_run() {
+            let trajectories = self.instant.drain_trajectories();
+            if !trajectories.is_empty() {
+                return Some(self.background.run_cycle(trajectories));
+            }
+        }
+
+        None
+    }
+
+    /// Force background cycle
+    pub fn force_background(&self) -> BackgroundResult {
+        let trajectories = self.instant.drain_trajectories();
+        self.background.run_cycle(trajectories)
+    }
+
+    /// Flush instant loop updates
+    pub fn flush_instant(&self) {
+        self.instant.flush();
+    }
+
+    /// Get micro-LoRA for inference
+    pub fn micro_lora(&self) -> &Arc<RwLock<MicroLoRA>> {
+        self.instant.micro_lora()
+    }
+
+    /// Get base-LoRA for inference
+    pub fn base_lora(&self) -> &Arc<RwLock<BaseLoRA>> {
+        &self.base_lora
+    }
+
+    /// Get reasoning bank
+    pub fn reasoning_bank(&self) -> &Arc<RwLock<ReasoningBank>> {
+        &self.reasoning_bank
+    }
+
+    /// Get EWC++
+    pub fn ewc(&self) -> &Arc<RwLock<EwcPlusPlus>> {
+        &self.ewc
+    }
+
+    /// Enable/disable instant loop
+    pub fn set_instant_enabled(&mut self, enabled: bool) {
+        self.instant_enabled = enabled;
+    }
+
+    /// Enable/disable background loop
+    pub fn set_background_enabled(&mut self, enabled: bool) {
+        self.background_enabled = enabled;
+    }
+
+    /// Get statistics
+    pub fn stats(&self) -> CoordinatorStats {
+        let (buffer_len, dropped, success_rate) = self.instant.buffer_stats();
+
+        CoordinatorStats {
+            trajectories_buffered: buffer_len,
+            trajectories_dropped: dropped,
+            buffer_success_rate: success_rate,
+            patterns_stored: self.reasoning_bank.read().pattern_count(),
+            ewc_tasks: self.ewc.read().task_count(),
+            instant_enabled: self.instant_enabled,
+            background_enabled: self.background_enabled,
+        }
+    }
+}
+
+/// Coordinator statistics
+#[derive(Debug, Clone)]
+#[cfg_attr(
+    feature = "serde-support",
+    derive(serde::Serialize, serde::Deserialize)
+)]
+pub struct CoordinatorStats {
+    pub trajectories_buffered: usize,
+    pub trajectories_dropped: u64,
+    pub buffer_success_rate: f64,
+    pub patterns_stored: usize,
+    pub ewc_tasks: usize,
+    pub instant_enabled: bool,
+    pub background_enabled: bool,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::types::TrajectoryStep;
+
+    fn make_trajectory(id: u64) -> QueryTrajectory {
+        let mut t = QueryTrajectory::new(id, vec![0.1; 256]);
+        t.add_step(TrajectoryStep::new(vec![0.5; 256], vec![], 0.8, 0));
+        t.finalize(0.8, 1000);
+        t
+    }
+
+    #[test]
+    fn test_coordinator_creation() {
+        let coord = LoopCoordinator::new(256);
+        let stats = coord.stats();
+        assert_eq!(stats.trajectories_buffered, 0);
+    }
+
+    #[test]
+    fn test_inference_processing() {
+        let coord = LoopCoordinator::new(256);
+
+        for i in 0..10 {
+            let t = make_trajectory(coord.next_trajectory_id());
+            coord.on_inference(t);
+        }
+
+        let stats = coord.stats();
+        assert_eq!(stats.trajectories_buffered, 10);
+    }
+
+    #[test]
+    fn test_force_background() {
+        let coord = LoopCoordinator::new(256);
+
+        for i in 0..150 {
+            let t = make_trajectory(coord.next_trajectory_id());
+            coord.on_inference(t);
+        }
+
+        let result = coord.force_background();
+        assert_eq!(result.trajectories_processed, 150);
+        assert!(result.patterns_extracted > 0);
+    }
+}

vendor/ruvector/crates/sona/src/loops/instant.rs

@@ -0,0 +1,247 @@
+//! Loop A - Instant Learning
+//!
+//! Per-request adaptation with <1ms overhead.
+
+use crate::lora::MicroLoRA;
+use crate::trajectory::{TrajectoryBuffer, TrajectoryIdGen};
+use crate::types::{LearningSignal, QueryTrajectory, SonaConfig};
+use parking_lot::RwLock;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+
+/// Configuration for instant loop
+#[derive(Clone, Debug)]
+pub struct InstantLoopConfig {
+    /// Micro-LoRA rank
+    pub micro_lora_rank: usize,
+    /// Micro-LoRA learning rate
+    pub micro_lora_lr: f32,
+    /// Buffer capacity
+    pub buffer_capacity: usize,
+    /// Flush threshold (apply updates every N signals)
+    pub flush_threshold: usize,
+}
+
+impl Default for InstantLoopConfig {
+    fn default() -> Self {
+        Self {
+            micro_lora_rank: 1,
+            micro_lora_lr: 0.001,
+            buffer_capacity: 10000,
+            flush_threshold: 100,
+        }
+    }
+}
+
+impl From<&SonaConfig> for InstantLoopConfig {
+    fn from(config: &SonaConfig) -> Self {
+        Self {
+            micro_lora_rank: config.micro_lora_rank,
+            micro_lora_lr: config.micro_lora_lr,
+            buffer_capacity: config.trajectory_capacity,
+            flush_threshold: 100,
+        }
+    }
+}
+
+/// Instant loop metrics
+#[derive(Debug, Default)]
+pub struct InstantLoopMetrics {
+    /// Total trajectories processed
+    pub trajectories_processed: AtomicU64,
+    /// Total signals accumulated
+    pub signals_accumulated: AtomicU64,
+    /// Total flushes performed
+    pub flushes_performed: AtomicU64,
+    /// Total updates applied
+    pub updates_applied: AtomicU64,
+}
+
+/// Instant learning loop (Loop A)
+pub struct InstantLoop {
+    /// Configuration
+    config: InstantLoopConfig,
+    /// Trajectory buffer
+    trajectory_buffer: Arc<TrajectoryBuffer>,
+    /// Micro-LoRA adapter
+    micro_lora: Arc<RwLock<MicroLoRA>>,
+    /// ID generator
+    id_gen: TrajectoryIdGen,
+    /// Pending signal count
+    pending_signals: AtomicU64,
+    /// Metrics
+    pub metrics: InstantLoopMetrics,
+}
+
+impl InstantLoop {
+    /// Create new instant loop
+    pub fn new(hidden_dim: usize, config: InstantLoopConfig) -> Self {
+        Self {
+            trajectory_buffer: Arc::new(TrajectoryBuffer::new(config.buffer_capacity)),
+            micro_lora: Arc::new(RwLock::new(MicroLoRA::new(
+                hidden_dim,
+                config.micro_lora_rank,
+            ))),
+            id_gen: TrajectoryIdGen::new(),
+            pending_signals: AtomicU64::new(0),
+            config,
+            metrics: InstantLoopMetrics::default(),
+        }
+    }
+
+    /// Create from SONA config
+    pub fn from_sona_config(config: &SonaConfig) -> Self {
+        Self::new(config.hidden_dim, InstantLoopConfig::from(config))
+    }
+
+    /// Generate next trajectory ID
+    pub fn next_id(&self) -> u64 {
+        self.id_gen.next()
+    }
+
+    /// Process completed trajectory
+    pub fn on_trajectory(&self, trajectory: QueryTrajectory) {
+        // Record to buffer
+        self.trajectory_buffer.record(trajectory.clone());
+        self.metrics
+            .trajectories_processed
+            .fetch_add(1, Ordering::Relaxed);
+
+        // Generate learning signal
+        let signal = LearningSignal::from_trajectory(&trajectory);
+
+        // Accumulate gradient (non-blocking)
+        if let Some(mut lora) = self.micro_lora.try_write() {
+            lora.accumulate_gradient(&signal);
+            self.metrics
+                .signals_accumulated
+                .fetch_add(1, Ordering::Relaxed);
+
+            let pending = self.pending_signals.fetch_add(1, Ordering::Relaxed) + 1;
+
+            // Auto-flush if threshold reached
+            if pending >= self.config.flush_threshold as u64 {
+                self.flush_internal(&mut lora);
+            }
+        }
+    }
+
+    /// Manually flush accumulated updates
+    pub fn flush(&self) {
+        if let Some(mut lora) = self.micro_lora.try_write() {
+            self.flush_internal(&mut lora);
+        }
+    }
+
+    fn flush_internal(&self, lora: &mut MicroLoRA) {
+        let pending = lora.pending_updates();
+        if pending > 0 {
+            lora.apply_accumulated(self.config.micro_lora_lr);
+            self.pending_signals.store(0, Ordering::Relaxed);
+            self.metrics
+                .flushes_performed
+                .fetch_add(1, Ordering::Relaxed);
+            self.metrics
+                .updates_applied
+                .fetch_add(pending as u64, Ordering::Relaxed);
+        }
+    }
+
+    /// Drain trajectories for background processing
+    pub fn drain_trajectories(&self) -> Vec<QueryTrajectory> {
+        self.trajectory_buffer.drain()
+    }
+
+    /// Drain up to N trajectories
+    pub fn drain_trajectories_n(&self, n: usize) -> Vec<QueryTrajectory> {
+        self.trajectory_buffer.drain_n(n)
+    }
+
+    /// Get micro-LoRA reference for inference
+    pub fn micro_lora(&self) -> &Arc<RwLock<MicroLoRA>> {
+        &self.micro_lora
+    }
+
+    /// Get trajectory buffer reference
+    pub fn buffer(&self) -> &Arc<TrajectoryBuffer> {
+        &self.trajectory_buffer
+    }
+
+    /// Get pending trajectory count
+    pub fn pending_count(&self) -> usize {
+        self.trajectory_buffer.len()
+    }
+
+    /// Get buffer stats
+    pub fn buffer_stats(&self) -> (usize, u64, f64) {
+        (
+            self.trajectory_buffer.len(),
+            self.trajectory_buffer.dropped_count(),
+            self.trajectory_buffer.success_rate(),
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::types::TrajectoryStep;
+
+    fn make_trajectory(id: u64) -> QueryTrajectory {
+        let mut t = QueryTrajectory::new(id, vec![0.1; 64]);
+        t.add_step(TrajectoryStep::new(vec![0.5; 64], vec![], 0.8, 0));
+        t.finalize(0.8, 1000);
+        t
+    }
+
+    #[test]
+    fn test_instant_loop_creation() {
+        let loop_a = InstantLoop::new(64, InstantLoopConfig::default());
+        assert_eq!(loop_a.pending_count(), 0);
+    }
+
+    #[test]
+    fn test_trajectory_processing() {
+        let loop_a = InstantLoop::new(64, InstantLoopConfig::default());
+
+        let t = make_trajectory(loop_a.next_id());
+        loop_a.on_trajectory(t);
+
+        assert_eq!(loop_a.pending_count(), 1);
+        assert_eq!(
+            loop_a
+                .metrics
+                .trajectories_processed
+                .load(Ordering::Relaxed),
+            1
+        );
+    }
+
+    #[test]
+    fn test_auto_flush() {
+        let config = InstantLoopConfig {
+            flush_threshold: 3,
+            ..Default::default()
+        };
+        let loop_a = InstantLoop::new(64, config);
+
+        for i in 0..5 {
+            loop_a.on_trajectory(make_trajectory(i));
+        }
+
+        assert!(loop_a.metrics.flushes_performed.load(Ordering::Relaxed) >= 1);
+    }
+
+    #[test]
+    fn test_drain() {
+        let loop_a = InstantLoop::new(64, InstantLoopConfig::default());
+
+        for i in 0..10 {
+            loop_a.on_trajectory(make_trajectory(i));
+        }
+
+        let drained = loop_a.drain_trajectories();
+        assert_eq!(drained.len(), 10);
+        assert_eq!(loop_a.pending_count(), 0);
+    }
+}

vendor/ruvector/crates/sona/src/loops/mod.rs

@@ -0,0 +1,14 @@
+//! SONA Learning Loops
+//!
+//! Three-tier temporal learning architecture:
+//! - Loop A (Instant): Per-request trajectory recording and micro-LoRA updates
+//! - Loop B (Background): Hourly pattern extraction and base LoRA updates
+//! - Loop C (Deep): Weekly dream consolidation and full EWC++ update
+
+pub mod background;
+pub mod coordinator;
+pub mod instant;
+
+pub use background::BackgroundLoop;
+pub use coordinator::LoopCoordinator;
+pub use instant::InstantLoop;

vendor/ruvector/crates/sona/src/lora.rs

@@ -0,0 +1,518 @@
+//! LoRA (Low-Rank Adaptation) implementations for SONA
+//!
+//! Two-tier LoRA system:
+//! - MicroLoRA: Rank 1-2, per-request adaptation (<100μs)
+//! - BaseLoRA: Rank 4-16, background adaptation (hourly)
+
+use crate::types::LearningSignal;
+use serde::{Deserialize, Serialize};
+
+/// Optimal batch size for processing (benchmark-validated)
+pub const OPTIMAL_BATCH_SIZE: usize = 32;
+
+/// Micro-LoRA for per-request adaptation
+///
+/// Uses rank 1-2 for ultra-low latency updates.
+/// Forward pass: output += scale * (input @ down) @ up
+///
+/// **Performance notes (from benchmarks):**
+/// - Rank-2 is ~5% faster than Rank-1 due to better SIMD vectorization
+/// - Batch size 32 optimal: 0.447ms per-vector, 2,236 ops/sec throughput
+/// - SIMD-enabled: +10% speedup over scalar
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct MicroLoRA {
+    /// Down projection (hidden_dim -> rank)
+    down_proj: Vec<f32>,
+    /// Up projection (rank -> hidden_dim)
+    up_proj: Vec<f32>,
+    /// Rank (1-2 for micro updates)
+    rank: usize,
+    /// Hidden dimension
+    hidden_dim: usize,
+    /// Accumulated gradients for down
+    #[serde(skip)]
+    grad_down: Vec<f32>,
+    /// Accumulated gradients for up
+    #[serde(skip)]
+    grad_up: Vec<f32>,
+    /// Update count for averaging
+    #[serde(skip)]
+    update_count: usize,
+    /// Scaling factor
+    scale: f32,
+}
+
+impl MicroLoRA {
+    /// Create new Micro-LoRA adapter
+    ///
+    /// # Arguments
+    /// * `hidden_dim` - Model hidden dimension
+    /// * `rank` - LoRA rank (must be 1-2)
+    ///
+    /// # Panics
+    /// Panics if rank > 2
+    pub fn new(hidden_dim: usize, rank: usize) -> Self {
+        assert!(
+            (1..=2).contains(&rank),
+            "MicroLoRA rank must be 1-2, got {}",
+            rank
+        );
+
+        // Initialize down with small random-like values (deterministic for reproducibility)
+        let down_proj: Vec<f32> = (0..hidden_dim * rank)
+            .map(|i| {
+                let x = (i as f32 * 0.618_034) % 1.0;
+                (x - 0.5) * 0.02
+            })
+            .collect();
+
+        // Initialize up to zero (standard LoRA init)
+        let up_proj = vec![0.0f32; rank * hidden_dim];
+
+        Self {
+            down_proj,
+            up_proj,
+            rank,
+            hidden_dim,
+            grad_down: vec![0.0; hidden_dim * rank],
+            grad_up: vec![0.0; rank * hidden_dim],
+            update_count: 0,
+            scale: 1.0 / (rank as f32).sqrt(),
+        }
+    }
+
+    /// Scalar forward pass (fallback)
+    pub fn forward_scalar(&self, input: &[f32], output: &mut [f32]) {
+        assert_eq!(input.len(), self.hidden_dim);
+        assert_eq!(output.len(), self.hidden_dim);
+
+        // Down projection: hidden_dim -> rank
+        let mut intermediate = vec![0.0f32; self.rank];
+        for (r, inter) in intermediate.iter_mut().enumerate() {
+            let mut sum = 0.0f32;
+            let offset = r * self.hidden_dim;
+            for (i, &inp) in input.iter().enumerate() {
+                sum += inp * self.down_proj[offset + i];
+            }
+            *inter = sum;
+        }
+
+        // Up projection: rank -> hidden_dim
+        for (i, out) in output.iter_mut().enumerate() {
+            let mut sum = 0.0f32;
+            for (r, &inter) in intermediate.iter().enumerate() {
+                sum += inter * self.up_proj[r * self.hidden_dim + i];
+            }
+            *out += sum * self.scale;
+        }
+    }
+
+    /// SIMD-optimized forward pass (AVX2)
+    #[cfg(all(target_arch = "x86_64", target_feature = "avx2"))]
+    pub fn forward_simd(&self, input: &[f32], output: &mut [f32]) {
+        use std::arch::x86_64::*;
+
+        assert_eq!(input.len(), self.hidden_dim);
+        assert_eq!(output.len(), self.hidden_dim);
+
+        unsafe {
+            // Down projection: hidden_dim -> rank
+            let mut intermediate = vec![0.0f32; self.rank];
+
+            for r in 0..self.rank {
+                let mut sum = _mm256_setzero_ps();
+                let offset = r * self.hidden_dim;
+
+                let mut i = 0;
+                while i + 8 <= self.hidden_dim {
+                    let inp = _mm256_loadu_ps(input[i..].as_ptr());
+                    let weight = _mm256_loadu_ps(self.down_proj[offset + i..].as_ptr());
+                    sum = _mm256_fmadd_ps(inp, weight, sum);
+                    i += 8;
+                }
+
+                // Horizontal sum
+                let mut result = [0.0f32; 8];
+                _mm256_storeu_ps(result.as_mut_ptr(), sum);
+                intermediate[r] = result.iter().sum();
+
+                // Handle remaining elements
+                for j in i..self.hidden_dim {
+                    intermediate[r] += input[j] * self.down_proj[offset + j];
+                }
+            }
+
+            // Up projection: rank -> hidden_dim
+            let scale_vec = _mm256_set1_ps(self.scale);
+
+            let mut i = 0;
+            while i + 8 <= self.hidden_dim {
+                let mut sum = _mm256_setzero_ps();
+
+                for r in 0..self.rank {
+                    let up_offset = r * self.hidden_dim;
+                    let weight = _mm256_loadu_ps(self.up_proj[up_offset + i..].as_ptr());
+                    let inter = _mm256_set1_ps(intermediate[r]);
+                    sum = _mm256_fmadd_ps(inter, weight, sum);
+                }
+
+                // Scale and add to output
+                sum = _mm256_mul_ps(sum, scale_vec);
+                let existing = _mm256_loadu_ps(output[i..].as_ptr());
+                let result = _mm256_add_ps(existing, sum);
+                _mm256_storeu_ps(output[i..].as_mut_ptr(), result);
+
+                i += 8;
+            }
+
+            // Handle remaining elements
+            for j in i..self.hidden_dim {
+                let mut val = 0.0;
+                for r in 0..self.rank {
+                    val += intermediate[r] * self.up_proj[r * self.hidden_dim + j];
+                }
+                output[j] += val * self.scale;
+            }
+        }
+    }
+
+    /// Forward pass with automatic SIMD detection
+    pub fn forward(&self, input: &[f32], output: &mut [f32]) {
+        #[cfg(all(target_arch = "x86_64", target_feature = "avx2"))]
+        {
+            self.forward_simd(input, output);
+            return;
+        }
+
+        #[allow(unreachable_code)]
+        self.forward_scalar(input, output);
+    }
+
+    /// Accumulate gradient from learning signal
+    pub fn accumulate_gradient(&mut self, signal: &LearningSignal) {
+        if signal.gradient_estimate.len() != self.hidden_dim {
+            return;
+        }
+
+        let quality = signal.quality_score;
+
+        // Simplified gradient: outer product scaled by quality
+        // This approximates the true gradient for rank-1 LoRA
+        for r in 0..self.rank {
+            for i in 0..self.hidden_dim {
+                let grad_idx = r * self.hidden_dim + i;
+                // Update up projection gradient (main target)
+                self.grad_up[grad_idx] += signal.gradient_estimate[i] * quality;
+            }
+        }
+
+        self.update_count += 1;
+    }
+
+    /// Apply accumulated gradients with learning rate
+    pub fn apply_accumulated(&mut self, learning_rate: f32) {
+        if self.update_count == 0 {
+            return;
+        }
+
+        let scale = learning_rate / self.update_count as f32;
+
+        // Update up projection (main adaptation target)
+        for (w, g) in self.up_proj.iter_mut().zip(self.grad_up.iter()) {
+            *w += g * scale;
+        }
+
+        // Reset accumulators
+        self.grad_up.fill(0.0);
+        self.grad_down.fill(0.0);
+        self.update_count = 0;
+    }
+
+    /// Reset adapter to initial state
+    pub fn reset(&mut self) {
+        self.up_proj.fill(0.0);
+        self.grad_up.fill(0.0);
+        self.grad_down.fill(0.0);
+        self.update_count = 0;
+    }
+
+    /// Get rank
+    pub fn rank(&self) -> usize {
+        self.rank
+    }
+
+    /// Get hidden dimension
+    pub fn hidden_dim(&self) -> usize {
+        self.hidden_dim
+    }
+
+    /// Get parameter count
+    pub fn param_count(&self) -> usize {
+        self.down_proj.len() + self.up_proj.len()
+    }
+
+    /// Get scale factor
+    pub fn scale(&self) -> f32 {
+        self.scale
+    }
+
+    /// Set scale factor
+    pub fn set_scale(&mut self, scale: f32) {
+        self.scale = scale;
+    }
+
+    /// Get pending update count
+    pub fn pending_updates(&self) -> usize {
+        self.update_count
+    }
+
+    /// Get LoRA weights for export (lora_a, lora_b)
+    pub fn get_weights(&self) -> (&Vec<f32>, &Vec<f32>) {
+        (&self.down_proj, &self.up_proj)
+    }
+}
+
+/// Base LoRA for background adaptation
+///
+/// Higher rank (4-16) for more expressive adaptation.
+/// Applied hourly during background learning cycles.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct BaseLoRA {
+    /// LoRA layers
+    pub layers: Vec<LoRALayer>,
+    /// Rank
+    pub rank: usize,
+    /// Hidden dimension
+    pub hidden_dim: usize,
+    /// Alpha scaling factor
+    pub alpha: f32,
+}
+
+/// Single LoRA layer
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct LoRALayer {
+    /// Down projection weights
+    pub down_proj: Vec<f32>,
+    /// Up projection weights
+    pub up_proj: Vec<f32>,
+    /// Layer index
+    pub layer_idx: usize,
+}
+
+impl BaseLoRA {
+    /// Create new Base LoRA
+    pub fn new(hidden_dim: usize, rank: usize, num_layers: usize) -> Self {
+        let layers = (0..num_layers)
+            .map(|idx| LoRALayer {
+                down_proj: vec![0.0; hidden_dim * rank],
+                up_proj: vec![0.0; rank * hidden_dim],
+                layer_idx: idx,
+            })
+            .collect();
+
+        Self {
+            layers,
+            rank,
+            hidden_dim,
+            alpha: rank as f32,
+        }
+    }
+
+    /// Forward pass for single layer
+    pub fn forward_layer(&self, layer_idx: usize, input: &[f32], output: &mut [f32]) {
+        if layer_idx >= self.layers.len() {
+            return;
+        }
+
+        let layer = &self.layers[layer_idx];
+        let scale = self.alpha / self.rank as f32;
+
+        // Down projection
+        let mut intermediate = vec![0.0f32; self.rank];
+        for (r, inter) in intermediate.iter_mut().enumerate() {
+            let offset = r * self.hidden_dim;
+            *inter = input
+                .iter()
+                .zip(&layer.down_proj[offset..offset + self.hidden_dim])
+                .map(|(a, b)| a * b)
+                .sum();
+        }
+
+        // Up projection
+        for (i, out) in output.iter_mut().enumerate() {
+            let mut sum = 0.0f32;
+            for (r, &inter) in intermediate.iter().enumerate() {
+                sum += inter * layer.up_proj[r * self.hidden_dim + i];
+            }
+            *out += sum * scale;
+        }
+    }
+
+    /// Merge LoRA weights into model weights (for inference optimization)
+    pub fn merge_into(&self, model_weights: &mut [f32], layer_idx: usize) {
+        if layer_idx >= self.layers.len() {
+            return;
+        }
+
+        let layer = &self.layers[layer_idx];
+        let scale = self.alpha / self.rank as f32;
+
+        // W' = W + scale * (down @ up)
+        // Assumes model_weights is [hidden_dim x hidden_dim]
+        for i in 0..self.hidden_dim {
+            for j in 0..self.hidden_dim {
+                let mut delta = 0.0f32;
+                for r in 0..self.rank {
+                    delta +=
+                        layer.down_proj[i * self.rank + r] * layer.up_proj[r * self.hidden_dim + j];
+                }
+                model_weights[i * self.hidden_dim + j] += delta * scale;
+            }
+        }
+    }
+
+    /// Get number of layers
+    pub fn num_layers(&self) -> usize {
+        self.layers.len()
+    }
+
+    /// Get total parameter count
+    pub fn param_count(&self) -> usize {
+        self.layers.len() * (self.hidden_dim * self.rank + self.rank * self.hidden_dim)
+    }
+
+    /// Get weights for a specific layer for export (lora_a, lora_b)
+    pub fn get_layer_weights(&self, layer_idx: usize) -> Option<(&Vec<f32>, &Vec<f32>)> {
+        self.layers
+            .get(layer_idx)
+            .map(|layer| (&layer.down_proj, &layer.up_proj))
+    }
+}
+
+/// Combined LoRA engine managing both tiers
+#[derive(Clone, Debug)]
+pub struct LoRAEngine {
+    /// Micro-LoRA for instant adaptation
+    pub micro: MicroLoRA,
+    /// Base LoRA for background adaptation
+    pub base: BaseLoRA,
+    /// Whether micro-LoRA is enabled
+    pub micro_enabled: bool,
+    /// Whether base LoRA is enabled
+    pub base_enabled: bool,
+}
+
+impl LoRAEngine {
+    /// Create new LoRA engine
+    pub fn new(hidden_dim: usize, micro_rank: usize, base_rank: usize, num_layers: usize) -> Self {
+        Self {
+            micro: MicroLoRA::new(hidden_dim, micro_rank.clamp(1, 2)),
+            base: BaseLoRA::new(hidden_dim, base_rank, num_layers),
+            micro_enabled: true,
+            base_enabled: true,
+        }
+    }
+
+    /// Apply both LoRA tiers
+    pub fn forward(&self, layer_idx: usize, input: &[f32], output: &mut [f32]) {
+        if self.micro_enabled {
+            self.micro.forward(input, output);
+        }
+        if self.base_enabled && layer_idx < self.base.num_layers() {
+            self.base.forward_layer(layer_idx, input, output);
+        }
+    }
+
+    /// Accumulate micro-LoRA gradient
+    pub fn accumulate_micro(&mut self, signal: &LearningSignal) {
+        if self.micro_enabled {
+            self.micro.accumulate_gradient(signal);
+        }
+    }
+
+    /// Apply micro-LoRA updates
+    pub fn apply_micro(&mut self, learning_rate: f32) {
+        if self.micro_enabled {
+            self.micro.apply_accumulated(learning_rate);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_micro_lora_creation() {
+        let lora = MicroLoRA::new(256, 1);
+        assert_eq!(lora.rank(), 1);
+        assert_eq!(lora.hidden_dim(), 256);
+        assert_eq!(lora.param_count(), 256 + 256);
+    }
+
+    #[test]
+    fn test_micro_lora_forward() {
+        let lora = MicroLoRA::new(64, 1);
+        let input = vec![1.0f32; 64];
+        let mut output = vec![0.0f32; 64];
+
+        lora.forward(&input, &mut output);
+
+        // Output should be modified (even if small due to init)
+        // With zero-init up_proj, output should still be zero
+        let sum: f32 = output.iter().sum();
+        assert!(
+            sum.abs() < 1e-6,
+            "Expected ~0 with zero up_proj, got {}",
+            sum
+        );
+    }
+
+    #[test]
+    fn test_micro_lora_learning() {
+        let mut lora = MicroLoRA::new(64, 1);
+
+        let signal = LearningSignal::with_gradient(vec![0.1; 64], vec![0.5; 64], 0.8);
+
+        lora.accumulate_gradient(&signal);
+        assert_eq!(lora.pending_updates(), 1);
+
+        lora.apply_accumulated(0.01);
+        assert_eq!(lora.pending_updates(), 0);
+
+        // Now forward should produce non-zero output
+        let input = vec![1.0f32; 64];
+        let mut output = vec![0.0f32; 64];
+        lora.forward(&input, &mut output);
+
+        let sum: f32 = output.iter().map(|x| x.abs()).sum();
+        assert!(sum > 0.0, "Expected non-zero output after learning");
+    }
+
+    #[test]
+    fn test_base_lora() {
+        let lora = BaseLoRA::new(64, 4, 12);
+        assert_eq!(lora.num_layers(), 12);
+        assert_eq!(lora.rank, 4);
+    }
+
+    #[test]
+    fn test_lora_engine() {
+        let mut engine = LoRAEngine::new(64, 1, 4, 12);
+
+        let signal = LearningSignal::with_gradient(vec![0.1; 64], vec![0.5; 64], 0.9);
+
+        engine.accumulate_micro(&signal);
+        engine.apply_micro(0.01);
+
+        let input = vec![1.0f32; 64];
+        let mut output = vec![0.0f32; 64];
+        engine.forward(0, &input, &mut output);
+    }
+
+    #[test]
+    #[should_panic(expected = "MicroLoRA rank must be 1-2")]
+    fn test_invalid_rank() {
+        MicroLoRA::new(64, 5);
+    }
+}

vendor/ruvector/crates/sona/src/mod.rs

@@ -0,0 +1,23 @@
+//! SONA (Self-Optimizing Neural Architecture)
+//!
+//! Adaptive learning system with ReasoningBank integration.
+
+pub mod types;
+pub mod lora;
+pub mod trajectory;
+pub mod ewc;
+pub mod reasoning_bank;
+pub mod loops;
+pub mod engine;
+
+// Re-export main types
+pub use types::{
+    LearningSignal, QueryTrajectory, TrajectoryStep,
+    LearnedPattern, PatternType, SignalMetadata, SonaConfig,
+};
+pub use lora::{MicroLoRA, BaseLoRA, LoRAEngine, LoRALayer};
+pub use trajectory::{TrajectoryBuffer, TrajectoryBuilder, TrajectoryIdGen};
+pub use ewc::{EwcConfig, EwcPlusPlus, TaskFisher};
+pub use reasoning_bank::{ReasoningBank, PatternConfig};
+pub use loops::{InstantLoop, BackgroundLoop, LoopCoordinator};
+pub use engine::SonaEngine;

vendor/ruvector/crates/sona/src/napi.rs

@@ -0,0 +1,298 @@
+//! NAPI-RS bindings for Node.js
+//! Enable with feature flag: `napi`
+
+#![cfg(feature = "napi")]
+
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+use crate::{
+    SonaEngine as RustSonaEngine,
+    SonaConfig,
+    TrajectoryBuilder as RustTrajectoryBuilder,
+    LearnedPattern,
+    PatternType,
+};
+
+/// Node.js SONA Engine wrapper
+#[napi]
+pub struct SonaEngine {
+    inner: RustSonaEngine,
+}
+
+#[napi]
+impl SonaEngine {
+    /// Create a new SONA engine with default configuration
+    /// @param hidden_dim - Hidden dimension size (e.g., 256, 512)
+    #[napi(constructor)]
+    pub fn new(hidden_dim: u32) -> Self {
+        Self {
+            inner: RustSonaEngine::new(hidden_dim as usize),
+        }
+    }
+
+    /// Create with custom configuration
+    /// @param config - Custom SONA configuration object
+    #[napi(factory)]
+    pub fn with_config(config: JsSonaConfig) -> Self {
+        let rust_config = SonaConfig {
+            hidden_dim: config.hidden_dim as usize,
+            embedding_dim: config.embedding_dim.unwrap_or(config.hidden_dim) as usize,
+            micro_lora_rank: config.micro_lora_rank.unwrap_or(1) as usize,
+            base_lora_rank: config.base_lora_rank.unwrap_or(8) as usize,
+            micro_lora_lr: config.micro_lora_lr.unwrap_or(0.001) as f32,
+            base_lora_lr: config.base_lora_lr.unwrap_or(0.0001) as f32,
+            ewc_lambda: config.ewc_lambda.unwrap_or(1000.0) as f32,
+            pattern_clusters: config.pattern_clusters.unwrap_or(50) as usize,
+            trajectory_capacity: config.trajectory_capacity.unwrap_or(10000) as usize,
+            background_interval_ms: config.background_interval_ms.unwrap_or(3600000) as u64,
+            quality_threshold: config.quality_threshold.unwrap_or(0.5) as f32,
+            enable_simd: config.enable_simd.unwrap_or(true),
+        };
+        Self {
+            inner: RustSonaEngine::with_config(rust_config),
+        }
+    }
+
+    /// Start a new trajectory recording
+    /// @param query_embedding - Query embedding vector (Float64Array)
+    /// @returns TrajectoryBuilder for adding steps
+    #[napi]
+    pub fn begin_trajectory(&self, query_embedding: Vec<f64>) -> TrajectoryBuilder {
+        let embedding: Vec<f32> = query_embedding.iter().map(|&x| x as f32).collect();
+        let builder = self.inner.begin_trajectory(embedding);
+        TrajectoryBuilder { inner: builder }
+    }
+
+    /// Complete a trajectory and submit for learning
+    /// @param builder - TrajectoryBuilder instance (consumed)
+    /// @param quality - Final quality score [0.0, 1.0]
+    #[napi]
+    pub fn end_trajectory(&self, mut builder: TrajectoryBuilder, quality: f64) {
+        let trajectory = builder.inner.build(quality as f32);
+        self.inner.submit_trajectory(trajectory);
+    }
+
+    /// Apply micro-LoRA transformation to input
+    /// @param input - Input vector (Float64Array)
+    /// @returns Transformed output vector
+    #[napi]
+    pub fn apply_micro_lora(&self, input: Vec<f64>) -> Vec<f64> {
+        let input_f32: Vec<f32> = input.iter().map(|&x| x as f32).collect();
+        let mut output = vec![0.0f32; input_f32.len()];
+        self.inner.apply_micro_lora(&input_f32, &mut output);
+        output.iter().map(|&x| x as f64).collect()
+    }
+
+    /// Apply base-LoRA transformation to layer output
+    /// @param layer_idx - Layer index
+    /// @param input - Input vector (Float64Array)
+    /// @returns Transformed output vector
+    #[napi]
+    pub fn apply_base_lora(&self, layer_idx: u32, input: Vec<f64>) -> Vec<f64> {
+        let input_f32: Vec<f32> = input.iter().map(|&x| x as f32).collect();
+        let mut output = vec![0.0f32; input_f32.len()];
+        self.inner.apply_base_lora(layer_idx as usize, &input_f32, &mut output);
+        output.iter().map(|&x| x as f64).collect()
+    }
+
+    /// Run background learning cycle if due
+    /// @returns Optional status message if cycle was executed
+    #[napi]
+    pub fn tick(&self) -> Option<String> {
+        self.inner.tick()
+    }
+
+    /// Force background learning cycle immediately
+    /// @returns Status message with learning results
+    #[napi]
+    pub fn force_learn(&self) -> String {
+        self.inner.force_learn()
+    }
+
+    /// Flush instant loop updates
+    #[napi]
+    pub fn flush(&self) {
+        self.inner.flush();
+    }
+
+    /// Find similar learned patterns to query
+    /// @param query_embedding - Query embedding vector
+    /// @param k - Number of patterns to return
+    /// @returns Array of learned patterns
+    #[napi]
+    pub fn find_patterns(&self, query_embedding: Vec<f64>, k: u32) -> Vec<JsLearnedPattern> {
+        let query: Vec<f32> = query_embedding.iter().map(|&x| x as f32).collect();
+        self.inner.find_patterns(&query, k as usize)
+            .into_iter()
+            .map(JsLearnedPattern::from)
+            .collect()
+    }
+
+    /// Get engine statistics as JSON string
+    /// @returns Statistics object as JSON string
+    #[napi]
+    pub fn get_stats(&self) -> String {
+        serde_json::to_string(&self.inner.stats()).unwrap_or_else(|e| {
+            format!("{{\"error\": \"{}\"}}", e)
+        })
+    }
+
+    /// Enable or disable the engine
+    /// @param enabled - Whether to enable the engine
+    #[napi]
+    pub fn set_enabled(&mut self, enabled: bool) {
+        self.inner.set_enabled(enabled);
+    }
+
+    /// Check if engine is enabled
+    /// @returns Whether the engine is enabled
+    #[napi]
+    pub fn is_enabled(&self) -> bool {
+        self.inner.is_enabled()
+    }
+}
+
+/// Trajectory builder for Node.js
+#[napi]
+pub struct TrajectoryBuilder {
+    inner: RustTrajectoryBuilder,
+}
+
+#[napi]
+impl TrajectoryBuilder {
+    /// Add a step to the trajectory
+    /// @param activations - Layer activations (Float64Array)
+    /// @param attention_weights - Attention weights (Float64Array)
+    /// @param reward - Reward signal for this step
+    #[napi]
+    pub fn add_step(&mut self, activations: Vec<f64>, attention_weights: Vec<f64>, reward: f64) {
+        let act: Vec<f32> = activations.iter().map(|&x| x as f32).collect();
+        let att: Vec<f32> = attention_weights.iter().map(|&x| x as f32).collect();
+        self.inner.add_step(act, att, reward as f32);
+    }
+
+    /// Set model route for this trajectory
+    /// @param route - Model route identifier
+    #[napi]
+    pub fn set_route(&mut self, route: String) {
+        self.inner.set_model_route(&route);
+    }
+
+    /// Add context ID to trajectory
+    /// @param context_id - Context identifier
+    #[napi]
+    pub fn add_context(&mut self, context_id: String) {
+        self.inner.add_context(&context_id);
+    }
+}
+
+/// SONA configuration for Node.js
+#[napi(object)]
+pub struct JsSonaConfig {
+    /// Hidden dimension size
+    pub hidden_dim: u32,
+    /// Embedding dimension (defaults to hidden_dim)
+    pub embedding_dim: Option<u32>,
+    /// Micro-LoRA rank (1-2, default: 1)
+    pub micro_lora_rank: Option<u32>,
+    /// Base LoRA rank (default: 8)
+    pub base_lora_rank: Option<u32>,
+    /// Micro-LoRA learning rate (default: 0.001)
+    pub micro_lora_lr: Option<f64>,
+    /// Base LoRA learning rate (default: 0.0001)
+    pub base_lora_lr: Option<f64>,
+    /// EWC lambda regularization (default: 1000.0)
+    pub ewc_lambda: Option<f64>,
+    /// Number of pattern clusters (default: 50)
+    pub pattern_clusters: Option<u32>,
+    /// Trajectory buffer capacity (default: 10000)
+    pub trajectory_capacity: Option<u32>,
+    /// Background learning interval in ms (default: 3600000 = 1 hour)
+    pub background_interval_ms: Option<i64>,
+    /// Quality threshold for learning (default: 0.5)
+    pub quality_threshold: Option<f64>,
+    /// Enable SIMD optimizations (default: true)
+    pub enable_simd: Option<bool>,
+}
+
+/// Learned pattern for Node.js
+#[napi(object)]
+pub struct JsLearnedPattern {
+    /// Pattern identifier
+    pub id: String,
+    /// Cluster centroid embedding
+    pub centroid: Vec<f64>,
+    /// Number of trajectories in cluster
+    pub cluster_size: u32,
+    /// Total weight of trajectories
+    pub total_weight: f64,
+    /// Average quality of member trajectories
+    pub avg_quality: f64,
+    /// Creation timestamp (Unix seconds)
+    pub created_at: String,
+    /// Last access timestamp (Unix seconds)
+    pub last_accessed: String,
+    /// Total access count
+    pub access_count: u32,
+    /// Pattern type
+    pub pattern_type: String,
+}
+
+impl From<LearnedPattern> for JsLearnedPattern {
+    fn from(pattern: LearnedPattern) -> Self {
+        Self {
+            id: pattern.id.to_string(),
+            centroid: pattern.centroid.iter().map(|&x| x as f64).collect(),
+            cluster_size: pattern.cluster_size as u32,
+            total_weight: pattern.total_weight as f64,
+            avg_quality: pattern.avg_quality as f64,
+            created_at: pattern.created_at.to_string(),
+            last_accessed: pattern.last_accessed.to_string(),
+            access_count: pattern.access_count,
+            pattern_type: format!("{:?}", pattern.pattern_type),
+        }
+    }
+}
+
+/// Pattern type enumeration
+#[napi]
+pub enum JsPatternType {
+    General,
+    Reasoning,
+    Factual,
+    Creative,
+    CodeGen,
+    Conversational,
+}
+
+impl From<JsPatternType> for PatternType {
+    fn from(js_type: JsPatternType) -> Self {
+        match js_type {
+            JsPatternType::General => PatternType::General,
+            JsPatternType::Reasoning => PatternType::Reasoning,
+            JsPatternType::Factual => PatternType::Factual,
+            JsPatternType::Creative => PatternType::Creative,
+            JsPatternType::CodeGen => PatternType::CodeGen,
+            JsPatternType::Conversational => PatternType::Conversational,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_napi_engine_creation() {
+        let engine = SonaEngine::new(256);
+        assert!(engine.is_enabled());
+    }
+
+    #[test]
+    fn test_napi_trajectory() {
+        let engine = SonaEngine::new(64);
+        let mut builder = engine.begin_trajectory(vec![0.1; 64]);
+        builder.add_step(vec![0.5; 64], vec![0.4; 32], 0.8);
+        engine.end_trajectory(&builder, 0.85);
+    }
+}

vendor/ruvector/crates/sona/src/napi_simple.rs

@@ -0,0 +1,286 @@
+//! Simplified NAPI-RS bindings for Node.js
+//! Enable with feature flag: `napi`
+//!
+//! This version uses a simpler API that doesn't expose TrajectoryBuilder to JS
+
+#![cfg(feature = "napi")]
+
+use napi_derive::napi;
+use std::collections::HashMap;
+use std::sync::{Mutex, OnceLock};
+
+use crate::{
+    LearnedPattern, SonaConfig, SonaEngine as RustSonaEngine,
+    TrajectoryBuilder as RustTrajectoryBuilder,
+};
+
+// Global storage for trajectory builders
+fn get_trajectory_builders() -> &'static Mutex<HashMap<u32, RustTrajectoryBuilder>> {
+    static BUILDERS: OnceLock<Mutex<HashMap<u32, RustTrajectoryBuilder>>> = OnceLock::new();
+    BUILDERS.get_or_init(|| Mutex::new(HashMap::new()))
+}
+
+fn get_next_builder_id() -> &'static Mutex<u32> {
+    static NEXT_ID: OnceLock<Mutex<u32>> = OnceLock::new();
+    NEXT_ID.get_or_init(|| Mutex::new(0))
+}
+
+/// Node.js SONA Engine wrapper
+#[napi]
+pub struct SonaEngine {
+    inner: RustSonaEngine,
+}
+
+#[napi]
+impl SonaEngine {
+    /// Create a new SONA engine with default configuration
+    /// @param hidden_dim - Hidden dimension size (e.g., 256, 512)
+    #[napi(constructor)]
+    pub fn new(hidden_dim: u32) -> Self {
+        Self {
+            inner: RustSonaEngine::new(hidden_dim as usize),
+        }
+    }
+
+    /// Create with custom configuration
+    /// @param config - Custom SONA configuration object
+    #[napi(factory)]
+    pub fn with_config(config: JsSonaConfig) -> Self {
+        let rust_config = SonaConfig {
+            hidden_dim: config.hidden_dim as usize,
+            embedding_dim: config.embedding_dim.unwrap_or(config.hidden_dim) as usize,
+            micro_lora_rank: config.micro_lora_rank.unwrap_or(1) as usize,
+            base_lora_rank: config.base_lora_rank.unwrap_or(8) as usize,
+            micro_lora_lr: config.micro_lora_lr.unwrap_or(0.001) as f32,
+            base_lora_lr: config.base_lora_lr.unwrap_or(0.0001) as f32,
+            ewc_lambda: config.ewc_lambda.unwrap_or(1000.0) as f32,
+            pattern_clusters: config.pattern_clusters.unwrap_or(50) as usize,
+            trajectory_capacity: config.trajectory_capacity.unwrap_or(10000) as usize,
+            background_interval_ms: config.background_interval_ms.unwrap_or(3600000) as u64,
+            quality_threshold: config.quality_threshold.unwrap_or(0.5) as f32,
+            enable_simd: config.enable_simd.unwrap_or(true),
+        };
+        Self {
+            inner: RustSonaEngine::with_config(rust_config),
+        }
+    }
+
+    /// Start a new trajectory recording
+    /// @param query_embedding - Query embedding vector (Float64Array)
+    /// @returns Trajectory ID for adding steps
+    #[napi]
+    pub fn begin_trajectory(&self, query_embedding: Vec<f64>) -> u32 {
+        let embedding: Vec<f32> = query_embedding.iter().map(|&x| x as f32).collect();
+        let builder = self.inner.begin_trajectory(embedding);
+
+        let mut builders = get_trajectory_builders().lock().unwrap();
+        let mut next_id = get_next_builder_id().lock().unwrap();
+        let id = *next_id;
+        *next_id += 1;
+        builders.insert(id, builder);
+        id
+    }
+
+    /// Add a step to trajectory
+    /// @param trajectory_id - Trajectory ID from beginTrajectory
+    /// @param activations - Layer activations (Float64Array)
+    /// @param attention_weights - Attention weights (Float64Array)
+    /// @param reward - Reward signal for this step
+    #[napi]
+    pub fn add_trajectory_step(
+        &self,
+        trajectory_id: u32,
+        activations: Vec<f64>,
+        attention_weights: Vec<f64>,
+        reward: f64,
+    ) {
+        let mut builders = get_trajectory_builders().lock().unwrap();
+        if let Some(builder) = builders.get_mut(&trajectory_id) {
+            let act: Vec<f32> = activations.iter().map(|&x| x as f32).collect();
+            let att: Vec<f32> = attention_weights.iter().map(|&x| x as f32).collect();
+            builder.add_step(act, att, reward as f32);
+        }
+    }
+
+    /// Set model route for trajectory
+    /// @param trajectory_id - Trajectory ID
+    /// @param route - Model route identifier
+    #[napi]
+    pub fn set_trajectory_route(&self, trajectory_id: u32, route: String) {
+        let mut builders = get_trajectory_builders().lock().unwrap();
+        if let Some(builder) = builders.get_mut(&trajectory_id) {
+            builder.set_model_route(&route);
+        }
+    }
+
+    /// Add context to trajectory
+    /// @param trajectory_id - Trajectory ID
+    /// @param context_id - Context identifier
+    #[napi]
+    pub fn add_trajectory_context(&self, trajectory_id: u32, context_id: String) {
+        let mut builders = get_trajectory_builders().lock().unwrap();
+        if let Some(builder) = builders.get_mut(&trajectory_id) {
+            builder.add_context(&context_id);
+        }
+    }
+
+    /// Complete a trajectory and submit for learning
+    /// @param trajectory_id - Trajectory ID
+    /// @param quality - Final quality score [0.0, 1.0]
+    #[napi]
+    pub fn end_trajectory(&self, trajectory_id: u32, quality: f64) {
+        let mut builders = get_trajectory_builders().lock().unwrap();
+        if let Some(builder) = builders.remove(&trajectory_id) {
+            let trajectory = builder.build(quality as f32);
+            self.inner.submit_trajectory(trajectory);
+        }
+    }
+
+    /// Apply micro-LoRA transformation to input
+    /// @param input - Input vector (Float64Array)
+    /// @returns Transformed output vector
+    #[napi]
+    pub fn apply_micro_lora(&self, input: Vec<f64>) -> Vec<f64> {
+        let input_f32: Vec<f32> = input.iter().map(|&x| x as f32).collect();
+        let mut output = vec![0.0f32; input_f32.len()];
+        self.inner.apply_micro_lora(&input_f32, &mut output);
+        output.iter().map(|&x| x as f64).collect()
+    }
+
+    /// Apply base-LoRA transformation to layer output
+    /// @param layer_idx - Layer index
+    /// @param input - Input vector (Float64Array)
+    /// @returns Transformed output vector
+    #[napi]
+    pub fn apply_base_lora(&self, layer_idx: u32, input: Vec<f64>) -> Vec<f64> {
+        let input_f32: Vec<f32> = input.iter().map(|&x| x as f32).collect();
+        let mut output = vec![0.0f32; input_f32.len()];
+        self.inner
+            .apply_base_lora(layer_idx as usize, &input_f32, &mut output);
+        output.iter().map(|&x| x as f64).collect()
+    }
+
+    /// Run background learning cycle if due
+    /// @returns Optional status message if cycle was executed
+    #[napi]
+    pub fn tick(&self) -> Option<String> {
+        self.inner.tick()
+    }
+
+    /// Force background learning cycle immediately
+    /// @returns Status message with learning results
+    #[napi]
+    pub fn force_learn(&self) -> String {
+        self.inner.force_learn()
+    }
+
+    /// Flush instant loop updates
+    #[napi]
+    pub fn flush(&self) {
+        self.inner.flush();
+    }
+
+    /// Find similar learned patterns to query
+    /// @param query_embedding - Query embedding vector
+    /// @param k - Number of patterns to return
+    /// @returns Array of learned patterns
+    #[napi]
+    pub fn find_patterns(&self, query_embedding: Vec<f64>, k: u32) -> Vec<JsLearnedPattern> {
+        let query: Vec<f32> = query_embedding.iter().map(|&x| x as f32).collect();
+        self.inner
+            .find_patterns(&query, k as usize)
+            .into_iter()
+            .map(JsLearnedPattern::from)
+            .collect()
+    }
+
+    /// Get engine statistics as JSON string
+    /// @returns Statistics object as JSON string
+    #[napi]
+    pub fn get_stats(&self) -> String {
+        serde_json::to_string(&self.inner.stats())
+            .unwrap_or_else(|e| format!("{{\"error\": \"{}\"}}", e))
+    }
+
+    /// Enable or disable the engine
+    /// @param enabled - Whether to enable the engine
+    #[napi]
+    pub fn set_enabled(&mut self, enabled: bool) {
+        self.inner.set_enabled(enabled);
+    }
+
+    /// Check if engine is enabled
+    /// @returns Whether the engine is enabled
+    #[napi]
+    pub fn is_enabled(&self) -> bool {
+        self.inner.is_enabled()
+    }
+}
+
+/// SONA configuration for Node.js
+#[napi(object)]
+pub struct JsSonaConfig {
+    /// Hidden dimension size
+    pub hidden_dim: u32,
+    /// Embedding dimension (defaults to hidden_dim)
+    pub embedding_dim: Option<u32>,
+    /// Micro-LoRA rank (1-2, default: 1)
+    pub micro_lora_rank: Option<u32>,
+    /// Base LoRA rank (default: 8)
+    pub base_lora_rank: Option<u32>,
+    /// Micro-LoRA learning rate (default: 0.001)
+    pub micro_lora_lr: Option<f64>,
+    /// Base LoRA learning rate (default: 0.0001)
+    pub base_lora_lr: Option<f64>,
+    /// EWC lambda regularization (default: 1000.0)
+    pub ewc_lambda: Option<f64>,
+    /// Number of pattern clusters (default: 50)
+    pub pattern_clusters: Option<u32>,
+    /// Trajectory buffer capacity (default: 10000)
+    pub trajectory_capacity: Option<u32>,
+    /// Background learning interval in ms (default: 3600000 = 1 hour)
+    pub background_interval_ms: Option<i64>,
+    /// Quality threshold for learning (default: 0.5)
+    pub quality_threshold: Option<f64>,
+    /// Enable SIMD optimizations (default: true)
+    pub enable_simd: Option<bool>,
+}
+
+/// Learned pattern for Node.js
+#[napi(object)]
+pub struct JsLearnedPattern {
+    /// Pattern identifier
+    pub id: String,
+    /// Cluster centroid embedding
+    pub centroid: Vec<f64>,
+    /// Number of trajectories in cluster
+    pub cluster_size: u32,
+    /// Total weight of trajectories
+    pub total_weight: f64,
+    /// Average quality of member trajectories
+    pub avg_quality: f64,
+    /// Creation timestamp (Unix seconds)
+    pub created_at: String,
+    /// Last access timestamp (Unix seconds)
+    pub last_accessed: String,
+    /// Total access count
+    pub access_count: u32,
+    /// Pattern type
+    pub pattern_type: String,
+}
+
+impl From<LearnedPattern> for JsLearnedPattern {
+    fn from(pattern: LearnedPattern) -> Self {
+        Self {
+            id: pattern.id.to_string(),
+            centroid: pattern.centroid.iter().map(|&x| x as f64).collect(),
+            cluster_size: pattern.cluster_size as u32,
+            total_weight: pattern.total_weight as f64,
+            avg_quality: pattern.avg_quality as f64,
+            created_at: pattern.created_at.to_string(),
+            last_accessed: pattern.last_accessed.to_string(),
+            access_count: pattern.access_count,
+            pattern_type: format!("{:?}", pattern.pattern_type),
+        }
+    }
+}

vendor/ruvector/crates/sona/src/reasoning_bank.rs

@@ -0,0 +1,554 @@
+//! ReasoningBank - Pattern storage and extraction for SONA
+//!
+//! Implements trajectory clustering using K-means++ for pattern discovery.
+
+use crate::types::{LearnedPattern, PatternType, QueryTrajectory};
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+/// ReasoningBank configuration
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct PatternConfig {
+    /// Number of clusters for K-means++
+    pub k_clusters: usize,
+    /// Embedding dimension
+    pub embedding_dim: usize,
+    /// Maximum K-means iterations
+    pub max_iterations: usize,
+    /// Convergence threshold
+    pub convergence_threshold: f32,
+    /// Minimum cluster size to keep
+    pub min_cluster_size: usize,
+    /// Maximum trajectories to store
+    pub max_trajectories: usize,
+    /// Quality threshold for pattern
+    pub quality_threshold: f32,
+}
+
+impl Default for PatternConfig {
+    fn default() -> Self {
+        // OPTIMIZED DEFAULTS based on @ruvector/sona v0.1.1 benchmarks:
+        // - 100 clusters = 1.3ms search vs 50 clusters = 3.0ms (2.3x faster)
+        // - Quality threshold 0.3 balances learning vs noise filtering
+        Self {
+            k_clusters: 100, // OPTIMIZED: 2.3x faster search (1.3ms vs 3.0ms)
+            embedding_dim: 256,
+            max_iterations: 100,
+            convergence_threshold: 0.001,
+            min_cluster_size: 5,
+            max_trajectories: 10000,
+            quality_threshold: 0.3, // OPTIMIZED: Lower threshold for more learning
+        }
+    }
+}
+
+/// ReasoningBank for pattern storage and extraction
+#[derive(Clone, Debug)]
+pub struct ReasoningBank {
+    /// Configuration
+    config: PatternConfig,
+    /// Stored trajectories
+    trajectories: Vec<TrajectoryEntry>,
+    /// Extracted patterns
+    patterns: HashMap<u64, LearnedPattern>,
+    /// Next pattern ID
+    next_pattern_id: u64,
+    /// Pattern index (embedding -> pattern_id)
+    pattern_index: Vec<(Vec<f32>, u64)>,
+}
+
+/// Internal trajectory entry with embedding
+#[derive(Clone, Debug)]
+struct TrajectoryEntry {
+    /// Trajectory embedding (query + avg activations)
+    embedding: Vec<f32>,
+    /// Quality score
+    quality: f32,
+    /// Cluster assignment
+    cluster: Option<usize>,
+    /// Original trajectory ID
+    _trajectory_id: u64,
+}
+
+impl ReasoningBank {
+    /// Create new ReasoningBank
+    pub fn new(config: PatternConfig) -> Self {
+        Self {
+            config,
+            trajectories: Vec::new(),
+            patterns: HashMap::new(),
+            next_pattern_id: 0,
+            pattern_index: Vec::new(),
+        }
+    }
+
+    /// Add trajectory to bank
+    pub fn add_trajectory(&mut self, trajectory: &QueryTrajectory) {
+        // Compute embedding from trajectory
+        let embedding = self.compute_embedding(trajectory);
+
+        let entry = TrajectoryEntry {
+            embedding,
+            quality: trajectory.final_quality,
+            cluster: None,
+            _trajectory_id: trajectory.id,
+        };
+
+        // Enforce capacity
+        if self.trajectories.len() >= self.config.max_trajectories {
+            // Remove oldest entries
+            let to_remove = self.trajectories.len() - self.config.max_trajectories + 1;
+            self.trajectories.drain(0..to_remove);
+        }
+
+        self.trajectories.push(entry);
+    }
+
+    /// Compute embedding from trajectory
+    fn compute_embedding(&self, trajectory: &QueryTrajectory) -> Vec<f32> {
+        let dim = self.config.embedding_dim;
+        let mut embedding = vec![0.0f32; dim];
+
+        // Start with query embedding
+        let query_len = trajectory.query_embedding.len().min(dim);
+        embedding[..query_len].copy_from_slice(&trajectory.query_embedding[..query_len]);
+
+        // Average in step activations (weighted by reward)
+        if !trajectory.steps.is_empty() {
+            let mut total_reward = 0.0f32;
+
+            for step in &trajectory.steps {
+                let weight = step.reward.max(0.0);
+                total_reward += weight;
+
+                for (i, &act) in step.activations.iter().enumerate() {
+                    if i < dim {
+                        embedding[i] += act * weight;
+                    }
+                }
+            }
+
+            if total_reward > 0.0 {
+                for e in &mut embedding {
+                    *e /= total_reward + 1.0; // +1 for query contribution
+                }
+            }
+        }
+
+        // L2 normalize
+        let norm: f32 = embedding.iter().map(|x| x * x).sum::<f32>().sqrt();
+        if norm > 1e-8 {
+            for e in &mut embedding {
+                *e /= norm;
+            }
+        }
+
+        embedding
+    }
+
+    /// Extract patterns using K-means++
+    pub fn extract_patterns(&mut self) -> Vec<LearnedPattern> {
+        if self.trajectories.is_empty() {
+            return Vec::new();
+        }
+
+        let k = self.config.k_clusters.min(self.trajectories.len());
+        if k == 0 {
+            return Vec::new();
+        }
+
+        // K-means++ initialization
+        let centroids = self.kmeans_plus_plus_init(k);
+
+        // Run K-means
+        let (final_centroids, assignments) = self.run_kmeans(centroids);
+
+        // Create patterns from clusters
+        let mut patterns = Vec::new();
+
+        for (cluster_idx, centroid) in final_centroids.into_iter().enumerate() {
+            // Collect cluster members
+            let members: Vec<_> = self
+                .trajectories
+                .iter()
+                .enumerate()
+                .filter(|(i, _)| assignments.get(*i) == Some(&cluster_idx))
+                .map(|(_, t)| t)
+                .collect();
+
+            if members.len() < self.config.min_cluster_size {
+                continue;
+            }
+
+            // Compute cluster statistics
+            let cluster_size = members.len();
+            let total_weight: f32 = members.iter().map(|t| t.quality).sum();
+            let avg_quality = total_weight / cluster_size as f32;
+
+            if avg_quality < self.config.quality_threshold {
+                continue;
+            }
+
+            let pattern_id = self.next_pattern_id;
+            self.next_pattern_id += 1;
+
+            let now = crate::time_compat::SystemTime::now()
+                .duration_since_epoch()
+                .as_secs();
+            let pattern = LearnedPattern {
+                id: pattern_id,
+                centroid,
+                cluster_size,
+                total_weight,
+                avg_quality,
+                created_at: now,
+                last_accessed: now,
+                access_count: 0,
+                pattern_type: PatternType::General,
+            };
+
+            self.patterns.insert(pattern_id, pattern.clone());
+            self.pattern_index
+                .push((pattern.centroid.clone(), pattern_id));
+            patterns.push(pattern);
+        }
+
+        // Update trajectory cluster assignments
+        for (i, cluster) in assignments.into_iter().enumerate() {
+            if i < self.trajectories.len() {
+                self.trajectories[i].cluster = Some(cluster);
+            }
+        }
+
+        patterns
+    }
+
+    /// K-means++ initialization
+    fn kmeans_plus_plus_init(&self, k: usize) -> Vec<Vec<f32>> {
+        let mut centroids = Vec::with_capacity(k);
+        let n = self.trajectories.len();
+
+        if n == 0 || k == 0 {
+            return centroids;
+        }
+
+        // First centroid: random (use deterministic selection for reproducibility)
+        let first_idx = 0;
+        centroids.push(self.trajectories[first_idx].embedding.clone());
+
+        // Remaining centroids: D^2 weighting
+        for _ in 1..k {
+            // Compute distances to nearest centroid
+            let mut distances: Vec<f32> = self
+                .trajectories
+                .iter()
+                .map(|t| {
+                    centroids
+                        .iter()
+                        .map(|c| self.squared_distance(&t.embedding, c))
+                        .fold(f32::MAX, f32::min)
+                })
+                .collect();
+
+            // Normalize to probabilities
+            let total: f32 = distances.iter().sum();
+            if total > 0.0 {
+                for d in &mut distances {
+                    *d /= total;
+                }
+            }
+
+            // Select next centroid (deterministic: highest distance)
+            // SECURITY FIX (H-004): Handle NaN values in partial_cmp safely
+            let (next_idx, _) = distances
+                .iter()
+                .enumerate()
+                .max_by(|a, b| a.1.partial_cmp(b.1).unwrap_or(std::cmp::Ordering::Equal))
+                .unwrap_or((0, &0.0));
+
+            centroids.push(self.trajectories[next_idx].embedding.clone());
+        }
+
+        centroids
+    }
+
+    /// Run K-means algorithm
+    fn run_kmeans(&self, mut centroids: Vec<Vec<f32>>) -> (Vec<Vec<f32>>, Vec<usize>) {
+        let n = self.trajectories.len();
+        let k = centroids.len();
+        let dim = self.config.embedding_dim;
+
+        let mut assignments = vec![0usize; n];
+
+        for _iter in 0..self.config.max_iterations {
+            // Assign points to nearest centroid
+            let mut changed = false;
+            for (i, t) in self.trajectories.iter().enumerate() {
+                // SECURITY FIX (H-004): Handle NaN values in partial_cmp safely
+                let (nearest, _) = centroids
+                    .iter()
+                    .enumerate()
+                    .map(|(j, c)| (j, self.squared_distance(&t.embedding, c)))
+                    .min_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal))
+                    .unwrap_or((0, 0.0));
+
+                if assignments[i] != nearest {
+                    assignments[i] = nearest;
+                    changed = true;
+                }
+            }
+
+            if !changed {
+                break;
+            }
+
+            // Update centroids
+            let mut new_centroids = vec![vec![0.0f32; dim]; k];
+            let mut counts = vec![0usize; k];
+
+            for (i, t) in self.trajectories.iter().enumerate() {
+                let cluster = assignments[i];
+                counts[cluster] += 1;
+                for (j, &e) in t.embedding.iter().enumerate() {
+                    new_centroids[cluster][j] += e;
+                }
+            }
+
+            // Average and check convergence
+            let mut max_shift = 0.0f32;
+            for (i, new_c) in new_centroids.iter_mut().enumerate() {
+                if counts[i] > 0 {
+                    for e in new_c.iter_mut() {
+                        *e /= counts[i] as f32;
+                    }
+                    let shift = self.squared_distance(new_c, &centroids[i]).sqrt();
+                    max_shift = max_shift.max(shift);
+                }
+            }
+
+            centroids = new_centroids;
+
+            if max_shift < self.config.convergence_threshold {
+                break;
+            }
+        }
+
+        (centroids, assignments)
+    }
+
+    /// Squared Euclidean distance
+    fn squared_distance(&self, a: &[f32], b: &[f32]) -> f32 {
+        a.iter()
+            .zip(b.iter())
+            .map(|(&x, &y)| (x - y) * (x - y))
+            .sum()
+    }
+
+    /// Find similar patterns
+    pub fn find_similar(&self, query: &[f32], k: usize) -> Vec<&LearnedPattern> {
+        let mut scored: Vec<_> = self
+            .patterns
+            .values()
+            .map(|p| (p, p.similarity(query)))
+            .collect();
+
+        // Note: This already has the safe unwrap_or pattern for NaN handling
+        scored.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
+
+        scored.into_iter().take(k).map(|(p, _)| p).collect()
+    }
+
+    /// Get pattern by ID
+    pub fn get_pattern(&self, id: u64) -> Option<&LearnedPattern> {
+        self.patterns.get(&id)
+    }
+
+    /// Get mutable pattern by ID
+    pub fn get_pattern_mut(&mut self, id: u64) -> Option<&mut LearnedPattern> {
+        self.patterns.get_mut(&id)
+    }
+
+    /// Get trajectory count
+    pub fn trajectory_count(&self) -> usize {
+        self.trajectories.len()
+    }
+
+    /// Get pattern count
+    pub fn pattern_count(&self) -> usize {
+        self.patterns.len()
+    }
+
+    /// Clear trajectories (keep patterns)
+    pub fn clear_trajectories(&mut self) {
+        self.trajectories.clear();
+    }
+
+    /// Prune low-quality patterns
+    pub fn prune_patterns(&mut self, min_quality: f32, min_accesses: u32, max_age_secs: u64) {
+        let to_remove: Vec<u64> = self
+            .patterns
+            .iter()
+            .filter(|(_, p)| p.should_prune(min_quality, min_accesses, max_age_secs))
+            .map(|(id, _)| *id)
+            .collect();
+
+        for id in to_remove {
+            self.patterns.remove(&id);
+        }
+
+        // Update index
+        self.pattern_index
+            .retain(|(_, id)| self.patterns.contains_key(id));
+    }
+
+    /// Get all patterns for export
+    pub fn get_all_patterns(&self) -> Vec<LearnedPattern> {
+        self.patterns.values().cloned().collect()
+    }
+
+    /// Consolidate similar patterns
+    pub fn consolidate(&mut self, similarity_threshold: f32) {
+        let pattern_ids: Vec<u64> = self.patterns.keys().copied().collect();
+        let mut merged = Vec::new();
+
+        for i in 0..pattern_ids.len() {
+            for j in i + 1..pattern_ids.len() {
+                let id1 = pattern_ids[i];
+                let id2 = pattern_ids[j];
+
+                if merged.contains(&id1) || merged.contains(&id2) {
+                    continue;
+                }
+
+                if let (Some(p1), Some(p2)) = (self.patterns.get(&id1), self.patterns.get(&id2)) {
+                    let sim = p1.similarity(&p2.centroid);
+                    if sim > similarity_threshold {
+                        // Merge p2 into p1
+                        let merged_pattern = p1.merge(p2);
+                        self.patterns.insert(id1, merged_pattern);
+                        merged.push(id2);
+                    }
+                }
+            }
+        }
+
+        // Remove merged patterns
+        for id in merged {
+            self.patterns.remove(&id);
+        }
+
+        // Update index
+        self.pattern_index
+            .retain(|(_, id)| self.patterns.contains_key(id));
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_trajectory(id: u64, embedding: Vec<f32>, quality: f32) -> QueryTrajectory {
+        let mut t = QueryTrajectory::new(id, embedding);
+        t.finalize(quality, 1000);
+        t
+    }
+
+    #[test]
+    fn test_bank_creation() {
+        let bank = ReasoningBank::new(PatternConfig::default());
+        assert_eq!(bank.trajectory_count(), 0);
+        assert_eq!(bank.pattern_count(), 0);
+    }
+
+    #[test]
+    fn test_add_trajectory() {
+        let config = PatternConfig {
+            embedding_dim: 4,
+            ..Default::default()
+        };
+        let mut bank = ReasoningBank::new(config);
+
+        let t = make_trajectory(1, vec![0.1, 0.2, 0.3, 0.4], 0.8);
+        bank.add_trajectory(&t);
+
+        assert_eq!(bank.trajectory_count(), 1);
+    }
+
+    #[test]
+    fn test_extract_patterns() {
+        let config = PatternConfig {
+            embedding_dim: 4,
+            k_clusters: 2,
+            min_cluster_size: 2,
+            quality_threshold: 0.0,
+            ..Default::default()
+        };
+        let mut bank = ReasoningBank::new(config);
+
+        // Add clustered trajectories
+        for i in 0..5 {
+            let t = make_trajectory(i, vec![1.0, 0.0, 0.0, 0.0], 0.8);
+            bank.add_trajectory(&t);
+        }
+        for i in 5..10 {
+            let t = make_trajectory(i, vec![0.0, 1.0, 0.0, 0.0], 0.7);
+            bank.add_trajectory(&t);
+        }
+
+        let patterns = bank.extract_patterns();
+        assert!(!patterns.is_empty());
+    }
+
+    #[test]
+    fn test_find_similar() {
+        let config = PatternConfig {
+            embedding_dim: 4,
+            k_clusters: 2,
+            min_cluster_size: 2,
+            quality_threshold: 0.0,
+            ..Default::default()
+        };
+        let mut bank = ReasoningBank::new(config);
+
+        for i in 0..10 {
+            let emb = if i < 5 {
+                vec![1.0, 0.0, 0.0, 0.0]
+            } else {
+                vec![0.0, 1.0, 0.0, 0.0]
+            };
+            bank.add_trajectory(&make_trajectory(i, emb, 0.8));
+        }
+
+        bank.extract_patterns();
+
+        let query = vec![0.9, 0.1, 0.0, 0.0];
+        let similar = bank.find_similar(&query, 1);
+        assert!(!similar.is_empty());
+    }
+
+    #[test]
+    fn test_consolidate() {
+        let config = PatternConfig {
+            embedding_dim: 4,
+            k_clusters: 3,
+            min_cluster_size: 1,
+            quality_threshold: 0.0,
+            ..Default::default()
+        };
+        let mut bank = ReasoningBank::new(config);
+
+        // Create very similar trajectories
+        for i in 0..9 {
+            let emb = vec![1.0 + (i as f32 * 0.001), 0.0, 0.0, 0.0];
+            bank.add_trajectory(&make_trajectory(i, emb, 0.8));
+        }
+
+        bank.extract_patterns();
+        let before = bank.pattern_count();
+
+        bank.consolidate(0.99);
+        let after = bank.pattern_count();
+
+        assert!(after <= before);
+    }
+}

vendor/ruvector/crates/sona/src/time_compat.rs

@@ -0,0 +1,139 @@
+//! Cross-platform time abstraction for native and WASM targets.
+//!
+//! Uses `std::time::Instant` on native platforms and `performance.now()` on WASM.
+//! Uses `std::time::SystemTime` on native platforms and `Date.now()` on WASM.
+
+#[cfg(not(target_arch = "wasm32"))]
+mod native {
+    use std::fmt;
+    use std::time::{Duration, Instant as StdInstant, SystemTime as StdSystemTime, UNIX_EPOCH};
+
+    #[derive(Clone, Copy)]
+    pub struct Instant(StdInstant);
+
+    impl Instant {
+        pub fn now() -> Self {
+            Instant(StdInstant::now())
+        }
+
+        pub fn elapsed(&self) -> Duration {
+            self.0.elapsed()
+        }
+    }
+
+    impl Default for Instant {
+        fn default() -> Self {
+            Self::now()
+        }
+    }
+
+    impl fmt::Debug for Instant {
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            self.0.fmt(f)
+        }
+    }
+
+    #[derive(Clone, Copy)]
+    pub struct SystemTime(StdSystemTime);
+
+    impl SystemTime {
+        pub fn now() -> Self {
+            SystemTime(StdSystemTime::now())
+        }
+
+        pub fn duration_since_epoch(&self) -> Duration {
+            self.0.duration_since(UNIX_EPOCH).unwrap_or(Duration::ZERO)
+        }
+    }
+
+    impl fmt::Debug for SystemTime {
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            self.0.fmt(f)
+        }
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+mod wasm {
+    use std::fmt;
+    use std::time::Duration;
+
+    fn performance_now() -> f64 {
+        #[cfg(feature = "wasm")]
+        {
+            use wasm_bindgen::JsCast;
+            js_sys::Reflect::get(&js_sys::global(), &"performance".into())
+                .ok()
+                .and_then(|p| p.dyn_into::<web_sys::Performance>().ok())
+                .map(|p| p.now())
+                .unwrap_or(0.0)
+        }
+        #[cfg(not(feature = "wasm"))]
+        {
+            0.0
+        }
+    }
+
+    fn date_now() -> f64 {
+        #[cfg(feature = "wasm")]
+        {
+            js_sys::Date::now()
+        }
+        #[cfg(not(feature = "wasm"))]
+        {
+            0.0
+        }
+    }
+
+    #[derive(Clone, Copy)]
+    pub struct Instant(f64);
+
+    impl Instant {
+        pub fn now() -> Self {
+            Instant(performance_now())
+        }
+
+        pub fn elapsed(&self) -> Duration {
+            let now = performance_now();
+            let elapsed_ms = (now - self.0).max(0.0);
+            Duration::from_secs_f64(elapsed_ms / 1000.0)
+        }
+    }
+
+    impl Default for Instant {
+        fn default() -> Self {
+            Self::now()
+        }
+    }
+
+    impl fmt::Debug for Instant {
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            write!(f, "Instant({}ms)", self.0)
+        }
+    }
+
+    #[derive(Clone, Copy)]
+    pub struct SystemTime(f64);
+
+    impl SystemTime {
+        pub fn now() -> Self {
+            SystemTime(date_now())
+        }
+
+        pub fn duration_since_epoch(&self) -> Duration {
+            Duration::from_secs_f64(self.0 / 1000.0)
+        }
+    }
+
+    impl fmt::Debug for SystemTime {
+        fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+            write!(f, "SystemTime({}ms)", self.0)
+        }
+    }
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+pub use native::{Instant, SystemTime};
+
+#[cfg(target_arch = "wasm32")]
+pub use wasm::{Instant, SystemTime};

vendor/ruvector/crates/sona/src/training/factory.rs

@@ -0,0 +1,510 @@
+//! Agent Factory for SONA
+//!
+//! Create and manage multiple specialized agents.
+
+use super::metrics::TrainingMetrics;
+use super::templates::{AgentType, TrainingTemplate};
+use crate::engine::SonaEngine;
+use crate::time_compat::SystemTime;
+use crate::types::SonaConfig;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::sync::{Arc, RwLock};
+
+/// Handle to a managed agent
+#[derive(Clone, Debug)]
+pub struct AgentHandle {
+    /// Agent identifier
+    pub id: String,
+    /// Agent type
+    pub agent_type: AgentType,
+    /// Creation timestamp
+    pub created_at: u64,
+}
+
+/// Managed agent with engine and metadata
+pub struct ManagedAgent {
+    /// Agent handle
+    pub handle: AgentHandle,
+    /// SONA engine
+    pub engine: SonaEngine,
+    /// Training metrics
+    pub metrics: TrainingMetrics,
+    /// Purpose/description
+    pub purpose: String,
+    /// Training count
+    pub training_count: u64,
+    /// Tags for organization
+    pub tags: Vec<String>,
+}
+
+impl ManagedAgent {
+    /// Create a new managed agent
+    pub fn new(
+        id: impl Into<String>,
+        agent_type: AgentType,
+        config: SonaConfig,
+        purpose: impl Into<String>,
+    ) -> Self {
+        let now = SystemTime::now().duration_since_epoch().as_secs();
+
+        let id = id.into();
+        Self {
+            handle: AgentHandle {
+                id: id.clone(),
+                agent_type,
+                created_at: now,
+            },
+            engine: SonaEngine::with_config(config),
+            metrics: TrainingMetrics::new(&id),
+            purpose: purpose.into(),
+            training_count: 0,
+            tags: Vec::new(),
+        }
+    }
+
+    /// Get agent stats
+    pub fn stats(&self) -> AgentStats {
+        AgentStats {
+            id: self.handle.id.clone(),
+            agent_type: self.handle.agent_type.clone(),
+            training_count: self.training_count,
+            patterns_learned: self.metrics.patterns_learned,
+            avg_quality: self.metrics.avg_quality(),
+            total_examples: self.metrics.total_examples,
+        }
+    }
+}
+
+/// Agent statistics
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentStats {
+    /// Agent ID
+    pub id: String,
+    /// Agent type
+    pub agent_type: AgentType,
+    /// Number of training sessions
+    pub training_count: u64,
+    /// Patterns learned
+    pub patterns_learned: usize,
+    /// Average quality score
+    pub avg_quality: f32,
+    /// Total examples processed
+    pub total_examples: usize,
+}
+
+/// Factory for creating and managing agents
+pub struct AgentFactory {
+    /// Base configuration for all agents
+    base_config: SonaConfig,
+    /// Managed agents
+    agents: HashMap<String, ManagedAgent>,
+    /// Default hidden dimension
+    default_hidden_dim: usize,
+}
+
+impl Default for AgentFactory {
+    fn default() -> Self {
+        Self::new(SonaConfig::default())
+    }
+}
+
+impl AgentFactory {
+    /// Create a new agent factory
+    pub fn new(base_config: SonaConfig) -> Self {
+        let default_hidden_dim = base_config.hidden_dim;
+        Self {
+            base_config,
+            agents: HashMap::new(),
+            default_hidden_dim,
+        }
+    }
+
+    /// Create factory with specific hidden dimension
+    pub fn with_hidden_dim(hidden_dim: usize) -> Self {
+        let config = SonaConfig {
+            hidden_dim,
+            embedding_dim: hidden_dim,
+            ..SonaConfig::default()
+        };
+        Self::new(config)
+    }
+
+    /// Create an agent from a template
+    pub fn create_from_template(
+        &mut self,
+        name: impl Into<String>,
+        template: &TrainingTemplate,
+    ) -> &ManagedAgent {
+        let name = name.into();
+        let agent = ManagedAgent::new(
+            name.clone(),
+            template.agent_type.clone(),
+            template.sona_config.clone(),
+            &template.name,
+        );
+        self.agents.insert(name.clone(), agent);
+        self.agents.get(&name).unwrap()
+    }
+
+    /// Create an agent with custom configuration
+    pub fn create_agent(
+        &mut self,
+        name: impl Into<String>,
+        agent_type: AgentType,
+        purpose: impl Into<String>,
+    ) -> &ManagedAgent {
+        let name = name.into();
+        let config = self.config_for_agent_type(&agent_type);
+        let mut agent = ManagedAgent::new(name.clone(), agent_type, config, purpose);
+        agent.tags.push("custom".into());
+        self.agents.insert(name.clone(), agent);
+        self.agents.get(&name).unwrap()
+    }
+
+    /// Create a code agent
+    pub fn create_code_agent(&mut self, name: impl Into<String>) -> &ManagedAgent {
+        let template = TrainingTemplate::code_agent().with_hidden_dim(self.default_hidden_dim);
+        self.create_from_template(name, &template)
+    }
+
+    /// Create a chat agent
+    pub fn create_chat_agent(&mut self, name: impl Into<String>) -> &ManagedAgent {
+        let template = TrainingTemplate::chat_agent().with_hidden_dim(self.default_hidden_dim);
+        self.create_from_template(name, &template)
+    }
+
+    /// Create a RAG agent
+    pub fn create_rag_agent(&mut self, name: impl Into<String>) -> &ManagedAgent {
+        let template = TrainingTemplate::rag_agent().with_hidden_dim(self.default_hidden_dim);
+        self.create_from_template(name, &template)
+    }
+
+    /// Create a task planner agent
+    pub fn create_task_planner(&mut self, name: impl Into<String>) -> &ManagedAgent {
+        let template = TrainingTemplate::task_planner().with_hidden_dim(self.default_hidden_dim);
+        self.create_from_template(name, &template)
+    }
+
+    /// Create a reasoning agent
+    pub fn create_reasoning_agent(&mut self, name: impl Into<String>) -> &ManagedAgent {
+        let template = TrainingTemplate::reasoning_agent().with_hidden_dim(self.default_hidden_dim);
+        self.create_from_template(name, &template)
+    }
+
+    /// Create a codebase helper agent
+    pub fn create_codebase_helper(&mut self, name: impl Into<String>) -> &ManagedAgent {
+        let template = TrainingTemplate::codebase_helper().with_hidden_dim(self.default_hidden_dim);
+        self.create_from_template(name, &template)
+    }
+
+    /// Get an agent by name
+    pub fn get_agent(&self, name: &str) -> Option<&ManagedAgent> {
+        self.agents.get(name)
+    }
+
+    /// Get a mutable agent by name
+    pub fn get_agent_mut(&mut self, name: &str) -> Option<&mut ManagedAgent> {
+        self.agents.get_mut(name)
+    }
+
+    /// Remove an agent
+    pub fn remove_agent(&mut self, name: &str) -> Option<ManagedAgent> {
+        self.agents.remove(name)
+    }
+
+    /// List all agents
+    pub fn list_agents(&self) -> Vec<AgentStats> {
+        self.agents.values().map(|a| a.stats()).collect()
+    }
+
+    /// Get agent count
+    pub fn agent_count(&self) -> usize {
+        self.agents.len()
+    }
+
+    /// Train an agent with examples
+    pub fn train_agent<E>(
+        &mut self,
+        name: &str,
+        examples: impl Iterator<Item = E>,
+    ) -> Result<usize, String>
+    where
+        E: TrainingExample,
+    {
+        let agent = self
+            .agents
+            .get_mut(name)
+            .ok_or_else(|| format!("Agent '{}' not found", name))?;
+
+        let mut count = 0;
+        for example in examples {
+            // Use builder-based trajectory API
+            let mut builder = agent.engine.begin_trajectory(example.embedding());
+
+            // Set route if available
+            if let Some(route) = example.route() {
+                builder.set_model_route(&route);
+            }
+
+            // Add context if available
+            for ctx in example.context() {
+                builder.add_context(&ctx);
+            }
+
+            // Add step with activations
+            builder.add_step(example.activations(), example.attention(), example.reward());
+
+            // End trajectory with quality
+            agent.engine.end_trajectory(builder, example.quality());
+
+            count += 1;
+            agent.metrics.total_examples += 1;
+            agent.metrics.add_quality_sample(example.quality());
+        }
+
+        // Force learning after batch
+        agent.engine.force_learn();
+        agent.training_count += 1;
+        agent.metrics.training_sessions += 1;
+
+        Ok(count)
+    }
+
+    /// Get configuration for agent type
+    fn config_for_agent_type(&self, agent_type: &AgentType) -> SonaConfig {
+        let mut config = self.base_config.clone();
+
+        match agent_type {
+            AgentType::CodeAgent | AgentType::CodebaseHelper => {
+                config.base_lora_rank = 16;
+                config.pattern_clusters = 200;
+                config.quality_threshold = 0.2;
+            }
+            AgentType::ChatAgent => {
+                config.base_lora_rank = 8;
+                config.pattern_clusters = 50;
+                config.quality_threshold = 0.4;
+            }
+            AgentType::RagAgent => {
+                config.pattern_clusters = 200;
+                config.trajectory_capacity = 10000;
+            }
+            AgentType::TaskPlanner => {
+                config.base_lora_rank = 16;
+                config.ewc_lambda = 2000.0;
+            }
+            AgentType::ReasoningAgent => {
+                config.base_lora_rank = 16;
+                config.ewc_lambda = 3000.0;
+                config.pattern_clusters = 150;
+            }
+            AgentType::DomainExpert => {
+                config.quality_threshold = 0.1;
+                config.trajectory_capacity = 20000;
+            }
+            AgentType::DataAnalyst => {
+                config.base_lora_rank = 8;
+                config.pattern_clusters = 100;
+            }
+            AgentType::CreativeWriter => {
+                config.base_lora_rank = 8;
+                config.pattern_clusters = 50;
+                config.quality_threshold = 0.5;
+            }
+            _ => {}
+        }
+
+        config
+    }
+}
+
+/// Trait for training examples
+pub trait TrainingExample {
+    /// Get embedding vector
+    fn embedding(&self) -> Vec<f32>;
+
+    /// Get activations (can be same as embedding)
+    fn activations(&self) -> Vec<f32> {
+        self.embedding()
+    }
+
+    /// Get attention weights
+    fn attention(&self) -> Vec<f32> {
+        vec![1.0 / 64.0; 64]
+    }
+
+    /// Get reward signal
+    fn reward(&self) -> f32 {
+        self.quality()
+    }
+
+    /// Get quality score
+    fn quality(&self) -> f32;
+
+    /// Get optional route
+    fn route(&self) -> Option<String> {
+        None
+    }
+
+    /// Get context identifiers
+    fn context(&self) -> Vec<String> {
+        Vec::new()
+    }
+}
+
+/// Simple training example implementation
+#[derive(Clone, Debug)]
+pub struct SimpleExample {
+    /// Embedding vector
+    pub embedding: Vec<f32>,
+    /// Quality score
+    pub quality: f32,
+    /// Optional route
+    pub route: Option<String>,
+    /// Context IDs
+    pub context: Vec<String>,
+}
+
+impl SimpleExample {
+    /// Create a new simple example
+    pub fn new(embedding: Vec<f32>, quality: f32) -> Self {
+        Self {
+            embedding,
+            quality,
+            route: None,
+            context: Vec::new(),
+        }
+    }
+
+    /// Set route
+    pub fn with_route(mut self, route: impl Into<String>) -> Self {
+        self.route = Some(route.into());
+        self
+    }
+
+    /// Add context
+    pub fn with_context(mut self, ctx: impl Into<String>) -> Self {
+        self.context.push(ctx.into());
+        self
+    }
+}
+
+impl TrainingExample for SimpleExample {
+    fn embedding(&self) -> Vec<f32> {
+        self.embedding.clone()
+    }
+
+    fn quality(&self) -> f32 {
+        self.quality
+    }
+
+    fn route(&self) -> Option<String> {
+        self.route.clone()
+    }
+
+    fn context(&self) -> Vec<String> {
+        self.context.clone()
+    }
+}
+
+/// Thread-safe agent factory wrapper
+pub struct SharedAgentFactory {
+    inner: Arc<RwLock<AgentFactory>>,
+}
+
+impl SharedAgentFactory {
+    /// Create a new shared factory
+    pub fn new(config: SonaConfig) -> Self {
+        Self {
+            inner: Arc::new(RwLock::new(AgentFactory::new(config))),
+        }
+    }
+
+    /// Get read access to factory
+    pub fn read(&self) -> std::sync::RwLockReadGuard<'_, AgentFactory> {
+        self.inner.read().unwrap()
+    }
+
+    /// Get write access to factory
+    pub fn write(&self) -> std::sync::RwLockWriteGuard<'_, AgentFactory> {
+        self.inner.write().unwrap()
+    }
+
+    /// Clone the Arc
+    pub fn clone_arc(&self) -> Self {
+        Self {
+            inner: Arc::clone(&self.inner),
+        }
+    }
+}
+
+impl Clone for SharedAgentFactory {
+    fn clone(&self) -> Self {
+        self.clone_arc()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_factory_creation() {
+        let factory = AgentFactory::default();
+        assert_eq!(factory.agent_count(), 0);
+    }
+
+    #[test]
+    fn test_create_agents() {
+        let mut factory = AgentFactory::with_hidden_dim(256);
+
+        factory.create_code_agent("code-1");
+        factory.create_chat_agent("chat-1");
+        factory.create_rag_agent("rag-1");
+
+        assert_eq!(factory.agent_count(), 3);
+        assert!(factory.get_agent("code-1").is_some());
+        assert!(factory.get_agent("unknown").is_none());
+    }
+
+    #[test]
+    fn test_agent_from_template() {
+        let mut factory = AgentFactory::with_hidden_dim(256);
+        let template = TrainingTemplate::reasoning_agent().with_hidden_dim(256);
+
+        factory.create_from_template("reasoner", &template);
+
+        let agent = factory.get_agent("reasoner").unwrap();
+        assert_eq!(agent.handle.agent_type, AgentType::ReasoningAgent);
+    }
+
+    #[test]
+    fn test_train_agent() {
+        let mut factory = AgentFactory::with_hidden_dim(256);
+        factory.create_chat_agent("bot");
+
+        let examples = vec![
+            SimpleExample::new(vec![0.1; 256], 0.8).with_route("greeting"),
+            SimpleExample::new(vec![0.2; 256], 0.9).with_route("question"),
+            SimpleExample::new(vec![0.3; 256], 0.7).with_route("farewell"),
+        ];
+
+        let count = factory.train_agent("bot", examples.into_iter()).unwrap();
+        assert_eq!(count, 3);
+
+        let agent = factory.get_agent("bot").unwrap();
+        assert_eq!(agent.training_count, 1);
+        assert_eq!(agent.metrics.total_examples, 3);
+    }
+
+    #[test]
+    fn test_list_agents() {
+        let mut factory = AgentFactory::with_hidden_dim(256);
+        factory.create_code_agent("code");
+        factory.create_chat_agent("chat");
+
+        let agents = factory.list_agents();
+        assert_eq!(agents.len(), 2);
+    }
+}

vendor/ruvector/crates/sona/src/training/federated.rs

@@ -0,0 +1,681 @@
+//! Federated Learning for SONA
+//!
+//! Enable distributed learning across ephemeral agents that share
+//! trajectories with a central coordinator.
+//!
+//! ## Architecture
+//!
+//! ```text
+//! ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+//! │  Agent A    │     │  Agent B    │     │  Agent C    │
+//! │ (ephemeral) │     │ (ephemeral) │     │ (ephemeral) │
+//! └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
+//!        │                   │                   │
+//!        │    export()       │    export()       │    export()
+//!        ▼                   ▼                   ▼
+//!   ┌────────────────────────────────────────────────┐
+//!   │            Federated Coordinator               │
+//!   │         (persistent, large capacity)           │
+//!   └────────────────────────────────────────────────┘
+//! ```
+
+use super::metrics::TrainingMetrics;
+use crate::engine::SonaEngine;
+use crate::time_compat::SystemTime;
+use crate::types::{LearnedPattern, SonaConfig};
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+/// Exported state from an ephemeral agent
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentExport {
+    /// Agent identifier
+    pub agent_id: String,
+    /// Exported trajectories (embedding, quality pairs)
+    pub trajectories: Vec<TrajectoryExport>,
+    /// Agent statistics
+    pub stats: AgentExportStats,
+    /// Session duration in milliseconds
+    pub session_duration_ms: u64,
+    /// Export timestamp
+    pub timestamp: u64,
+}
+
+/// Single trajectory export
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TrajectoryExport {
+    /// Query embedding
+    pub embedding: Vec<f32>,
+    /// Quality score
+    pub quality: f32,
+    /// Model route (if any)
+    pub route: Option<String>,
+    /// Context identifiers
+    pub context: Vec<String>,
+    /// Timestamp
+    pub timestamp: u64,
+}
+
+/// Agent export statistics
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub struct AgentExportStats {
+    /// Total trajectories processed
+    pub total_trajectories: usize,
+    /// Average quality
+    pub avg_quality: f32,
+    /// Patterns learned locally
+    pub patterns_learned: usize,
+}
+
+/// Ephemeral agent for federated learning
+///
+/// Collects trajectories during its session and exports state before termination.
+pub struct EphemeralAgent {
+    /// Agent identifier
+    agent_id: String,
+    /// SONA engine
+    engine: SonaEngine,
+    /// Collected trajectories
+    trajectories: Vec<TrajectoryExport>,
+    /// Session start time
+    start_time: u64,
+    /// Quality samples
+    quality_samples: Vec<f32>,
+}
+
+impl EphemeralAgent {
+    /// Create a new ephemeral agent
+    pub fn new(agent_id: impl Into<String>, config: SonaConfig) -> Self {
+        let now = SystemTime::now().duration_since_epoch().as_millis() as u64;
+
+        Self {
+            agent_id: agent_id.into(),
+            engine: SonaEngine::with_config(config),
+            trajectories: Vec::new(),
+            start_time: now,
+            quality_samples: Vec::new(),
+        }
+    }
+
+    /// Create with default config for federated learning
+    pub fn default_federated(agent_id: impl Into<String>, hidden_dim: usize) -> Self {
+        Self::new(
+            agent_id,
+            SonaConfig {
+                hidden_dim,
+                embedding_dim: hidden_dim,
+                micro_lora_rank: 2,
+                base_lora_rank: 8,
+                micro_lora_lr: 0.002,
+                trajectory_capacity: 500, // Small buffer per agent
+                pattern_clusters: 25,
+                ..Default::default()
+            },
+        )
+    }
+
+    /// Get agent ID
+    pub fn agent_id(&self) -> &str {
+        &self.agent_id
+    }
+
+    /// Get engine reference
+    pub fn engine(&self) -> &SonaEngine {
+        &self.engine
+    }
+
+    /// Get mutable engine reference
+    pub fn engine_mut(&mut self) -> &mut SonaEngine {
+        &mut self.engine
+    }
+
+    /// Process a task and record trajectory
+    pub fn process_trajectory(
+        &mut self,
+        embedding: Vec<f32>,
+        activations: Vec<f32>,
+        quality: f32,
+        route: Option<String>,
+        context: Vec<String>,
+    ) {
+        let now = SystemTime::now().duration_since_epoch().as_millis() as u64;
+
+        // Record in SONA engine
+        let mut builder = self.engine.begin_trajectory(embedding.clone());
+        if let Some(ref r) = route {
+            builder.set_model_route(r);
+        }
+        for ctx in &context {
+            builder.add_context(ctx);
+        }
+        builder.add_step(activations, vec![], quality);
+        self.engine.end_trajectory(builder, quality);
+
+        // Store for export
+        self.trajectories.push(TrajectoryExport {
+            embedding,
+            quality,
+            route,
+            context,
+            timestamp: now,
+        });
+
+        self.quality_samples.push(quality);
+    }
+
+    /// Apply micro-LoRA to hidden states
+    pub fn apply_micro_lora(&self, input: &[f32], output: &mut [f32]) {
+        self.engine.apply_micro_lora(input, output);
+    }
+
+    /// Get number of collected trajectories
+    pub fn trajectory_count(&self) -> usize {
+        self.trajectories.len()
+    }
+
+    /// Get average quality
+    pub fn avg_quality(&self) -> f32 {
+        if self.quality_samples.is_empty() {
+            0.0
+        } else {
+            self.quality_samples.iter().sum::<f32>() / self.quality_samples.len() as f32
+        }
+    }
+
+    /// Force local learning
+    pub fn force_learn(&self) -> String {
+        self.engine.force_learn()
+    }
+
+    /// Simple process task method
+    pub fn process_task(&mut self, embedding: Vec<f32>, quality: f32) {
+        self.process_trajectory(embedding.clone(), embedding, quality, None, vec![]);
+    }
+
+    /// Process task with route information
+    pub fn process_task_with_route(&mut self, embedding: Vec<f32>, quality: f32, route: &str) {
+        self.process_trajectory(
+            embedding.clone(),
+            embedding,
+            quality,
+            Some(route.to_string()),
+            vec![],
+        );
+    }
+
+    /// Get average quality (alias for avg_quality)
+    pub fn average_quality(&self) -> f32 {
+        self.avg_quality()
+    }
+
+    /// Get uptime in seconds
+    pub fn uptime_seconds(&self) -> u64 {
+        let now = SystemTime::now().duration_since_epoch().as_millis() as u64;
+        (now - self.start_time) / 1000
+    }
+
+    /// Get agent stats
+    pub fn stats(&self) -> AgentExportStats {
+        let engine_stats = self.engine.stats();
+        AgentExportStats {
+            total_trajectories: self.trajectories.len(),
+            avg_quality: self.avg_quality(),
+            patterns_learned: engine_stats.patterns_stored,
+        }
+    }
+
+    /// Clear trajectories (after export)
+    pub fn clear(&mut self) {
+        self.trajectories.clear();
+        self.quality_samples.clear();
+    }
+
+    /// Get learned patterns from agent
+    pub fn get_patterns(&self) -> Vec<LearnedPattern> {
+        self.engine.find_patterns(&[], 0)
+    }
+
+    /// Export agent state for federation
+    ///
+    /// Call this before terminating the agent.
+    pub fn export_state(&self) -> AgentExport {
+        let now = SystemTime::now().duration_since_epoch().as_millis() as u64;
+
+        // Force learning before export
+        self.engine.force_learn();
+
+        let stats = self.engine.stats();
+
+        AgentExport {
+            agent_id: self.agent_id.clone(),
+            trajectories: self.trajectories.clone(),
+            stats: AgentExportStats {
+                total_trajectories: self.trajectories.len(),
+                avg_quality: self.avg_quality(),
+                patterns_learned: stats.patterns_stored,
+            },
+            session_duration_ms: now - self.start_time,
+            timestamp: now,
+        }
+    }
+}
+
+/// Agent contribution record
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AgentContribution {
+    /// Number of trajectories contributed
+    pub trajectory_count: usize,
+    /// Average quality of contributions
+    pub avg_quality: f32,
+    /// Contribution timestamp
+    pub timestamp: u64,
+    /// Session duration
+    pub session_duration_ms: u64,
+}
+
+/// Federated learning coordinator
+///
+/// Aggregates learning from multiple ephemeral agents.
+pub struct FederatedCoordinator {
+    /// Coordinator identifier
+    coordinator_id: String,
+    /// Master SONA engine for aggregation
+    master_engine: SonaEngine,
+    /// Agent contributions
+    contributions: HashMap<String, AgentContribution>,
+    /// Quality threshold for accepting trajectories
+    quality_threshold: f32,
+    /// Total trajectories aggregated
+    total_trajectories: usize,
+    /// Consolidation interval (number of agents)
+    consolidation_interval: usize,
+    /// Metrics
+    metrics: TrainingMetrics,
+}
+
+impl FederatedCoordinator {
+    /// Create a new federated coordinator
+    pub fn new(coordinator_id: impl Into<String>, config: SonaConfig) -> Self {
+        let id = coordinator_id.into();
+        Self {
+            coordinator_id: id.clone(),
+            master_engine: SonaEngine::with_config(config),
+            contributions: HashMap::new(),
+            quality_threshold: 0.4,
+            total_trajectories: 0,
+            consolidation_interval: 50,
+            metrics: TrainingMetrics::new(&id),
+        }
+    }
+
+    /// Create with default config for coordination
+    pub fn default_coordinator(coordinator_id: impl Into<String>, hidden_dim: usize) -> Self {
+        Self::new(
+            coordinator_id,
+            SonaConfig {
+                hidden_dim,
+                embedding_dim: hidden_dim,
+                micro_lora_rank: 2,
+                base_lora_rank: 16,         // Deeper for aggregation
+                trajectory_capacity: 50000, // Large central buffer
+                pattern_clusters: 200,
+                ewc_lambda: 2000.0, // Strong regularization
+                ..Default::default()
+            },
+        )
+    }
+
+    /// Get coordinator ID
+    pub fn coordinator_id(&self) -> &str {
+        &self.coordinator_id
+    }
+
+    /// Set quality threshold for accepting trajectories
+    pub fn set_quality_threshold(&mut self, threshold: f32) {
+        self.quality_threshold = threshold;
+    }
+
+    /// Set consolidation interval
+    pub fn set_consolidation_interval(&mut self, interval: usize) {
+        self.consolidation_interval = interval;
+    }
+
+    /// Get master engine reference
+    pub fn master_engine(&self) -> &SonaEngine {
+        &self.master_engine
+    }
+
+    /// Aggregate agent export into coordinator
+    pub fn aggregate(&mut self, export: AgentExport) -> AggregationResult {
+        let mut accepted = 0;
+        let mut rejected = 0;
+
+        // Replay trajectories into master engine
+        for traj in &export.trajectories {
+            if traj.quality >= self.quality_threshold {
+                let mut builder = self.master_engine.begin_trajectory(traj.embedding.clone());
+                if let Some(ref route) = traj.route {
+                    builder.set_model_route(route);
+                }
+                for ctx in &traj.context {
+                    builder.add_context(ctx);
+                }
+                self.master_engine.end_trajectory(builder, traj.quality);
+
+                self.metrics.add_quality_sample(traj.quality);
+                accepted += 1;
+            } else {
+                rejected += 1;
+            }
+        }
+
+        self.total_trajectories += accepted;
+
+        // Record contribution
+        let now = SystemTime::now().duration_since_epoch().as_millis() as u64;
+
+        self.contributions.insert(
+            export.agent_id.clone(),
+            AgentContribution {
+                trajectory_count: export.trajectories.len(),
+                avg_quality: export.stats.avg_quality,
+                timestamp: now,
+                session_duration_ms: export.session_duration_ms,
+            },
+        );
+
+        // Auto-consolidate if needed
+        let consolidated = if self.should_consolidate() {
+            self.master_engine.force_learn();
+            true
+        } else {
+            false
+        };
+
+        AggregationResult {
+            agent_id: export.agent_id,
+            trajectories_accepted: accepted,
+            trajectories_rejected: rejected,
+            consolidated,
+            total_agents: self.contributions.len(),
+            total_trajectories: self.total_trajectories,
+        }
+    }
+
+    /// Check if consolidation is needed
+    fn should_consolidate(&self) -> bool {
+        self.contributions.len() % self.consolidation_interval == 0
+    }
+
+    /// Force consolidation
+    pub fn force_consolidate(&self) -> String {
+        self.master_engine.force_learn()
+    }
+
+    /// Get initial state for new agents
+    ///
+    /// Returns learned patterns that new agents can use for warm start.
+    pub fn get_initial_patterns(&self, k: usize) -> Vec<LearnedPattern> {
+        // Find patterns similar to a general query (empty or average)
+        // Since we don't have a specific query, get all patterns
+        self.master_engine
+            .find_patterns(&[], 0)
+            .into_iter()
+            .take(k)
+            .collect()
+    }
+
+    /// Get all learned patterns
+    pub fn get_all_patterns(&self) -> Vec<LearnedPattern> {
+        self.master_engine.find_patterns(&[], 0)
+    }
+
+    /// Get coordinator statistics
+    pub fn stats(&self) -> CoordinatorStats {
+        let engine_stats = self.master_engine.stats();
+
+        CoordinatorStats {
+            coordinator_id: self.coordinator_id.clone(),
+            total_agents: self.contributions.len(),
+            total_trajectories: self.total_trajectories,
+            patterns_learned: engine_stats.patterns_stored,
+            avg_quality: self.metrics.avg_quality(),
+            quality_threshold: self.quality_threshold,
+        }
+    }
+
+    /// Get contribution history
+    pub fn contributions(&self) -> &HashMap<String, AgentContribution> {
+        &self.contributions
+    }
+
+    /// Get metrics
+    pub fn metrics(&self) -> &TrainingMetrics {
+        &self.metrics
+    }
+
+    /// Get total number of contributing agents
+    pub fn agent_count(&self) -> usize {
+        self.contributions.len()
+    }
+
+    /// Get total trajectories aggregated
+    pub fn total_trajectories(&self) -> usize {
+        self.total_trajectories
+    }
+
+    /// Find similar patterns
+    pub fn find_patterns(&self, query: &[f32], k: usize) -> Vec<LearnedPattern> {
+        self.master_engine.find_patterns(query, k)
+    }
+
+    /// Apply coordinator's LoRA to input
+    pub fn apply_lora(&self, input: &[f32]) -> Vec<f32> {
+        let mut output = vec![0.0; input.len()];
+        self.master_engine.apply_micro_lora(input, &mut output);
+        output
+    }
+
+    /// Consolidate learning (alias for force_consolidate)
+    pub fn consolidate(&self) -> String {
+        self.force_consolidate()
+    }
+
+    /// Clear all contributions
+    pub fn clear(&mut self) {
+        self.contributions.clear();
+        self.total_trajectories = 0;
+    }
+}
+
+/// Result of aggregating an agent export
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AggregationResult {
+    /// Agent ID that was aggregated
+    pub agent_id: String,
+    /// Number of trajectories accepted
+    pub trajectories_accepted: usize,
+    /// Number of trajectories rejected (below quality threshold)
+    pub trajectories_rejected: usize,
+    /// Whether consolidation was triggered
+    pub consolidated: bool,
+    /// Total number of contributing agents
+    pub total_agents: usize,
+    /// Total trajectories in coordinator
+    pub total_trajectories: usize,
+}
+
+/// Coordinator statistics
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct CoordinatorStats {
+    /// Coordinator identifier
+    pub coordinator_id: String,
+    /// Number of contributing agents
+    pub total_agents: usize,
+    /// Total trajectories aggregated
+    pub total_trajectories: usize,
+    /// Patterns learned
+    pub patterns_learned: usize,
+    /// Average quality across all contributions
+    pub avg_quality: f32,
+    /// Quality threshold
+    pub quality_threshold: f32,
+}
+
+impl std::fmt::Display for CoordinatorStats {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "Coordinator(id={}, agents={}, trajectories={}, patterns={}, avg_quality={:.4})",
+            self.coordinator_id,
+            self.total_agents,
+            self.total_trajectories,
+            self.patterns_learned,
+            self.avg_quality
+        )
+    }
+}
+
+/// Federated learning topology
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub enum FederatedTopology {
+    /// Agents -> Central Coordinator (simple, single aggregation point)
+    #[default]
+    Star,
+    /// Agents -> Regional -> Global (multi-datacenter)
+    Hierarchical {
+        /// Number of regional coordinators
+        regions: usize,
+    },
+    /// Agents share directly (edge deployment)
+    PeerToPeer,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_ephemeral_agent_creation() {
+        let agent = EphemeralAgent::default_federated("agent-1", 256);
+        assert_eq!(agent.agent_id(), "agent-1");
+        assert_eq!(agent.trajectory_count(), 0);
+    }
+
+    #[test]
+    fn test_trajectory_collection() {
+        let mut agent = EphemeralAgent::default_federated("agent-1", 256);
+
+        agent.process_trajectory(
+            vec![0.1; 256],
+            vec![0.5; 256],
+            0.8,
+            Some("code".into()),
+            vec!["file:main.rs".into()],
+        );
+
+        assert_eq!(agent.trajectory_count(), 1);
+        assert!((agent.avg_quality() - 0.8).abs() < 0.01);
+    }
+
+    #[test]
+    fn test_agent_export() {
+        let mut agent = EphemeralAgent::default_federated("agent-1", 256);
+
+        for i in 0..5 {
+            agent.process_trajectory(
+                vec![i as f32 * 0.1; 256],
+                vec![0.5; 256],
+                0.7 + i as f32 * 0.05,
+                None,
+                vec![],
+            );
+        }
+
+        let export = agent.export_state();
+        assert_eq!(export.agent_id, "agent-1");
+        assert_eq!(export.trajectories.len(), 5);
+        assert!(export.stats.avg_quality > 0.7);
+    }
+
+    #[test]
+    fn test_coordinator_creation() {
+        let coord = FederatedCoordinator::default_coordinator("coord-1", 256);
+        assert_eq!(coord.coordinator_id(), "coord-1");
+
+        let stats = coord.stats();
+        assert_eq!(stats.total_agents, 0);
+        assert_eq!(stats.total_trajectories, 0);
+    }
+
+    #[test]
+    fn test_aggregation() {
+        let mut coord = FederatedCoordinator::default_coordinator("coord-1", 256);
+        coord.set_quality_threshold(0.5);
+
+        // Create agent export
+        let export = AgentExport {
+            agent_id: "agent-1".into(),
+            trajectories: vec![
+                TrajectoryExport {
+                    embedding: vec![0.1; 256],
+                    quality: 0.8,
+                    route: Some("code".into()),
+                    context: vec![],
+                    timestamp: 0,
+                },
+                TrajectoryExport {
+                    embedding: vec![0.2; 256],
+                    quality: 0.3, // Below threshold
+                    route: None,
+                    context: vec![],
+                    timestamp: 0,
+                },
+            ],
+            stats: AgentExportStats {
+                total_trajectories: 2,
+                avg_quality: 0.55,
+                patterns_learned: 0,
+            },
+            session_duration_ms: 1000,
+            timestamp: 0,
+        };
+
+        let result = coord.aggregate(export);
+        assert_eq!(result.trajectories_accepted, 1);
+        assert_eq!(result.trajectories_rejected, 1);
+        assert_eq!(result.total_agents, 1);
+    }
+
+    #[test]
+    fn test_multi_agent_aggregation() {
+        let mut coord = FederatedCoordinator::default_coordinator("coord-1", 256);
+        coord.set_consolidation_interval(2); // Consolidate every 2 agents
+
+        for i in 0..3 {
+            let export = AgentExport {
+                agent_id: format!("agent-{}", i),
+                trajectories: vec![TrajectoryExport {
+                    embedding: vec![i as f32 * 0.1; 256],
+                    quality: 0.8,
+                    route: None,
+                    context: vec![],
+                    timestamp: 0,
+                }],
+                stats: AgentExportStats::default(),
+                session_duration_ms: 1000,
+                timestamp: 0,
+            };
+
+            let result = coord.aggregate(export);
+            // Second agent should trigger consolidation
+            if i == 1 {
+                assert!(result.consolidated);
+            }
+        }
+
+        let stats = coord.stats();
+        assert_eq!(stats.total_agents, 3);
+        assert_eq!(stats.total_trajectories, 3);
+    }
+}

vendor/ruvector/crates/sona/src/training/metrics.rs

@@ -0,0 +1,468 @@
+//! Training Metrics for SONA
+//!
+//! Comprehensive analytics for training sessions.
+
+use serde::{Deserialize, Serialize};
+
+/// Training metrics collection
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub struct TrainingMetrics {
+    /// Pipeline/agent name
+    pub name: String,
+    /// Total examples processed
+    pub total_examples: usize,
+    /// Total training sessions
+    pub training_sessions: u64,
+    /// Patterns learned
+    pub patterns_learned: usize,
+    /// Quality samples for averaging
+    pub quality_samples: Vec<f32>,
+    /// Validation quality (if validation was run)
+    pub validation_quality: Option<f32>,
+    /// Performance metrics
+    pub performance: PerformanceMetrics,
+}
+
+impl TrainingMetrics {
+    /// Create new metrics
+    pub fn new(name: &str) -> Self {
+        Self {
+            name: name.to_string(),
+            ..Default::default()
+        }
+    }
+
+    /// Add quality sample
+    pub fn add_quality_sample(&mut self, quality: f32) {
+        self.quality_samples.push(quality);
+        // Keep last 10000 samples
+        if self.quality_samples.len() > 10000 {
+            self.quality_samples.remove(0);
+        }
+    }
+
+    /// Get average quality
+    pub fn avg_quality(&self) -> f32 {
+        if self.quality_samples.is_empty() {
+            0.0
+        } else {
+            self.quality_samples.iter().sum::<f32>() / self.quality_samples.len() as f32
+        }
+    }
+
+    /// Get quality percentile
+    pub fn quality_percentile(&self, percentile: f32) -> f32 {
+        if self.quality_samples.is_empty() {
+            return 0.0;
+        }
+
+        let mut sorted = self.quality_samples.clone();
+        sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
+
+        let idx = ((percentile / 100.0) * (sorted.len() - 1) as f32) as usize;
+        sorted[idx.min(sorted.len() - 1)]
+    }
+
+    /// Get quality statistics
+    pub fn quality_stats(&self) -> QualityMetrics {
+        if self.quality_samples.is_empty() {
+            return QualityMetrics::default();
+        }
+
+        let avg = self.avg_quality();
+        let min = self
+            .quality_samples
+            .iter()
+            .cloned()
+            .fold(f32::MAX, f32::min);
+        let max = self
+            .quality_samples
+            .iter()
+            .cloned()
+            .fold(f32::MIN, f32::max);
+
+        let variance = self
+            .quality_samples
+            .iter()
+            .map(|q| (q - avg).powi(2))
+            .sum::<f32>()
+            / self.quality_samples.len() as f32;
+        let std_dev = variance.sqrt();
+
+        QualityMetrics {
+            avg,
+            min,
+            max,
+            std_dev,
+            p25: self.quality_percentile(25.0),
+            p50: self.quality_percentile(50.0),
+            p75: self.quality_percentile(75.0),
+            p95: self.quality_percentile(95.0),
+            sample_count: self.quality_samples.len(),
+        }
+    }
+
+    /// Reset metrics
+    pub fn reset(&mut self) {
+        self.total_examples = 0;
+        self.training_sessions = 0;
+        self.patterns_learned = 0;
+        self.quality_samples.clear();
+        self.validation_quality = None;
+        self.performance = PerformanceMetrics::default();
+    }
+
+    /// Merge with another metrics instance
+    pub fn merge(&mut self, other: &TrainingMetrics) {
+        self.total_examples += other.total_examples;
+        self.training_sessions += other.training_sessions;
+        self.patterns_learned = other.patterns_learned; // Take latest
+        self.quality_samples.extend(&other.quality_samples);
+
+        // Keep last 10000
+        if self.quality_samples.len() > 10000 {
+            let excess = self.quality_samples.len() - 10000;
+            self.quality_samples.drain(0..excess);
+        }
+    }
+}
+
+/// Quality metrics summary
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub struct QualityMetrics {
+    /// Average quality
+    pub avg: f32,
+    /// Minimum quality
+    pub min: f32,
+    /// Maximum quality
+    pub max: f32,
+    /// Standard deviation
+    pub std_dev: f32,
+    /// 25th percentile
+    pub p25: f32,
+    /// 50th percentile (median)
+    pub p50: f32,
+    /// 75th percentile
+    pub p75: f32,
+    /// 95th percentile
+    pub p95: f32,
+    /// Number of samples
+    pub sample_count: usize,
+}
+
+impl std::fmt::Display for QualityMetrics {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "avg={:.4}, std={:.4}, min={:.4}, max={:.4}, p50={:.4}, p95={:.4} (n={})",
+            self.avg, self.std_dev, self.min, self.max, self.p50, self.p95, self.sample_count
+        )
+    }
+}
+
+/// Performance metrics
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub struct PerformanceMetrics {
+    /// Total training time in seconds
+    pub total_training_secs: f64,
+    /// Average batch processing time in milliseconds
+    pub avg_batch_time_ms: f64,
+    /// Average example processing time in microseconds
+    pub avg_example_time_us: f64,
+    /// Peak memory usage in MB
+    pub peak_memory_mb: usize,
+    /// Examples per second throughput
+    pub examples_per_sec: f64,
+    /// Pattern extraction time in milliseconds
+    pub pattern_extraction_ms: f64,
+}
+
+impl PerformanceMetrics {
+    /// Calculate throughput
+    pub fn calculate_throughput(&mut self, examples: usize, duration_secs: f64) {
+        if duration_secs > 0.0 {
+            self.examples_per_sec = examples as f64 / duration_secs;
+            self.avg_example_time_us = (duration_secs * 1_000_000.0) / examples as f64;
+        }
+    }
+}
+
+/// Epoch statistics
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct EpochStats {
+    /// Epoch number (0-indexed)
+    pub epoch: usize,
+    /// Examples processed in this epoch
+    pub examples_processed: usize,
+    /// Average quality for this epoch
+    pub avg_quality: f32,
+    /// Duration in seconds
+    pub duration_secs: f64,
+}
+
+impl std::fmt::Display for EpochStats {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "Epoch {}: {} examples, avg_quality={:.4}, {:.2}s",
+            self.epoch + 1,
+            self.examples_processed,
+            self.avg_quality,
+            self.duration_secs
+        )
+    }
+}
+
+/// Training result summary
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TrainingResult {
+    /// Pipeline name
+    pub pipeline_name: String,
+    /// Number of epochs completed
+    pub epochs_completed: usize,
+    /// Total examples processed
+    pub total_examples: usize,
+    /// Patterns learned
+    pub patterns_learned: usize,
+    /// Final average quality
+    pub final_avg_quality: f32,
+    /// Total duration in seconds
+    pub total_duration_secs: f64,
+    /// Per-epoch statistics
+    pub epoch_stats: Vec<EpochStats>,
+    /// Validation quality (if validation was run)
+    pub validation_quality: Option<f32>,
+}
+
+impl TrainingResult {
+    /// Get examples per second
+    pub fn examples_per_sec(&self) -> f64 {
+        if self.total_duration_secs > 0.0 {
+            self.total_examples as f64 / self.total_duration_secs
+        } else {
+            0.0
+        }
+    }
+
+    /// Get average epoch duration
+    pub fn avg_epoch_duration(&self) -> f64 {
+        if self.epochs_completed > 0 {
+            self.total_duration_secs / self.epochs_completed as f64
+        } else {
+            0.0
+        }
+    }
+
+    /// Check if training improved quality
+    pub fn quality_improved(&self) -> bool {
+        if self.epoch_stats.len() < 2 {
+            return false;
+        }
+        let first = self.epoch_stats.first().unwrap().avg_quality;
+        let last = self.epoch_stats.last().unwrap().avg_quality;
+        last > first
+    }
+
+    /// Get quality improvement
+    pub fn quality_improvement(&self) -> f32 {
+        if self.epoch_stats.len() < 2 {
+            return 0.0;
+        }
+        let first = self.epoch_stats.first().unwrap().avg_quality;
+        let last = self.epoch_stats.last().unwrap().avg_quality;
+        last - first
+    }
+}
+
+impl std::fmt::Display for TrainingResult {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "TrainingResult(pipeline={}, epochs={}, examples={}, patterns={}, \
+             final_quality={:.4}, duration={:.2}s, throughput={:.1}/s)",
+            self.pipeline_name,
+            self.epochs_completed,
+            self.total_examples,
+            self.patterns_learned,
+            self.final_avg_quality,
+            self.total_duration_secs,
+            self.examples_per_sec()
+        )
+    }
+}
+
+/// Comparison metrics between training runs
+#[derive(Clone, Debug, Serialize, Deserialize)]
+#[allow(dead_code)]
+pub struct TrainingComparison {
+    /// Baseline result name
+    pub baseline_name: String,
+    /// Comparison result name
+    pub comparison_name: String,
+    /// Quality difference (comparison - baseline)
+    pub quality_diff: f32,
+    /// Quality improvement percentage
+    pub quality_improvement_pct: f32,
+    /// Throughput difference
+    pub throughput_diff: f64,
+    /// Duration difference in seconds
+    pub duration_diff: f64,
+}
+
+#[allow(dead_code)]
+impl TrainingComparison {
+    /// Compare two training results
+    pub fn compare(baseline: &TrainingResult, comparison: &TrainingResult) -> Self {
+        let quality_diff = comparison.final_avg_quality - baseline.final_avg_quality;
+        let quality_improvement_pct = if baseline.final_avg_quality > 0.0 {
+            (quality_diff / baseline.final_avg_quality) * 100.0
+        } else {
+            0.0
+        };
+
+        Self {
+            baseline_name: baseline.pipeline_name.clone(),
+            comparison_name: comparison.pipeline_name.clone(),
+            quality_diff,
+            quality_improvement_pct,
+            throughput_diff: comparison.examples_per_sec() - baseline.examples_per_sec(),
+            duration_diff: comparison.total_duration_secs - baseline.total_duration_secs,
+        }
+    }
+}
+
+impl std::fmt::Display for TrainingComparison {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let quality_sign = if self.quality_diff >= 0.0 { "+" } else { "" };
+        let throughput_sign = if self.throughput_diff >= 0.0 { "+" } else { "" };
+
+        write!(
+            f,
+            "Comparison {} vs {}: quality {}{:.4} ({}{:.1}%), throughput {}{:.1}/s",
+            self.comparison_name,
+            self.baseline_name,
+            quality_sign,
+            self.quality_diff,
+            quality_sign,
+            self.quality_improvement_pct,
+            throughput_sign,
+            self.throughput_diff
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_metrics_creation() {
+        let metrics = TrainingMetrics::new("test");
+        assert_eq!(metrics.name, "test");
+        assert_eq!(metrics.total_examples, 0);
+    }
+
+    #[test]
+    fn test_quality_samples() {
+        let mut metrics = TrainingMetrics::new("test");
+
+        for i in 0..10 {
+            metrics.add_quality_sample(i as f32 / 10.0);
+        }
+
+        assert_eq!(metrics.quality_samples.len(), 10);
+        assert!((metrics.avg_quality() - 0.45).abs() < 0.01);
+    }
+
+    #[test]
+    fn test_quality_percentiles() {
+        let mut metrics = TrainingMetrics::new("test");
+
+        for i in 0..100 {
+            metrics.add_quality_sample(i as f32 / 100.0);
+        }
+
+        assert!((metrics.quality_percentile(50.0) - 0.5).abs() < 0.02);
+        assert!((metrics.quality_percentile(95.0) - 0.95).abs() < 0.02);
+    }
+
+    #[test]
+    fn test_quality_stats() {
+        let mut metrics = TrainingMetrics::new("test");
+        metrics.add_quality_sample(0.5);
+        metrics.add_quality_sample(0.7);
+        metrics.add_quality_sample(0.9);
+
+        let stats = metrics.quality_stats();
+        assert!((stats.avg - 0.7).abs() < 0.01);
+        assert!((stats.min - 0.5).abs() < 0.01);
+        assert!((stats.max - 0.9).abs() < 0.01);
+    }
+
+    #[test]
+    fn test_training_result() {
+        let result = TrainingResult {
+            pipeline_name: "test".into(),
+            epochs_completed: 3,
+            total_examples: 1000,
+            patterns_learned: 50,
+            final_avg_quality: 0.85,
+            total_duration_secs: 10.0,
+            epoch_stats: vec![
+                EpochStats {
+                    epoch: 0,
+                    examples_processed: 333,
+                    avg_quality: 0.75,
+                    duration_secs: 3.0,
+                },
+                EpochStats {
+                    epoch: 1,
+                    examples_processed: 333,
+                    avg_quality: 0.80,
+                    duration_secs: 3.5,
+                },
+                EpochStats {
+                    epoch: 2,
+                    examples_processed: 334,
+                    avg_quality: 0.85,
+                    duration_secs: 3.5,
+                },
+            ],
+            validation_quality: Some(0.82),
+        };
+
+        assert_eq!(result.examples_per_sec(), 100.0);
+        assert!(result.quality_improved());
+        assert!((result.quality_improvement() - 0.10).abs() < 0.01);
+    }
+
+    #[test]
+    fn test_training_comparison() {
+        let baseline = TrainingResult {
+            pipeline_name: "baseline".into(),
+            epochs_completed: 2,
+            total_examples: 500,
+            patterns_learned: 25,
+            final_avg_quality: 0.70,
+            total_duration_secs: 5.0,
+            epoch_stats: vec![],
+            validation_quality: None,
+        };
+
+        let improved = TrainingResult {
+            pipeline_name: "improved".into(),
+            epochs_completed: 2,
+            total_examples: 500,
+            patterns_learned: 30,
+            final_avg_quality: 0.85,
+            total_duration_secs: 4.0,
+            epoch_stats: vec![],
+            validation_quality: None,
+        };
+
+        let comparison = TrainingComparison::compare(&baseline, &improved);
+        assert!((comparison.quality_diff - 0.15).abs() < 0.01);
+        assert!(comparison.quality_improvement_pct > 20.0);
+        assert!(comparison.throughput_diff > 0.0);
+    }
+}

vendor/ruvector/crates/sona/src/training/mod.rs

@@ -0,0 +1,70 @@
+//! SONA Training System
+//!
+//! Templated training pipelines for specialized model adaptation.
+//!
+//! ## Overview
+//!
+//! The training module provides:
+//! - **Training Templates**: Pre-configured training setups for common use cases
+//! - **Agent Factory**: Create and manage multiple specialized agents
+//! - **Training Pipelines**: Structured workflows for different verticals
+//! - **Federated Learning**: Distributed training across ephemeral agents
+//! - **Metrics & Results**: Comprehensive training analytics
+//!
+//! ## Quick Start
+//!
+//! ```rust,ignore
+//! use ruvector_sona::training::{TrainingTemplate, AgentFactory, TrainingPipeline};
+//!
+//! // Use a preset template
+//! let template = TrainingTemplate::code_agent();
+//! let pipeline = TrainingPipeline::from_template(template);
+//!
+//! // Train on examples
+//! for example in examples {
+//!     pipeline.add_example(example);
+//! }
+//! let results = pipeline.train()?;
+//! ```
+//!
+//! ## Federated Learning
+//!
+//! ```rust,ignore
+//! use ruvector_sona::training::{EphemeralAgent, FederatedCoordinator};
+//!
+//! // Create coordinator
+//! let mut coordinator = FederatedCoordinator::default_coordinator("main", 3072);
+//!
+//! // Ephemeral agents process tasks
+//! let mut agent = EphemeralAgent::default_federated("agent-1", 3072);
+//! agent.process_trajectory(embedding, activations, quality, route, context);
+//!
+//! // Export state before termination
+//! let export = agent.export_state();
+//! coordinator.aggregate(export);
+//! ```
+
+mod factory;
+mod federated;
+mod metrics;
+mod pipeline;
+mod templates;
+
+pub use factory::{
+    AgentFactory, AgentHandle, AgentStats, ManagedAgent, SharedAgentFactory, SimpleExample,
+    TrainingExample as FactoryTrainingExample,
+};
+pub use federated::{
+    AgentContribution, AgentExport, AgentExportStats, AggregationResult, CoordinatorStats,
+    EphemeralAgent, FederatedCoordinator, FederatedTopology, TrajectoryExport,
+};
+pub use metrics::{
+    EpochStats, PerformanceMetrics, QualityMetrics, TrainingMetrics, TrainingResult,
+};
+pub use pipeline::{
+    BatchConfig, PipelineStage, TrainingCallback, TrainingExample, TrainingPipeline,
+};
+pub use templates::{
+    AgentType, DataSizeHint, TaskDomain, TemplatePreset, TrainingMethod, TrainingTemplate,
+    VerticalConfig,
+};

vendor/ruvector/crates/sona/src/training/pipeline.rs

@@ -0,0 +1,709 @@
+//! Training Pipeline for SONA
+//!
+//! Structured training workflows with batching and callbacks.
+
+use super::metrics::{EpochStats, TrainingMetrics, TrainingResult};
+use super::templates::{DataSizeHint, TrainingMethod, TrainingTemplate};
+use crate::engine::SonaEngine;
+use crate::time_compat::Instant;
+use crate::types::SonaConfig;
+use serde::{Deserialize, Serialize};
+
+/// Training example with all data needed for learning
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TrainingExample {
+    /// Input embedding
+    pub embedding: Vec<f32>,
+    /// Hidden activations (optional, defaults to embedding)
+    pub activations: Option<Vec<f32>>,
+    /// Attention weights (optional)
+    pub attention: Option<Vec<f32>>,
+    /// Quality score [0.0, 1.0]
+    pub quality: f32,
+    /// Reward signal (optional, defaults to quality)
+    pub reward: Option<f32>,
+    /// Model route identifier
+    pub route: Option<String>,
+    /// Context identifiers
+    pub context: Vec<String>,
+    /// Example weight for importance sampling
+    pub weight: f32,
+    /// Tags for filtering
+    pub tags: Vec<String>,
+}
+
+impl TrainingExample {
+    /// Create a new training example
+    pub fn new(embedding: Vec<f32>, quality: f32) -> Self {
+        Self {
+            embedding,
+            activations: None,
+            attention: None,
+            quality,
+            reward: None,
+            route: None,
+            context: Vec::new(),
+            weight: 1.0,
+            tags: Vec::new(),
+        }
+    }
+
+    /// Set activations
+    pub fn with_activations(mut self, activations: Vec<f32>) -> Self {
+        self.activations = Some(activations);
+        self
+    }
+
+    /// Set attention
+    pub fn with_attention(mut self, attention: Vec<f32>) -> Self {
+        self.attention = Some(attention);
+        self
+    }
+
+    /// Set reward
+    pub fn with_reward(mut self, reward: f32) -> Self {
+        self.reward = Some(reward);
+        self
+    }
+
+    /// Set route
+    pub fn with_route(mut self, route: impl Into<String>) -> Self {
+        self.route = Some(route.into());
+        self
+    }
+
+    /// Add context
+    pub fn with_context(mut self, ctx: impl Into<String>) -> Self {
+        self.context.push(ctx.into());
+        self
+    }
+
+    /// Set weight
+    pub fn with_weight(mut self, weight: f32) -> Self {
+        self.weight = weight;
+        self
+    }
+
+    /// Add tag
+    pub fn with_tag(mut self, tag: impl Into<String>) -> Self {
+        self.tags.push(tag.into());
+        self
+    }
+
+    /// Get activations or default to embedding
+    pub fn get_activations(&self) -> Vec<f32> {
+        self.activations
+            .clone()
+            .unwrap_or_else(|| self.embedding.clone())
+    }
+
+    /// Get attention or default
+    pub fn get_attention(&self) -> Vec<f32> {
+        self.attention
+            .clone()
+            .unwrap_or_else(|| vec![1.0 / 64.0; 64])
+    }
+
+    /// Get reward or default to quality
+    pub fn get_reward(&self) -> f32 {
+        self.reward.unwrap_or(self.quality)
+    }
+}
+
+/// Batch configuration for training
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct BatchConfig {
+    /// Batch size
+    pub batch_size: usize,
+    /// Shuffle examples
+    pub shuffle: bool,
+    /// Drop incomplete last batch
+    pub drop_last: bool,
+    /// Number of epochs
+    pub epochs: usize,
+    /// Early stopping patience (None = disabled)
+    pub early_stopping_patience: Option<usize>,
+    /// Minimum quality improvement for early stopping
+    pub min_quality_improvement: f32,
+}
+
+impl Default for BatchConfig {
+    fn default() -> Self {
+        Self {
+            batch_size: 32,
+            shuffle: true,
+            drop_last: false,
+            epochs: 1,
+            early_stopping_patience: None,
+            min_quality_improvement: 0.001,
+        }
+    }
+}
+
+impl BatchConfig {
+    /// Create config for single pass (no batching)
+    pub fn single_pass() -> Self {
+        Self {
+            batch_size: usize::MAX,
+            shuffle: false,
+            drop_last: false,
+            epochs: 1,
+            early_stopping_patience: None,
+            min_quality_improvement: 0.0,
+        }
+    }
+
+    /// Create config optimized for size hint
+    pub fn for_data_size(hint: &DataSizeHint) -> Self {
+        match hint {
+            DataSizeHint::Tiny => Self {
+                batch_size: 8,
+                epochs: 10,
+                early_stopping_patience: Some(3),
+                ..Default::default()
+            },
+            DataSizeHint::Small => Self {
+                batch_size: 16,
+                epochs: 5,
+                early_stopping_patience: Some(2),
+                ..Default::default()
+            },
+            DataSizeHint::Medium => Self {
+                batch_size: 32,
+                epochs: 3,
+                early_stopping_patience: Some(2),
+                ..Default::default()
+            },
+            DataSizeHint::Large => Self {
+                batch_size: 64,
+                epochs: 2,
+                ..Default::default()
+            },
+            DataSizeHint::Massive => Self {
+                batch_size: 128,
+                epochs: 1,
+                ..Default::default()
+            },
+        }
+    }
+}
+
+/// Pipeline stage for tracking progress
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PipelineStage {
+    /// Not started
+    Idle,
+    /// Loading and preprocessing data
+    Preprocessing,
+    /// Training in progress
+    Training,
+    /// Running validation
+    Validation,
+    /// Extracting patterns
+    PatternExtraction,
+    /// Exporting results
+    Export,
+    /// Completed successfully
+    Completed,
+    /// Failed with error
+    Failed,
+}
+
+impl std::fmt::Display for PipelineStage {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            PipelineStage::Idle => write!(f, "idle"),
+            PipelineStage::Preprocessing => write!(f, "preprocessing"),
+            PipelineStage::Training => write!(f, "training"),
+            PipelineStage::Validation => write!(f, "validation"),
+            PipelineStage::PatternExtraction => write!(f, "pattern_extraction"),
+            PipelineStage::Export => write!(f, "export"),
+            PipelineStage::Completed => write!(f, "completed"),
+            PipelineStage::Failed => write!(f, "failed"),
+        }
+    }
+}
+
+/// Callback trait for training events
+pub trait TrainingCallback: Send + Sync {
+    /// Called when stage changes
+    fn on_stage_change(&self, _stage: &PipelineStage) {}
+
+    /// Called after each batch
+    fn on_batch_complete(&self, _batch_idx: usize, _total_batches: usize, _avg_quality: f32) {}
+
+    /// Called after each epoch
+    fn on_epoch_complete(&self, _epoch: usize, _stats: &EpochStats) {}
+
+    /// Called when training completes
+    fn on_training_complete(&self, _result: &TrainingResult) {}
+
+    /// Called on error
+    fn on_error(&self, _error: &str) {}
+}
+
+/// No-op callback implementation
+pub struct NoOpCallback;
+impl TrainingCallback for NoOpCallback {}
+
+/// Logging callback implementation
+#[allow(dead_code)]
+pub struct LoggingCallback {
+    prefix: String,
+}
+
+#[allow(dead_code)]
+impl LoggingCallback {
+    /// Create with prefix
+    pub fn new(prefix: impl Into<String>) -> Self {
+        Self {
+            prefix: prefix.into(),
+        }
+    }
+}
+
+impl TrainingCallback for LoggingCallback {
+    fn on_stage_change(&self, stage: &PipelineStage) {
+        println!("[{}] Stage: {}", self.prefix, stage);
+    }
+
+    fn on_batch_complete(&self, batch_idx: usize, total_batches: usize, avg_quality: f32) {
+        if batch_idx % 10 == 0 || batch_idx == total_batches - 1 {
+            println!(
+                "[{}] Batch {}/{}: avg_quality={:.4}",
+                self.prefix,
+                batch_idx + 1,
+                total_batches,
+                avg_quality
+            );
+        }
+    }
+
+    fn on_epoch_complete(&self, epoch: usize, stats: &EpochStats) {
+        println!(
+            "[{}] Epoch {}: examples={}, avg_quality={:.4}, duration={:.2}s",
+            self.prefix,
+            epoch + 1,
+            stats.examples_processed,
+            stats.avg_quality,
+            stats.duration_secs
+        );
+    }
+
+    fn on_training_complete(&self, result: &TrainingResult) {
+        println!(
+            "[{}] Training complete: epochs={}, patterns={}, final_quality={:.4}",
+            self.prefix, result.epochs_completed, result.patterns_learned, result.final_avg_quality
+        );
+    }
+
+    fn on_error(&self, error: &str) {
+        eprintln!("[{}] ERROR: {}", self.prefix, error);
+    }
+}
+
+/// Training pipeline for structured training workflows
+pub struct TrainingPipeline {
+    /// Pipeline name
+    name: String,
+    /// SONA engine
+    engine: SonaEngine,
+    /// Batch configuration
+    batch_config: BatchConfig,
+    /// Training method
+    training_method: TrainingMethod,
+    /// Current stage
+    stage: PipelineStage,
+    /// Training examples buffer
+    examples: Vec<TrainingExample>,
+    /// Validation examples
+    validation_examples: Vec<TrainingExample>,
+    /// Training metrics
+    metrics: TrainingMetrics,
+    /// Callback
+    callback: Box<dyn TrainingCallback>,
+    /// Enable pattern extraction after training
+    extract_patterns: bool,
+}
+
+impl TrainingPipeline {
+    /// Create a new training pipeline
+    pub fn new(name: impl Into<String>, config: SonaConfig) -> Self {
+        let name = name.into();
+        Self {
+            name: name.clone(),
+            engine: SonaEngine::with_config(config),
+            batch_config: BatchConfig::default(),
+            training_method: TrainingMethod::default(),
+            stage: PipelineStage::Idle,
+            examples: Vec::new(),
+            validation_examples: Vec::new(),
+            metrics: TrainingMetrics::new(&name),
+            callback: Box::new(NoOpCallback),
+            extract_patterns: true,
+        }
+    }
+
+    /// Create from template
+    pub fn from_template(template: TrainingTemplate) -> Self {
+        let batch_config = BatchConfig::for_data_size(&template.expected_data_size);
+        let mut pipeline = Self::new(&template.name, template.sona_config);
+        pipeline.batch_config = batch_config;
+        pipeline.training_method = template.training_method;
+        pipeline
+    }
+
+    /// Set batch configuration
+    pub fn with_batch_config(mut self, config: BatchConfig) -> Self {
+        self.batch_config = config;
+        self
+    }
+
+    /// Set training method
+    pub fn with_training_method(mut self, method: TrainingMethod) -> Self {
+        self.training_method = method;
+        self
+    }
+
+    /// Set callback
+    pub fn with_callback<C: TrainingCallback + 'static>(mut self, callback: C) -> Self {
+        self.callback = Box::new(callback);
+        self
+    }
+
+    /// Enable/disable pattern extraction
+    pub fn with_pattern_extraction(mut self, enabled: bool) -> Self {
+        self.extract_patterns = enabled;
+        self
+    }
+
+    /// Add a training example
+    pub fn add_example(&mut self, example: TrainingExample) {
+        self.examples.push(example);
+    }
+
+    /// Add multiple training examples
+    pub fn add_examples(&mut self, examples: impl IntoIterator<Item = TrainingExample>) {
+        self.examples.extend(examples);
+    }
+
+    /// Add validation example
+    pub fn add_validation_example(&mut self, example: TrainingExample) {
+        self.validation_examples.push(example);
+    }
+
+    /// Get current stage
+    pub fn stage(&self) -> &PipelineStage {
+        &self.stage
+    }
+
+    /// Get number of examples
+    pub fn example_count(&self) -> usize {
+        self.examples.len()
+    }
+
+    /// Get metrics
+    pub fn metrics(&self) -> &TrainingMetrics {
+        &self.metrics
+    }
+
+    /// Get engine reference
+    pub fn engine(&self) -> &SonaEngine {
+        &self.engine
+    }
+
+    /// Get mutable engine reference
+    pub fn engine_mut(&mut self) -> &mut SonaEngine {
+        &mut self.engine
+    }
+
+    /// Run the training pipeline
+    pub fn train(&mut self) -> Result<TrainingResult, String> {
+        let start = Instant::now();
+
+        // Preprocessing
+        self.set_stage(PipelineStage::Preprocessing);
+        self.preprocess()?;
+
+        // Training
+        self.set_stage(PipelineStage::Training);
+        let epoch_stats = self.run_training()?;
+
+        // Validation (if examples provided)
+        if !self.validation_examples.is_empty() {
+            self.set_stage(PipelineStage::Validation);
+            self.run_validation()?;
+        }
+
+        // Pattern extraction
+        if self.extract_patterns {
+            self.set_stage(PipelineStage::PatternExtraction);
+            self.engine.force_learn();
+        }
+
+        self.set_stage(PipelineStage::Completed);
+
+        let result = TrainingResult {
+            pipeline_name: self.name.clone(),
+            epochs_completed: epoch_stats.len(),
+            total_examples: self.metrics.total_examples,
+            patterns_learned: self.metrics.patterns_learned,
+            final_avg_quality: self.metrics.avg_quality(),
+            total_duration_secs: start.elapsed().as_secs_f64(),
+            epoch_stats,
+            validation_quality: self.metrics.validation_quality,
+        };
+
+        self.callback.on_training_complete(&result);
+        Ok(result)
+    }
+
+    /// Set stage and notify callback
+    fn set_stage(&mut self, stage: PipelineStage) {
+        self.stage = stage.clone();
+        self.callback.on_stage_change(&stage);
+    }
+
+    /// Preprocess examples
+    fn preprocess(&mut self) -> Result<(), String> {
+        if self.examples.is_empty() {
+            return Err("No training examples provided".into());
+        }
+
+        // Shuffle if configured
+        if self.batch_config.shuffle {
+            use rand::seq::SliceRandom;
+            let mut rng = rand::thread_rng();
+            self.examples.shuffle(&mut rng);
+        }
+
+        Ok(())
+    }
+
+    /// Run training epochs
+    fn run_training(&mut self) -> Result<Vec<EpochStats>, String> {
+        let mut all_epoch_stats = Vec::new();
+        let mut best_quality = 0.0f32;
+        let mut patience_counter = 0usize;
+
+        for epoch in 0..self.batch_config.epochs {
+            let epoch_start = Instant::now();
+            let mut epoch_quality_sum = 0.0f32;
+            let mut epoch_examples = 0usize;
+
+            // Create batch indices (to avoid borrow checker issues)
+            let batch_size = self.batch_config.batch_size;
+            let total_examples = self.examples.len();
+            let mut batch_indices: Vec<(usize, usize)> = Vec::new();
+            let mut start = 0;
+            while start < total_examples {
+                let end = (start + batch_size).min(total_examples);
+                if end > start && (!self.batch_config.drop_last || end - start == batch_size) {
+                    batch_indices.push((start, end));
+                }
+                start = end;
+            }
+            let total_batches = batch_indices.len();
+
+            for (batch_idx, (start, end)) in batch_indices.into_iter().enumerate() {
+                let batch_quality = self.train_batch_range(start, end)?;
+                let batch_len = end - start;
+                epoch_quality_sum += batch_quality * batch_len as f32;
+                epoch_examples += batch_len;
+
+                self.callback.on_batch_complete(
+                    batch_idx,
+                    total_batches,
+                    epoch_quality_sum / epoch_examples as f32,
+                );
+            }
+
+            let epoch_avg_quality = if epoch_examples > 0 {
+                epoch_quality_sum / epoch_examples as f32
+            } else {
+                0.0
+            };
+
+            let epoch_stats = EpochStats {
+                epoch,
+                examples_processed: epoch_examples,
+                avg_quality: epoch_avg_quality,
+                duration_secs: epoch_start.elapsed().as_secs_f64(),
+            };
+
+            self.callback.on_epoch_complete(epoch, &epoch_stats);
+            all_epoch_stats.push(epoch_stats);
+
+            // Early stopping check
+            if let Some(patience) = self.batch_config.early_stopping_patience {
+                let improvement = epoch_avg_quality - best_quality;
+                if improvement > self.batch_config.min_quality_improvement {
+                    best_quality = epoch_avg_quality;
+                    patience_counter = 0;
+                } else {
+                    patience_counter += 1;
+                    if patience_counter >= patience {
+                        break; // Early stop
+                    }
+                }
+            }
+
+            // Reshuffle for next epoch
+            if self.batch_config.shuffle && epoch + 1 < self.batch_config.epochs {
+                use rand::seq::SliceRandom;
+                let mut rng = rand::thread_rng();
+                self.examples.shuffle(&mut rng);
+            }
+        }
+
+        Ok(all_epoch_stats)
+    }
+
+    /// Train on examples in a range
+    fn train_batch_range(&mut self, start: usize, end: usize) -> Result<f32, String> {
+        let mut quality_sum = 0.0f32;
+        let batch_len = end - start;
+
+        for idx in start..end {
+            let example = &self.examples[idx];
+
+            // Begin trajectory using builder API
+            let mut builder = self.engine.begin_trajectory(example.embedding.clone());
+
+            // Set route
+            if let Some(ref route) = example.route {
+                builder.set_model_route(route);
+            }
+
+            // Add context
+            for ctx in &example.context {
+                builder.add_context(ctx);
+            }
+
+            // Add step
+            builder.add_step(
+                example.get_activations(),
+                example.get_attention(),
+                example.get_reward() * example.weight,
+            );
+
+            // End trajectory
+            self.engine.end_trajectory(builder, example.quality);
+
+            quality_sum += example.quality;
+            self.metrics.total_examples += 1;
+            self.metrics.add_quality_sample(example.quality);
+        }
+
+        // Run tick to process accumulated trajectories
+        self.engine.tick();
+
+        Ok(quality_sum / batch_len as f32)
+    }
+
+    /// Run validation
+    fn run_validation(&mut self) -> Result<(), String> {
+        let mut quality_sum = 0.0f32;
+
+        for example in &self.validation_examples {
+            // Apply learned transformations
+            let mut output = vec![0.0f32; example.embedding.len()];
+            self.engine
+                .apply_micro_lora(&example.embedding, &mut output);
+
+            // In a real scenario, you'd evaluate the model output
+            // For now, we track the expected quality
+            quality_sum += example.quality;
+        }
+
+        self.metrics.validation_quality = Some(quality_sum / self.validation_examples.len() as f32);
+
+        Ok(())
+    }
+
+    /// Clear examples (keep engine state)
+    pub fn clear_examples(&mut self) {
+        self.examples.clear();
+        self.validation_examples.clear();
+    }
+
+    /// Reset pipeline (clear examples and metrics)
+    pub fn reset(&mut self) {
+        self.clear_examples();
+        self.metrics = TrainingMetrics::new(&self.name);
+        self.stage = PipelineStage::Idle;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_training_example() {
+        let example = TrainingExample::new(vec![0.1; 256], 0.8)
+            .with_route("test")
+            .with_context("ctx1")
+            .with_weight(1.5)
+            .with_tag("test");
+
+        assert_eq!(example.quality, 0.8);
+        assert_eq!(example.route, Some("test".into()));
+        assert_eq!(example.weight, 1.5);
+    }
+
+    #[test]
+    fn test_batch_config() {
+        let config = BatchConfig::for_data_size(&DataSizeHint::Small);
+        assert_eq!(config.batch_size, 16);
+        assert_eq!(config.epochs, 5);
+    }
+
+    #[test]
+    fn test_pipeline_creation() {
+        let pipeline = TrainingPipeline::new("test", SonaConfig::default());
+        assert_eq!(pipeline.stage(), &PipelineStage::Idle);
+        assert_eq!(pipeline.example_count(), 0);
+    }
+
+    #[test]
+    fn test_pipeline_from_template() {
+        let template = TrainingTemplate::code_agent().with_hidden_dim(256);
+        let pipeline = TrainingPipeline::from_template(template);
+        assert_eq!(pipeline.name, "code-agent");
+    }
+
+    #[test]
+    fn test_pipeline_training() {
+        let mut pipeline =
+            TrainingPipeline::new("test", SonaConfig::default()).with_batch_config(BatchConfig {
+                batch_size: 2,
+                epochs: 2,
+                ..Default::default()
+            });
+
+        // Add examples
+        for i in 0..5 {
+            pipeline.add_example(TrainingExample::new(
+                vec![i as f32 * 0.1; 256],
+                0.7 + i as f32 * 0.05,
+            ));
+        }
+
+        let result = pipeline.train().unwrap();
+        assert_eq!(result.epochs_completed, 2);
+        assert!(result.total_examples > 0);
+    }
+
+    #[test]
+    fn test_pipeline_with_validation() {
+        let mut pipeline = TrainingPipeline::new("test", SonaConfig::default())
+            .with_batch_config(BatchConfig::single_pass());
+
+        pipeline.add_example(TrainingExample::new(vec![0.1; 256], 0.8));
+        pipeline.add_validation_example(TrainingExample::new(vec![0.2; 256], 0.9));
+
+        let result = pipeline.train().unwrap();
+        assert!(result.validation_quality.is_some());
+    }
+}

vendor/ruvector/crates/sona/src/training/templates.rs

@@ -0,0 +1,656 @@
+//! Training Templates for SONA
+//!
+//! Pre-configured training setups optimized for different use cases.
+
+use crate::types::SonaConfig;
+use serde::{Deserialize, Serialize};
+
+/// Agent specialization types
+#[derive(Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum AgentType {
+    /// Code generation and assistance
+    CodeAgent,
+    /// General chat and conversation
+    ChatAgent,
+    /// Document retrieval and Q&A
+    RagAgent,
+    /// Task decomposition and planning
+    TaskPlanner,
+    /// Domain-specific expert
+    DomainExpert,
+    /// Codebase-aware assistant
+    CodebaseHelper,
+    /// Data analysis and insights
+    DataAnalyst,
+    /// Creative writing and content
+    CreativeWriter,
+    /// Reasoning and logic
+    ReasoningAgent,
+    /// Multi-modal understanding
+    MultiModal,
+    /// Custom agent type
+    Custom(String),
+}
+
+impl std::fmt::Display for AgentType {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            AgentType::CodeAgent => write!(f, "code-agent"),
+            AgentType::ChatAgent => write!(f, "chat-agent"),
+            AgentType::RagAgent => write!(f, "rag-agent"),
+            AgentType::TaskPlanner => write!(f, "task-planner"),
+            AgentType::DomainExpert => write!(f, "domain-expert"),
+            AgentType::CodebaseHelper => write!(f, "codebase-helper"),
+            AgentType::DataAnalyst => write!(f, "data-analyst"),
+            AgentType::CreativeWriter => write!(f, "creative-writer"),
+            AgentType::ReasoningAgent => write!(f, "reasoning-agent"),
+            AgentType::MultiModal => write!(f, "multi-modal"),
+            AgentType::Custom(name) => write!(f, "custom-{}", name),
+        }
+    }
+}
+
+/// Task domain for training focus
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum TaskDomain {
+    /// Software development
+    SoftwareDevelopment,
+    /// Customer support
+    CustomerSupport,
+    /// Healthcare
+    Healthcare,
+    /// Finance
+    Finance,
+    /// Legal
+    Legal,
+    /// Education
+    Education,
+    /// Research
+    Research,
+    /// Marketing
+    Marketing,
+    /// General purpose
+    General,
+    /// Custom domain
+    Custom(String),
+}
+
+/// Training method configuration
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum TrainingMethod {
+    /// Standard supervised learning
+    Supervised {
+        /// Batch size for training
+        batch_size: usize,
+        /// Number of epochs
+        epochs: usize,
+    },
+    /// Reinforcement learning from feedback
+    RLHF {
+        /// Reward model weight
+        reward_weight: f32,
+        /// KL divergence penalty
+        kl_penalty: f32,
+    },
+    /// Direct preference optimization
+    DPO {
+        /// Beta parameter for DPO
+        beta: f32,
+        /// Reference model weight
+        ref_weight: f32,
+    },
+    /// Continuous online learning
+    Online {
+        /// Learning rate decay
+        lr_decay: f32,
+        /// Window size for recent examples
+        window_size: usize,
+    },
+    /// Few-shot adaptation
+    FewShot {
+        /// Number of examples per class
+        k_shot: usize,
+        /// Meta-learning rate
+        meta_lr: f32,
+    },
+}
+
+impl Default for TrainingMethod {
+    fn default() -> Self {
+        TrainingMethod::Online {
+            lr_decay: 0.999,
+            window_size: 1000,
+        }
+    }
+}
+
+/// Vertical-specific configuration
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct VerticalConfig {
+    /// Domain focus
+    pub domain: TaskDomain,
+    /// Specialized vocabulary size
+    pub vocab_boost: usize,
+    /// Domain-specific quality metrics
+    pub quality_metrics: Vec<String>,
+    /// Compliance requirements
+    pub compliance_level: ComplianceLevel,
+}
+
+/// Compliance level for regulated industries
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub enum ComplianceLevel {
+    #[default]
+    None,
+    /// Basic audit logging
+    Basic,
+    /// HIPAA compliance
+    Hipaa,
+    /// SOC2 compliance
+    Soc2,
+    /// GDPR compliance
+    Gdpr,
+    /// Custom compliance
+    Custom(String),
+}
+
+/// Template preset for quick configuration
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub enum TemplatePreset {
+    /// Minimal configuration for testing
+    Minimal,
+    /// Balanced for general use
+    Balanced,
+    /// High performance for production
+    Production,
+    /// Maximum quality regardless of speed
+    MaxQuality,
+    /// Edge deployment (<5MB)
+    Edge,
+    /// Research and experimentation
+    Research,
+}
+
+/// Training template with full configuration
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TrainingTemplate {
+    /// Template name
+    pub name: String,
+    /// Agent type
+    pub agent_type: AgentType,
+    /// SONA configuration
+    pub sona_config: SonaConfig,
+    /// Training method
+    pub training_method: TrainingMethod,
+    /// Vertical configuration
+    pub vertical: Option<VerticalConfig>,
+    /// Expected training data size
+    pub expected_data_size: DataSizeHint,
+    /// Memory budget in MB
+    pub memory_budget_mb: usize,
+    /// Target latency in microseconds
+    pub target_latency_us: u64,
+    /// Enable continuous learning
+    pub continuous_learning: bool,
+    /// Auto-export trained adapters
+    pub auto_export: bool,
+    /// Tags for organization
+    pub tags: Vec<String>,
+}
+
+/// Hint about training data size
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub enum DataSizeHint {
+    /// <100 examples (few-shot)
+    Tiny,
+    /// 100-1000 examples
+    Small,
+    /// 1000-10000 examples
+    #[default]
+    Medium,
+    /// 10000-100000 examples
+    Large,
+    /// >100000 examples
+    Massive,
+}
+
+impl TrainingTemplate {
+    /// Create a new training template
+    pub fn new(name: impl Into<String>, agent_type: AgentType) -> Self {
+        Self {
+            name: name.into(),
+            agent_type,
+            sona_config: SonaConfig::default(),
+            training_method: TrainingMethod::default(),
+            vertical: None,
+            expected_data_size: DataSizeHint::default(),
+            memory_budget_mb: 100,
+            target_latency_us: 1000,
+            continuous_learning: true,
+            auto_export: false,
+            tags: Vec::new(),
+        }
+    }
+
+    /// Create from preset
+    pub fn from_preset(preset: TemplatePreset, agent_type: AgentType) -> Self {
+        let mut template = Self::new(format!("{:?}-{}", preset, agent_type), agent_type.clone());
+
+        match preset {
+            TemplatePreset::Minimal => {
+                template.sona_config = SonaConfig::edge_deployment();
+                template.memory_budget_mb = 10;
+                template.expected_data_size = DataSizeHint::Tiny;
+            }
+            TemplatePreset::Balanced => {
+                template.sona_config = SonaConfig::default();
+                template.memory_budget_mb = 100;
+            }
+            TemplatePreset::Production => {
+                template.sona_config = SonaConfig::max_throughput();
+                template.memory_budget_mb = 200;
+                template.auto_export = true;
+            }
+            TemplatePreset::MaxQuality => {
+                template.sona_config = SonaConfig::max_quality();
+                template.memory_budget_mb = 500;
+                template.expected_data_size = DataSizeHint::Large;
+            }
+            TemplatePreset::Edge => {
+                template.sona_config = SonaConfig::edge_deployment();
+                template.memory_budget_mb = 5;
+                template.target_latency_us = 500;
+            }
+            TemplatePreset::Research => {
+                template.sona_config = SonaConfig::max_quality();
+                template.sona_config.trajectory_capacity = 50000;
+                template.memory_budget_mb = 1000;
+                template.expected_data_size = DataSizeHint::Massive;
+            }
+        }
+
+        // Apply agent-specific optimizations
+        template.apply_agent_optimizations();
+        template
+    }
+
+    //------------------------------------------------------------------
+    // Pre-built Templates for Common Use Cases
+    //------------------------------------------------------------------
+
+    /// Code agent template - optimized for code generation
+    ///
+    /// **Best for**: Code completion, bug fixes, refactoring
+    /// **Config**: baseLoraRank=16, clusters=200, capacity=10000
+    /// **Training data**: Code completions, fixes, reviews
+    pub fn code_agent() -> Self {
+        let mut template = Self::new("code-agent", AgentType::CodeAgent);
+        template.sona_config.base_lora_rank = 16; // Deeper for code patterns
+        template.sona_config.pattern_clusters = 200; // Many code patterns
+        template.sona_config.trajectory_capacity = 10000;
+        template.sona_config.quality_threshold = 0.2; // Learn from most examples
+        template.training_method = TrainingMethod::Online {
+            lr_decay: 0.9995,
+            window_size: 5000,
+        };
+        template.tags = vec!["code".into(), "development".into(), "completion".into()];
+        template
+    }
+
+    /// Chat agent template - optimized for conversational AI
+    ///
+    /// **Best for**: Customer support, general chat, assistants
+    /// **Config**: baseLoraRank=8, clusters=50, fast response
+    /// **Training data**: Conversation histories, feedback
+    pub fn chat_agent() -> Self {
+        let mut template = Self::new("chat-agent", AgentType::ChatAgent);
+        template.sona_config.base_lora_rank = 8;
+        template.sona_config.pattern_clusters = 50;
+        template.sona_config.quality_threshold = 0.4;
+        template.target_latency_us = 500; // Fast responses
+        template.training_method = TrainingMethod::RLHF {
+            reward_weight: 0.5,
+            kl_penalty: 0.1,
+        };
+        template.tags = vec!["chat".into(), "conversation".into(), "support".into()];
+        template
+    }
+
+    /// RAG agent template - optimized for retrieval-augmented generation
+    ///
+    /// **Best for**: Document Q&A, knowledge bases, search
+    /// **Config**: clusters=200, capacity=10000, high pattern storage
+    /// **Training data**: Document chunks, Q&A pairs
+    pub fn rag_agent() -> Self {
+        let mut template = Self::new("rag-agent", AgentType::RagAgent);
+        template.sona_config.pattern_clusters = 200; // Many document patterns
+        template.sona_config.trajectory_capacity = 10000;
+        template.sona_config.embedding_dim = 512; // Larger embeddings for retrieval
+        template.sona_config.hidden_dim = 512;
+        template.training_method = TrainingMethod::Supervised {
+            batch_size: 32,
+            epochs: 10,
+        };
+        template.tags = vec!["rag".into(), "retrieval".into(), "documents".into()];
+        template
+    }
+
+    /// Task planner template - optimized for task decomposition
+    ///
+    /// **Best for**: Project planning, task breakdown, scheduling
+    /// **Config**: baseLoraRank=16, ewcLambda=2000, multi-task
+    /// **Training data**: Task decompositions, planning examples
+    pub fn task_planner() -> Self {
+        let mut template = Self::new("task-planner", AgentType::TaskPlanner);
+        template.sona_config.base_lora_rank = 16;
+        template.sona_config.ewc_lambda = 2000.0; // Important for multi-task
+        template.sona_config.pattern_clusters = 100;
+        template.training_method = TrainingMethod::DPO {
+            beta: 0.1,
+            ref_weight: 0.5,
+        };
+        template.tags = vec!["planning".into(), "tasks".into(), "decomposition".into()];
+        template
+    }
+
+    /// Domain expert template - optimized for specialized knowledge
+    ///
+    /// **Best for**: Legal, medical, financial expertise
+    /// **Config**: qualityThreshold=0.1, high capacity, compliance
+    /// **Training data**: Domain-specific Q&A, expert responses
+    pub fn domain_expert(domain: TaskDomain) -> Self {
+        let domain_name = format!("{:?}", domain).to_lowercase();
+        let mut template = Self::new(
+            format!("domain-expert-{}", domain_name),
+            AgentType::DomainExpert,
+        );
+        template.sona_config.quality_threshold = 0.1; // Learn from all domain examples
+        template.sona_config.trajectory_capacity = 20000;
+        template.sona_config.base_lora_rank = 16;
+        template.vertical = Some(VerticalConfig {
+            domain: domain.clone(),
+            vocab_boost: 10000,
+            quality_metrics: vec!["accuracy".into(), "relevance".into(), "compliance".into()],
+            compliance_level: match domain {
+                TaskDomain::Healthcare => ComplianceLevel::Hipaa,
+                TaskDomain::Finance => ComplianceLevel::Soc2,
+                TaskDomain::Legal => ComplianceLevel::Basic,
+                _ => ComplianceLevel::None,
+            },
+        });
+        template.tags = vec!["domain".into(), "expert".into(), domain_name];
+        template
+    }
+
+    /// Codebase helper template - learns your specific codebase
+    ///
+    /// **Best for**: Repository-specific assistance, code navigation
+    /// **Config**: clusters=200, capacity=10000, high pattern storage
+    /// **Training data**: Your repo's code, documentation
+    pub fn codebase_helper() -> Self {
+        let mut template = Self::new("codebase-helper", AgentType::CodebaseHelper);
+        template.sona_config.pattern_clusters = 200;
+        template.sona_config.trajectory_capacity = 10000;
+        template.sona_config.quality_threshold = 0.2;
+        template.sona_config.base_lora_rank = 16;
+        template.expected_data_size = DataSizeHint::Large;
+        template.training_method = TrainingMethod::Online {
+            lr_decay: 0.999,
+            window_size: 10000,
+        };
+        template.tags = vec!["codebase".into(), "repository".into(), "navigation".into()];
+        template
+    }
+
+    /// Data analyst template - optimized for data insights
+    ///
+    /// **Best for**: Data analysis, visualization, statistics
+    /// **Config**: baseLoraRank=8, clusters=100, reasoning focus
+    pub fn data_analyst() -> Self {
+        let mut template = Self::new("data-analyst", AgentType::DataAnalyst);
+        template.sona_config.base_lora_rank = 8;
+        template.sona_config.pattern_clusters = 100;
+        template.vertical = Some(VerticalConfig {
+            domain: TaskDomain::Research,
+            vocab_boost: 5000,
+            quality_metrics: vec!["accuracy".into(), "insight_quality".into()],
+            compliance_level: ComplianceLevel::None,
+        });
+        template.tags = vec!["data".into(), "analysis".into(), "insights".into()];
+        template
+    }
+
+    /// Creative writer template - optimized for content generation
+    ///
+    /// **Best for**: Marketing copy, blog posts, creative writing
+    /// **Config**: High diversity, quality focus
+    pub fn creative_writer() -> Self {
+        let mut template = Self::new("creative-writer", AgentType::CreativeWriter);
+        template.sona_config.base_lora_rank = 8;
+        template.sona_config.pattern_clusters = 50; // Fewer clusters for diversity
+        template.sona_config.quality_threshold = 0.5; // Only learn from high quality
+        template.training_method = TrainingMethod::RLHF {
+            reward_weight: 0.7,
+            kl_penalty: 0.05, // Less constraint for creativity
+        };
+        template.vertical = Some(VerticalConfig {
+            domain: TaskDomain::Marketing,
+            vocab_boost: 0,
+            quality_metrics: vec!["creativity".into(), "engagement".into(), "clarity".into()],
+            compliance_level: ComplianceLevel::None,
+        });
+        template.tags = vec!["creative".into(), "writing".into(), "content".into()];
+        template
+    }
+
+    /// Reasoning agent template - optimized for logical reasoning
+    ///
+    /// **Best for**: Math, logic, chain-of-thought reasoning
+    /// **Config**: High rank, strong EWC, accuracy focus
+    pub fn reasoning_agent() -> Self {
+        let mut template = Self::new("reasoning-agent", AgentType::ReasoningAgent);
+        template.sona_config.base_lora_rank = 16;
+        template.sona_config.ewc_lambda = 3000.0; // Strong protection
+        template.sona_config.pattern_clusters = 150;
+        template.sona_config.quality_threshold = 0.3;
+        template.training_method = TrainingMethod::DPO {
+            beta: 0.15,
+            ref_weight: 0.4,
+        };
+        template.tags = vec!["reasoning".into(), "logic".into(), "math".into()];
+        template
+    }
+
+    //------------------------------------------------------------------
+    // Builder Methods
+    //------------------------------------------------------------------
+
+    /// Set SONA configuration
+    pub fn with_sona_config(mut self, config: SonaConfig) -> Self {
+        self.sona_config = config;
+        self
+    }
+
+    /// Set training method
+    pub fn with_training_method(mut self, method: TrainingMethod) -> Self {
+        self.training_method = method;
+        self
+    }
+
+    /// Set vertical configuration
+    pub fn with_vertical(mut self, vertical: VerticalConfig) -> Self {
+        self.vertical = Some(vertical);
+        self
+    }
+
+    /// Set memory budget
+    pub fn with_memory_budget(mut self, mb: usize) -> Self {
+        self.memory_budget_mb = mb;
+        self
+    }
+
+    /// Set target latency
+    pub fn with_target_latency(mut self, us: u64) -> Self {
+        self.target_latency_us = us;
+        self
+    }
+
+    /// Enable continuous learning
+    pub fn with_continuous_learning(mut self, enabled: bool) -> Self {
+        self.continuous_learning = enabled;
+        self
+    }
+
+    /// Enable auto-export
+    pub fn with_auto_export(mut self, enabled: bool) -> Self {
+        self.auto_export = enabled;
+        self
+    }
+
+    /// Add tags
+    pub fn with_tags(mut self, tags: Vec<String>) -> Self {
+        self.tags = tags;
+        self
+    }
+
+    /// Set hidden dimension
+    pub fn with_hidden_dim(mut self, dim: usize) -> Self {
+        self.sona_config.hidden_dim = dim;
+        self.sona_config.embedding_dim = dim;
+        self
+    }
+
+    /// Set LoRA ranks
+    pub fn with_lora_ranks(mut self, micro: usize, base: usize) -> Self {
+        self.sona_config.micro_lora_rank = micro.min(2); // MicroLoRA max rank is 2
+        self.sona_config.base_lora_rank = base;
+        self
+    }
+
+    //------------------------------------------------------------------
+    // Internal Methods
+    //------------------------------------------------------------------
+
+    /// Apply agent-specific optimizations
+    fn apply_agent_optimizations(&mut self) {
+        match &self.agent_type {
+            AgentType::CodeAgent | AgentType::CodebaseHelper => {
+                self.sona_config.pattern_clusters = 200;
+                self.sona_config.base_lora_rank = 16;
+            }
+            AgentType::ChatAgent => {
+                self.sona_config.pattern_clusters = 50;
+                self.target_latency_us = 500;
+            }
+            AgentType::RagAgent => {
+                self.sona_config.pattern_clusters = 200;
+                self.sona_config.trajectory_capacity = 10000;
+            }
+            AgentType::ReasoningAgent => {
+                self.sona_config.ewc_lambda = 3000.0;
+                self.sona_config.base_lora_rank = 16;
+            }
+            AgentType::DomainExpert => {
+                self.sona_config.quality_threshold = 0.1;
+            }
+            _ => {}
+        }
+    }
+
+    /// Validate template configuration
+    pub fn validate(&self) -> Result<(), String> {
+        if self.sona_config.micro_lora_rank > 2 {
+            return Err("MicroLoRA rank must be 1 or 2".into());
+        }
+        if self.sona_config.hidden_dim == 0 {
+            return Err("Hidden dimension must be > 0".into());
+        }
+        if self.memory_budget_mb < 1 {
+            return Err("Memory budget must be >= 1 MB".into());
+        }
+        Ok(())
+    }
+
+    /// Get estimated memory usage in MB
+    pub fn estimated_memory_mb(&self) -> usize {
+        let config = &self.sona_config;
+
+        // Base engine memory
+        let engine_mb = 5;
+
+        // LoRA weights: hidden_dim * rank * 2 (A and B matrices) * 4 bytes * 2 (micro + base)
+        let lora_bytes =
+            config.hidden_dim * (config.micro_lora_rank + config.base_lora_rank) * 2 * 4 * 2;
+        let lora_mb = lora_bytes / (1024 * 1024);
+
+        // Trajectory buffer: capacity * ~800 bytes per trajectory
+        let traj_mb = (config.trajectory_capacity * 800) / (1024 * 1024);
+
+        // Pattern storage: clusters * embedding_dim * 4 bytes
+        let pattern_mb = (config.pattern_clusters * config.embedding_dim * 4) / (1024 * 1024);
+
+        engine_mb + lora_mb + traj_mb + pattern_mb + 1
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_template_creation() {
+        let template = TrainingTemplate::code_agent();
+        assert_eq!(template.agent_type, AgentType::CodeAgent);
+        assert_eq!(template.sona_config.base_lora_rank, 16);
+        assert_eq!(template.sona_config.pattern_clusters, 200);
+    }
+
+    #[test]
+    fn test_preset_templates() {
+        let production =
+            TrainingTemplate::from_preset(TemplatePreset::Production, AgentType::ChatAgent);
+        assert!(production.auto_export);
+
+        let edge = TrainingTemplate::from_preset(TemplatePreset::Edge, AgentType::ChatAgent);
+        assert_eq!(edge.memory_budget_mb, 5);
+    }
+
+    #[test]
+    fn test_domain_expert() {
+        let medical = TrainingTemplate::domain_expert(TaskDomain::Healthcare);
+        assert!(medical.vertical.is_some());
+        if let Some(v) = &medical.vertical {
+            assert!(matches!(v.compliance_level, ComplianceLevel::Hipaa));
+        }
+    }
+
+    #[test]
+    fn test_builder_pattern() {
+        let template = TrainingTemplate::new("custom", AgentType::Custom("test".into()))
+            .with_hidden_dim(512)
+            .with_lora_ranks(2, 16)
+            .with_memory_budget(200)
+            .with_continuous_learning(true);
+
+        assert_eq!(template.sona_config.hidden_dim, 512);
+        assert_eq!(template.sona_config.micro_lora_rank, 2);
+        assert_eq!(template.sona_config.base_lora_rank, 16);
+    }
+
+    #[test]
+    fn test_validation() {
+        let mut template = TrainingTemplate::code_agent();
+        assert!(template.validate().is_ok());
+
+        template.sona_config.micro_lora_rank = 5;
+        assert!(template.validate().is_err());
+    }
+
+    #[test]
+    fn test_memory_estimation() {
+        let template = TrainingTemplate::code_agent();
+        let mem = template.estimated_memory_mb();
+        assert!(mem > 0);
+        assert!(mem < template.memory_budget_mb * 2);
+    }
+}

vendor/ruvector/crates/sona/src/trajectory.rs

@@ -0,0 +1,362 @@
+//! Lock-free trajectory buffer for SONA
+//!
+//! Provides efficient, non-blocking trajectory recording during inference.
+
+use crate::time_compat::Instant;
+use crate::types::{QueryTrajectory, TrajectoryStep};
+use crossbeam::queue::ArrayQueue;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+/// Lock-free trajectory buffer using crossbeam ArrayQueue
+pub struct TrajectoryBuffer {
+    /// Internal queue
+    buffer: ArrayQueue<QueryTrajectory>,
+    /// Capacity
+    capacity: usize,
+    /// Count of dropped trajectories
+    dropped: AtomicU64,
+    /// Total trajectories seen
+    total_seen: AtomicU64,
+}
+
+impl TrajectoryBuffer {
+    /// Create new buffer with capacity
+    pub fn new(capacity: usize) -> Self {
+        Self {
+            buffer: ArrayQueue::new(capacity),
+            capacity,
+            dropped: AtomicU64::new(0),
+            total_seen: AtomicU64::new(0),
+        }
+    }
+
+    /// Record trajectory (non-blocking)
+    ///
+    /// Returns true if recorded, false if buffer full
+    pub fn record(&self, trajectory: QueryTrajectory) -> bool {
+        self.total_seen.fetch_add(1, Ordering::Relaxed);
+
+        match self.buffer.push(trajectory) {
+            Ok(()) => true,
+            Err(_) => {
+                self.dropped.fetch_add(1, Ordering::Relaxed);
+                false
+            }
+        }
+    }
+
+    /// Try to pop single trajectory
+    pub fn pop(&self) -> Option<QueryTrajectory> {
+        self.buffer.pop()
+    }
+
+    /// Drain all trajectories
+    pub fn drain(&self) -> Vec<QueryTrajectory> {
+        let mut result = Vec::with_capacity(self.len());
+        while let Some(t) = self.buffer.pop() {
+            result.push(t);
+        }
+        result
+    }
+
+    /// Drain up to n trajectories
+    pub fn drain_n(&self, n: usize) -> Vec<QueryTrajectory> {
+        let mut result = Vec::with_capacity(n.min(self.len()));
+        for _ in 0..n {
+            match self.buffer.pop() {
+                Some(t) => result.push(t),
+                None => break,
+            }
+        }
+        result
+    }
+
+    /// Get current length
+    pub fn len(&self) -> usize {
+        self.buffer.len()
+    }
+
+    /// Check if empty
+    pub fn is_empty(&self) -> bool {
+        self.buffer.is_empty()
+    }
+
+    /// Check if full
+    pub fn is_full(&self) -> bool {
+        self.buffer.is_full()
+    }
+
+    /// Get capacity
+    pub fn capacity(&self) -> usize {
+        self.capacity
+    }
+
+    /// Get dropped count
+    pub fn dropped_count(&self) -> u64 {
+        self.dropped.load(Ordering::Relaxed)
+    }
+
+    /// Get total seen count
+    pub fn total_seen(&self) -> u64 {
+        self.total_seen.load(Ordering::Relaxed)
+    }
+
+    /// Get success rate
+    pub fn success_rate(&self) -> f64 {
+        let total = self.total_seen.load(Ordering::Relaxed);
+        let dropped = self.dropped.load(Ordering::Relaxed);
+        if total == 0 {
+            1.0
+        } else {
+            (total - dropped) as f64 / total as f64
+        }
+    }
+
+    /// Reset statistics (not the buffer contents)
+    pub fn reset_stats(&self) {
+        self.dropped.store(0, Ordering::Relaxed);
+        self.total_seen.store(0, Ordering::Relaxed);
+    }
+}
+
+/// Builder for constructing trajectories during inference
+pub struct TrajectoryBuilder {
+    /// Trajectory ID
+    id: u64,
+    /// Query embedding
+    query_embedding: Vec<f32>,
+    /// Steps collected
+    steps: Vec<TrajectoryStep>,
+    /// Start time
+    start_time: Instant,
+    /// Model route
+    model_route: Option<String>,
+    /// Context IDs
+    context_ids: Vec<String>,
+}
+
+impl TrajectoryBuilder {
+    /// Start new trajectory
+    pub fn new(id: u64, query_embedding: Vec<f32>) -> Self {
+        Self {
+            id,
+            query_embedding,
+            steps: Vec::with_capacity(16),
+            start_time: Instant::now(),
+            model_route: None,
+            context_ids: Vec::new(),
+        }
+    }
+
+    /// Add execution step
+    pub fn add_step(&mut self, activations: Vec<f32>, attention_weights: Vec<f32>, reward: f32) {
+        let step_idx = self.steps.len();
+        self.steps.push(TrajectoryStep::new(
+            activations,
+            attention_weights,
+            reward,
+            step_idx,
+        ));
+    }
+
+    /// Add step with layer name
+    pub fn add_named_step(
+        &mut self,
+        name: &str,
+        activations: Vec<f32>,
+        attention_weights: Vec<f32>,
+        reward: f32,
+    ) {
+        let step_idx = self.steps.len();
+        self.steps.push(
+            TrajectoryStep::new(activations, attention_weights, reward, step_idx).with_layer(name),
+        );
+    }
+
+    /// Set model route
+    pub fn set_model_route(&mut self, route: &str) {
+        self.model_route = Some(route.to_string());
+    }
+
+    /// Add context ID
+    pub fn add_context(&mut self, context_id: &str) {
+        self.context_ids.push(context_id.to_string());
+    }
+
+    /// Get current step count
+    pub fn step_count(&self) -> usize {
+        self.steps.len()
+    }
+
+    /// Get elapsed time
+    pub fn elapsed(&self) -> std::time::Duration {
+        self.start_time.elapsed()
+    }
+
+    /// Finalize and build trajectory
+    pub fn build(self, final_quality: f32) -> QueryTrajectory {
+        let latency_us = self.start_time.elapsed().as_micros() as u64;
+
+        QueryTrajectory {
+            id: self.id,
+            query_embedding: self.query_embedding,
+            steps: self.steps,
+            final_quality,
+            latency_us,
+            model_route: self.model_route,
+            context_ids: self.context_ids,
+        }
+    }
+
+    /// Build with explicit latency
+    pub fn build_with_latency(self, final_quality: f32, latency_us: u64) -> QueryTrajectory {
+        QueryTrajectory {
+            id: self.id,
+            query_embedding: self.query_embedding,
+            steps: self.steps,
+            final_quality,
+            latency_us,
+            model_route: self.model_route,
+            context_ids: self.context_ids,
+        }
+    }
+}
+
+/// Trajectory ID generator
+pub struct TrajectoryIdGen {
+    counter: AtomicU64,
+}
+
+impl TrajectoryIdGen {
+    /// Create new generator
+    pub fn new() -> Self {
+        Self {
+            counter: AtomicU64::new(0),
+        }
+    }
+
+    /// Create with starting ID
+    pub fn with_start(start: u64) -> Self {
+        Self {
+            counter: AtomicU64::new(start),
+        }
+    }
+
+    /// Generate next ID
+    pub fn next(&self) -> u64 {
+        self.counter.fetch_add(1, Ordering::Relaxed)
+    }
+
+    /// Get current value without incrementing
+    pub fn current(&self) -> u64 {
+        self.counter.load(Ordering::Relaxed)
+    }
+}
+
+impl Default for TrajectoryIdGen {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_buffer_basic_ops() {
+        let buffer = TrajectoryBuffer::new(10);
+
+        assert!(buffer.is_empty());
+        assert_eq!(buffer.capacity(), 10);
+
+        let trajectory = QueryTrajectory::new(1, vec![0.1, 0.2]);
+        assert!(buffer.record(trajectory));
+
+        assert_eq!(buffer.len(), 1);
+        assert!(!buffer.is_empty());
+    }
+
+    #[test]
+    fn test_buffer_overflow() {
+        let buffer = TrajectoryBuffer::new(3);
+
+        for i in 0..5 {
+            let trajectory = QueryTrajectory::new(i, vec![0.1]);
+            buffer.record(trajectory);
+        }
+
+        assert_eq!(buffer.len(), 3);
+        assert_eq!(buffer.dropped_count(), 2);
+        assert_eq!(buffer.total_seen(), 5);
+    }
+
+    #[test]
+    fn test_buffer_drain() {
+        let buffer = TrajectoryBuffer::new(10);
+
+        for i in 0..5 {
+            let trajectory = QueryTrajectory::new(i, vec![0.1]);
+            buffer.record(trajectory);
+        }
+
+        let drained = buffer.drain();
+        assert_eq!(drained.len(), 5);
+        assert!(buffer.is_empty());
+    }
+
+    #[test]
+    fn test_buffer_drain_n() {
+        let buffer = TrajectoryBuffer::new(10);
+
+        for i in 0..5 {
+            let trajectory = QueryTrajectory::new(i, vec![0.1]);
+            buffer.record(trajectory);
+        }
+
+        let partial = buffer.drain_n(3);
+        assert_eq!(partial.len(), 3);
+        assert_eq!(buffer.len(), 2);
+    }
+
+    #[test]
+    fn test_builder() {
+        let mut builder = TrajectoryBuilder::new(42, vec![0.1, 0.2, 0.3]);
+
+        builder.add_step(vec![0.5], vec![0.4, 0.6], 0.7);
+        builder.add_step(vec![0.6], vec![0.3, 0.7], 0.8);
+        builder.set_model_route("llama-7b");
+        builder.add_context("ctx-123");
+
+        assert_eq!(builder.step_count(), 2);
+
+        let trajectory = builder.build(0.85);
+
+        assert_eq!(trajectory.id, 42);
+        assert_eq!(trajectory.steps.len(), 2);
+        assert_eq!(trajectory.final_quality, 0.85);
+        assert_eq!(trajectory.model_route, Some("llama-7b".to_string()));
+        assert!(trajectory.latency_us > 0);
+    }
+
+    #[test]
+    fn test_id_generator() {
+        let gen = TrajectoryIdGen::new();
+
+        assert_eq!(gen.next(), 0);
+        assert_eq!(gen.next(), 1);
+        assert_eq!(gen.next(), 2);
+        assert_eq!(gen.current(), 3);
+    }
+
+    #[test]
+    fn test_success_rate() {
+        let buffer = TrajectoryBuffer::new(2);
+
+        for i in 0..4 {
+            buffer.record(QueryTrajectory::new(i, vec![]));
+        }
+
+        assert!((buffer.success_rate() - 0.5).abs() < 1e-6);
+    }
+}

vendor/ruvector/crates/sona/src/types.rs

@@ -0,0 +1,584 @@
+//! SONA Core Types
+//!
+//! Defines the fundamental data structures for the Self-Optimizing Neural Architecture.
+
+use crate::time_compat::Instant;
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+/// Learning signal generated from inference trajectory
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct LearningSignal {
+    /// Query embedding vector
+    pub query_embedding: Vec<f32>,
+    /// Estimated gradient direction
+    pub gradient_estimate: Vec<f32>,
+    /// Quality score [0.0, 1.0]
+    pub quality_score: f32,
+    /// Signal generation timestamp (serialized as nanos)
+    #[serde(skip)]
+    pub timestamp: Option<Instant>,
+    /// Additional metadata
+    pub metadata: SignalMetadata,
+}
+
+/// Metadata for learning signals
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub struct SignalMetadata {
+    /// Source trajectory ID
+    pub trajectory_id: u64,
+    /// Number of steps in trajectory
+    pub step_count: usize,
+    /// Model route taken
+    pub model_route: Option<String>,
+    /// Custom tags
+    pub tags: HashMap<String, String>,
+}
+
+impl LearningSignal {
+    /// Create signal from query trajectory using REINFORCE gradient estimation
+    pub fn from_trajectory(trajectory: &QueryTrajectory) -> Self {
+        let gradient = Self::estimate_gradient(trajectory);
+
+        Self {
+            query_embedding: trajectory.query_embedding.clone(),
+            gradient_estimate: gradient,
+            quality_score: trajectory.final_quality,
+            timestamp: Some(Instant::now()),
+            metadata: SignalMetadata {
+                trajectory_id: trajectory.id,
+                step_count: trajectory.steps.len(),
+                model_route: trajectory.model_route.clone(),
+                tags: HashMap::new(),
+            },
+        }
+    }
+
+    /// Create signal with pre-computed gradient
+    pub fn with_gradient(embedding: Vec<f32>, gradient: Vec<f32>, quality: f32) -> Self {
+        Self {
+            query_embedding: embedding,
+            gradient_estimate: gradient,
+            quality_score: quality,
+            timestamp: Some(Instant::now()),
+            metadata: SignalMetadata::default(),
+        }
+    }
+
+    /// Estimate gradient using REINFORCE with baseline
+    fn estimate_gradient(trajectory: &QueryTrajectory) -> Vec<f32> {
+        if trajectory.steps.is_empty() {
+            return trajectory.query_embedding.clone();
+        }
+
+        let dim = trajectory.query_embedding.len();
+        let mut gradient = vec![0.0f32; dim];
+
+        // Compute baseline (average reward)
+        let baseline =
+            trajectory.steps.iter().map(|s| s.reward).sum::<f32>() / trajectory.steps.len() as f32;
+
+        // REINFORCE: gradient = sum((reward - baseline) * activation)
+        for step in &trajectory.steps {
+            let advantage = step.reward - baseline;
+            let activation_len = step.activations.len().min(dim);
+            for (grad, &act) in gradient
+                .iter_mut()
+                .zip(step.activations.iter())
+                .take(activation_len)
+            {
+                *grad += advantage * act;
+            }
+        }
+
+        // L2 normalize
+        let norm: f32 = gradient.iter().map(|x| x * x).sum::<f32>().sqrt();
+        if norm > 1e-8 {
+            gradient.iter_mut().for_each(|x| *x /= norm);
+        }
+
+        gradient
+    }
+
+    /// Scale gradient by quality
+    pub fn scaled_gradient(&self) -> Vec<f32> {
+        self.gradient_estimate
+            .iter()
+            .map(|&g| g * self.quality_score)
+            .collect()
+    }
+}
+
+/// Query trajectory recording
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct QueryTrajectory {
+    /// Unique trajectory identifier
+    pub id: u64,
+    /// Query embedding vector
+    pub query_embedding: Vec<f32>,
+    /// Execution steps
+    pub steps: Vec<TrajectoryStep>,
+    /// Final quality score [0.0, 1.0]
+    pub final_quality: f32,
+    /// Total latency in microseconds
+    pub latency_us: u64,
+    /// Model route taken
+    pub model_route: Option<String>,
+    /// Context used
+    pub context_ids: Vec<String>,
+}
+
+impl QueryTrajectory {
+    /// Create new trajectory
+    pub fn new(id: u64, query_embedding: Vec<f32>) -> Self {
+        Self {
+            id,
+            query_embedding,
+            steps: Vec::with_capacity(16),
+            final_quality: 0.0,
+            latency_us: 0,
+            model_route: None,
+            context_ids: Vec::new(),
+        }
+    }
+
+    /// Add execution step
+    pub fn add_step(&mut self, step: TrajectoryStep) {
+        self.steps.push(step);
+    }
+
+    /// Finalize trajectory with quality score
+    pub fn finalize(&mut self, quality: f32, latency_us: u64) {
+        self.final_quality = quality;
+        self.latency_us = latency_us;
+    }
+
+    /// Get total reward
+    pub fn total_reward(&self) -> f32 {
+        self.steps.iter().map(|s| s.reward).sum()
+    }
+
+    /// Get average reward
+    pub fn avg_reward(&self) -> f32 {
+        if self.steps.is_empty() {
+            0.0
+        } else {
+            self.total_reward() / self.steps.len() as f32
+        }
+    }
+}
+
+/// Single step in a trajectory
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct TrajectoryStep {
+    /// Layer/module activations (subset for efficiency)
+    pub activations: Vec<f32>,
+    /// Attention weights (flattened)
+    pub attention_weights: Vec<f32>,
+    /// Reward signal for this step
+    pub reward: f32,
+    /// Step index
+    pub step_idx: usize,
+    /// Optional layer name
+    pub layer_name: Option<String>,
+}
+
+impl TrajectoryStep {
+    /// Create new step
+    pub fn new(
+        activations: Vec<f32>,
+        attention_weights: Vec<f32>,
+        reward: f32,
+        step_idx: usize,
+    ) -> Self {
+        Self {
+            activations,
+            attention_weights,
+            reward,
+            step_idx,
+            layer_name: None,
+        }
+    }
+
+    /// Create step with layer name
+    pub fn with_layer(mut self, name: &str) -> Self {
+        self.layer_name = Some(name.to_string());
+        self
+    }
+}
+
+/// Learned pattern from trajectory clustering
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct LearnedPattern {
+    /// Pattern identifier
+    pub id: u64,
+    /// Cluster centroid embedding
+    pub centroid: Vec<f32>,
+    /// Number of trajectories in cluster
+    pub cluster_size: usize,
+    /// Sum of trajectory weights
+    pub total_weight: f32,
+    /// Average quality of member trajectories
+    pub avg_quality: f32,
+    /// Creation timestamp (Unix seconds)
+    pub created_at: u64,
+    /// Last access timestamp
+    pub last_accessed: u64,
+    /// Total access count
+    pub access_count: u32,
+    /// Pattern type/category
+    pub pattern_type: PatternType,
+}
+
+/// Pattern classification
+#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
+pub enum PatternType {
+    #[default]
+    General,
+    Reasoning,
+    Factual,
+    Creative,
+    CodeGen,
+    Conversational,
+}
+
+impl std::fmt::Display for PatternType {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            PatternType::General => write!(f, "general"),
+            PatternType::Reasoning => write!(f, "reasoning"),
+            PatternType::Factual => write!(f, "factual"),
+            PatternType::Creative => write!(f, "creative"),
+            PatternType::CodeGen => write!(f, "codegen"),
+            PatternType::Conversational => write!(f, "conversational"),
+        }
+    }
+}
+
+impl LearnedPattern {
+    /// Create new pattern
+    pub fn new(id: u64, centroid: Vec<f32>) -> Self {
+        use crate::time_compat::SystemTime;
+        let now = SystemTime::now().duration_since_epoch().as_secs();
+
+        Self {
+            id,
+            centroid,
+            cluster_size: 1,
+            total_weight: 1.0,
+            avg_quality: 0.0,
+            created_at: now,
+            last_accessed: now,
+            access_count: 0,
+            pattern_type: PatternType::default(),
+        }
+    }
+
+    /// Merge two patterns
+    pub fn merge(&self, other: &Self) -> Self {
+        let total_size = self.cluster_size + other.cluster_size;
+        let w1 = self.cluster_size as f32 / total_size as f32;
+        let w2 = other.cluster_size as f32 / total_size as f32;
+
+        let centroid: Vec<f32> = self
+            .centroid
+            .iter()
+            .zip(&other.centroid)
+            .map(|(&a, &b)| a * w1 + b * w2)
+            .collect();
+
+        Self {
+            id: self.id,
+            centroid,
+            cluster_size: total_size,
+            total_weight: self.total_weight + other.total_weight,
+            avg_quality: self.avg_quality * w1 + other.avg_quality * w2,
+            created_at: self.created_at.min(other.created_at),
+            last_accessed: self.last_accessed.max(other.last_accessed),
+            access_count: self.access_count + other.access_count,
+            pattern_type: self.pattern_type.clone(),
+        }
+    }
+
+    /// Decay pattern importance
+    pub fn decay(&mut self, factor: f32) {
+        self.total_weight *= factor;
+    }
+
+    /// Record access
+    pub fn touch(&mut self) {
+        use crate::time_compat::SystemTime;
+        self.access_count += 1;
+        self.last_accessed = SystemTime::now().duration_since_epoch().as_secs();
+    }
+
+    /// Check if pattern should be pruned
+    pub fn should_prune(&self, min_quality: f32, min_accesses: u32, max_age_secs: u64) -> bool {
+        use crate::time_compat::SystemTime;
+        let now = SystemTime::now().duration_since_epoch().as_secs();
+        let age = now.saturating_sub(self.last_accessed);
+
+        self.avg_quality < min_quality && self.access_count < min_accesses && age > max_age_secs
+    }
+
+    /// Compute cosine similarity with query
+    pub fn similarity(&self, query: &[f32]) -> f32 {
+        if self.centroid.len() != query.len() {
+            return 0.0;
+        }
+
+        let dot: f32 = self.centroid.iter().zip(query).map(|(a, b)| a * b).sum();
+        let norm_a: f32 = self.centroid.iter().map(|x| x * x).sum::<f32>().sqrt();
+        let norm_b: f32 = query.iter().map(|x| x * x).sum::<f32>().sqrt();
+
+        if norm_a > 1e-8 && norm_b > 1e-8 {
+            dot / (norm_a * norm_b)
+        } else {
+            0.0
+        }
+    }
+}
+
+/// SONA configuration
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct SonaConfig {
+    /// Hidden dimension
+    pub hidden_dim: usize,
+    /// Embedding dimension
+    pub embedding_dim: usize,
+    /// Micro-LoRA rank
+    pub micro_lora_rank: usize,
+    /// Base LoRA rank
+    pub base_lora_rank: usize,
+    /// Micro-LoRA learning rate
+    pub micro_lora_lr: f32,
+    /// Base LoRA learning rate
+    pub base_lora_lr: f32,
+    /// EWC lambda
+    pub ewc_lambda: f32,
+    /// Pattern extraction clusters
+    pub pattern_clusters: usize,
+    /// Trajectory buffer capacity
+    pub trajectory_capacity: usize,
+    /// Background learning interval (ms)
+    pub background_interval_ms: u64,
+    /// Quality threshold for learning
+    pub quality_threshold: f32,
+    /// Enable SIMD optimizations
+    pub enable_simd: bool,
+}
+
+impl Default for SonaConfig {
+    fn default() -> Self {
+        // OPTIMIZED DEFAULTS based on @ruvector/sona v0.1.1 benchmarks:
+        // - Rank-2 is 5% faster than Rank-1 due to better SIMD vectorization
+        // - Learning rate 0.002 yields +55% quality improvement
+        // - 100 clusters = 1.3ms search vs 50 clusters = 3.0ms (2.3x faster)
+        // - EWC lambda 2000 optimal for catastrophic forgetting prevention
+        // - Quality threshold 0.3 balances learning vs noise filtering
+        Self {
+            hidden_dim: 256,
+            embedding_dim: 256,
+            micro_lora_rank: 2, // OPTIMIZED: Rank-2 faster than Rank-1 (2,211 vs 2,100 ops/sec)
+            base_lora_rank: 8,  // Balanced for production
+            micro_lora_lr: 0.002, // OPTIMIZED: +55.3% quality improvement
+            base_lora_lr: 0.0001,
+            ewc_lambda: 2000.0,    // OPTIMIZED: Better forgetting prevention
+            pattern_clusters: 100, // OPTIMIZED: 2.3x faster search (1.3ms vs 3.0ms)
+            trajectory_capacity: 10000,
+            background_interval_ms: 3600000, // 1 hour
+            quality_threshold: 0.3,          // OPTIMIZED: Lower threshold for more learning
+            enable_simd: true,
+        }
+    }
+}
+
+impl SonaConfig {
+    /// Create config optimized for maximum throughput (real-time chat)
+    pub fn max_throughput() -> Self {
+        Self {
+            hidden_dim: 256,
+            embedding_dim: 256,
+            micro_lora_rank: 2,    // Rank-2 + SIMD = 2,211 ops/sec
+            base_lora_rank: 4,     // Minimal base for speed
+            micro_lora_lr: 0.0005, // Conservative for stability
+            base_lora_lr: 0.0001,
+            ewc_lambda: 2000.0,
+            pattern_clusters: 100,
+            trajectory_capacity: 5000,
+            background_interval_ms: 7200000, // 2 hours
+            quality_threshold: 0.4,
+            enable_simd: true,
+        }
+    }
+
+    /// Create config optimized for maximum quality (research/batch)
+    pub fn max_quality() -> Self {
+        Self {
+            hidden_dim: 256,
+            embedding_dim: 256,
+            micro_lora_rank: 2,
+            base_lora_rank: 16,   // Higher rank for expressiveness
+            micro_lora_lr: 0.002, // Optimal learning rate
+            base_lora_lr: 0.001,  // Aggressive base learning
+            ewc_lambda: 2000.0,
+            pattern_clusters: 100,
+            trajectory_capacity: 20000,
+            background_interval_ms: 1800000, // 30 minutes
+            quality_threshold: 0.2,          // Learn from more trajectories
+            enable_simd: true,
+        }
+    }
+
+    /// Create config for edge/mobile deployment (<5MB memory)
+    pub fn edge_deployment() -> Self {
+        Self {
+            hidden_dim: 256,
+            embedding_dim: 256,
+            micro_lora_rank: 1, // Minimal rank for memory
+            base_lora_rank: 4,
+            micro_lora_lr: 0.001,
+            base_lora_lr: 0.0001,
+            ewc_lambda: 1000.0,
+            pattern_clusters: 50,
+            trajectory_capacity: 200, // Small buffer
+            background_interval_ms: 3600000,
+            quality_threshold: 0.5,
+            enable_simd: true,
+        }
+    }
+
+    /// Create config for batch processing (50+ inferences/sec)
+    pub fn batch_processing() -> Self {
+        Self {
+            hidden_dim: 256,
+            embedding_dim: 256,
+            micro_lora_rank: 2,
+            base_lora_rank: 8,
+            micro_lora_lr: 0.001,
+            base_lora_lr: 0.0001,
+            ewc_lambda: 2000.0,
+            pattern_clusters: 100,
+            trajectory_capacity: 10000,
+            background_interval_ms: 3600000,
+            quality_threshold: 0.3,
+            enable_simd: true,
+        }
+    }
+
+    /// Create config for ephemeral agents (~5MB footprint)
+    ///
+    /// Optimized for lightweight federated learning nodes that collect
+    /// trajectories locally before aggregation.
+    pub fn for_ephemeral() -> Self {
+        Self {
+            hidden_dim: 256,
+            embedding_dim: 256,
+            micro_lora_rank: 2,
+            base_lora_rank: 4, // Small base for memory efficiency
+            micro_lora_lr: 0.002,
+            base_lora_lr: 0.0001,
+            ewc_lambda: 1000.0,
+            pattern_clusters: 50,          // Fewer clusters for memory
+            trajectory_capacity: 500,      // Local buffer before aggregation
+            background_interval_ms: 60000, // 1 minute for quick local updates
+            quality_threshold: 0.3,
+            enable_simd: true,
+        }
+    }
+
+    /// Create config for federated coordinator (central aggregation)
+    ///
+    /// Optimized for aggregating trajectories from multiple ephemeral agents
+    /// with larger capacity and pattern storage.
+    pub fn for_coordinator() -> Self {
+        Self {
+            hidden_dim: 256,
+            embedding_dim: 256,
+            micro_lora_rank: 2,
+            base_lora_rank: 16,             // Higher rank for aggregated learning
+            micro_lora_lr: 0.001,           // Conservative for stability
+            base_lora_lr: 0.0005,           // Moderate base learning
+            ewc_lambda: 2000.0,             // Strong forgetting prevention
+            pattern_clusters: 200,          // More clusters for diverse patterns
+            trajectory_capacity: 50000,     // Large capacity for aggregation
+            background_interval_ms: 300000, // 5 minutes consolidation
+            quality_threshold: 0.4,         // Higher threshold for quality filtering
+            enable_simd: true,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_learning_signal_from_trajectory() {
+        let mut trajectory = QueryTrajectory::new(1, vec![0.1, 0.2, 0.3]);
+        trajectory.add_step(TrajectoryStep::new(
+            vec![0.5, 0.3, 0.2],
+            vec![0.4, 0.4, 0.2],
+            0.8,
+            0,
+        ));
+        trajectory.finalize(0.8, 1000);
+
+        let signal = LearningSignal::from_trajectory(&trajectory);
+        assert_eq!(signal.quality_score, 0.8);
+        assert_eq!(signal.gradient_estimate.len(), 3);
+        assert_eq!(signal.metadata.trajectory_id, 1);
+    }
+
+    #[test]
+    fn test_pattern_merge() {
+        let p1 = LearnedPattern {
+            id: 1,
+            centroid: vec![1.0, 0.0],
+            cluster_size: 10,
+            total_weight: 5.0,
+            avg_quality: 0.8,
+            created_at: 100,
+            last_accessed: 200,
+            access_count: 5,
+            pattern_type: PatternType::General,
+        };
+
+        let p2 = LearnedPattern {
+            id: 2,
+            centroid: vec![0.0, 1.0],
+            cluster_size: 10,
+            total_weight: 5.0,
+            avg_quality: 0.9,
+            created_at: 150,
+            last_accessed: 250,
+            access_count: 3,
+            pattern_type: PatternType::General,
+        };
+
+        let merged = p1.merge(&p2);
+        assert_eq!(merged.cluster_size, 20);
+        assert!((merged.centroid[0] - 0.5).abs() < 1e-6);
+        assert!((merged.centroid[1] - 0.5).abs() < 1e-6);
+        assert!((merged.avg_quality - 0.85).abs() < 1e-6);
+    }
+
+    #[test]
+    fn test_pattern_similarity() {
+        let pattern = LearnedPattern::new(1, vec![1.0, 0.0, 0.0]);
+
+        assert!((pattern.similarity(&[1.0, 0.0, 0.0]) - 1.0).abs() < 1e-6);
+        assert!(pattern.similarity(&[0.0, 1.0, 0.0]).abs() < 1e-6);
+    }
+
+    #[test]
+    fn test_trajectory_rewards() {
+        let mut trajectory = QueryTrajectory::new(1, vec![0.1]);
+        trajectory.add_step(TrajectoryStep::new(vec![], vec![], 0.5, 0));
+        trajectory.add_step(TrajectoryStep::new(vec![], vec![], 0.7, 1));
+        trajectory.add_step(TrajectoryStep::new(vec![], vec![], 0.9, 2));
+
+        assert!((trajectory.total_reward() - 2.1).abs() < 1e-6);
+        assert!((trajectory.avg_reward() - 0.7).abs() < 1e-6);
+    }
+}

vendor/ruvector/crates/sona/src/wasm.rs

@@ -0,0 +1,718 @@
+//! WASM bindings for SONA
+//!
+//! Enable with feature flag: `wasm`
+//!
+//! ## Usage in JavaScript
+//!
+//! ```javascript
+//! import init, { WasmSonaEngine } from './pkg/sona.js';
+//!
+//! async function main() {
+//!   await init();
+//!
+//!   const engine = new WasmSonaEngine(256); // hidden_dim = 256
+//!
+//!   // Start trajectory
+//!   const embedding = new Float32Array(256).fill(0.1);
+//!   const trajectoryId = engine.start_trajectory(embedding);
+//!
+//!   // Record steps
+//!   engine.record_step(trajectoryId, 42, 0.8, 1000);
+//!
+//!   // End trajectory
+//!   engine.end_trajectory(trajectoryId, 0.85);
+//!
+//!   // Apply LoRA
+//!   const input = new Float32Array(256).fill(1.0);
+//!   const output = engine.apply_lora(input);
+//!
+//!   console.log('Transformed output:', output);
+//! }
+//! ```
+
+#![cfg(feature = "wasm")]
+
+use crate::{LearningSignal, SonaConfig, SonaEngine};
+use parking_lot::RwLock;
+use std::sync::Arc;
+use wasm_bindgen::prelude::*;
+
+/// WASM-compatible SONA Engine wrapper
+///
+/// Provides JavaScript bindings for the SONA adaptive learning system.
+#[wasm_bindgen]
+pub struct WasmSonaEngine {
+    inner: Arc<RwLock<SonaEngine>>,
+}
+
+#[wasm_bindgen]
+impl WasmSonaEngine {
+    /// Create a new SONA engine with specified hidden dimension
+    ///
+    /// # Arguments
+    /// * `hidden_dim` - Size of hidden layer (typically 256, 512, or 1024)
+    ///
+    /// # Example
+    /// ```javascript
+    /// const engine = new WasmSonaEngine(256);
+    /// ```
+    #[wasm_bindgen(constructor)]
+    pub fn new(hidden_dim: usize) -> Result<WasmSonaEngine, JsValue> {
+        #[cfg(feature = "console_error_panic_hook")]
+        console_error_panic_hook::set_once();
+
+        Ok(Self {
+            inner: Arc::new(RwLock::new(SonaEngine::new(hidden_dim))),
+        })
+    }
+
+    /// Create engine with custom configuration
+    ///
+    /// # Arguments
+    /// * `config` - JSON configuration object
+    ///
+    /// # Example
+    /// ```javascript
+    /// const config = {
+    ///   hidden_dim: 256,
+    ///   embedding_dim: 256,
+    ///   micro_lora_rank: 2,
+    ///   base_lora_rank: 16,
+    ///   micro_lora_lr: 0.001,
+    ///   base_lora_lr: 0.0001,
+    ///   ewc_lambda: 1000.0,
+    ///   pattern_clusters: 128,
+    ///   trajectory_capacity: 10000,
+    ///   quality_threshold: 0.6
+    /// };
+    /// const engine = WasmSonaEngine.with_config(config);
+    /// ```
+    #[wasm_bindgen(js_name = withConfig)]
+    pub fn with_config(config: JsValue) -> Result<WasmSonaEngine, JsValue> {
+        #[cfg(feature = "console_error_panic_hook")]
+        console_error_panic_hook::set_once();
+
+        let config: SonaConfig = serde_wasm_bindgen::from_value(config)?;
+
+        Ok(Self {
+            inner: Arc::new(RwLock::new(SonaEngine::with_config(config))),
+        })
+    }
+
+    /// Start recording a new trajectory
+    ///
+    /// # Arguments
+    /// * `query_embedding` - Query vector as Float32Array
+    ///
+    /// # Returns
+    /// Trajectory ID (u64)
+    ///
+    /// # Example
+    /// ```javascript
+    /// const embedding = new Float32Array(256).fill(0.1);
+    /// const trajectoryId = engine.start_trajectory(embedding);
+    /// ```
+    #[wasm_bindgen(js_name = startTrajectory)]
+    pub fn start_trajectory(&self, query_embedding: Vec<f32>) -> u64 {
+        let engine = self.inner.read();
+        let builder = engine.begin_trajectory(query_embedding);
+        // Return simple counter ID since builder.id is private
+        use std::sync::atomic::{AtomicU64, Ordering};
+        static NEXT_ID: AtomicU64 = AtomicU64::new(1);
+        NEXT_ID.fetch_add(1, Ordering::Relaxed)
+    }
+
+    /// Record a step in the trajectory
+    ///
+    /// # Arguments
+    /// * `trajectory_id` - ID returned from start_trajectory
+    /// * `node_id` - Graph node visited
+    /// * `score` - Step quality score [0.0, 1.0]
+    /// * `latency_us` - Step latency in microseconds
+    ///
+    /// # Example
+    /// ```javascript
+    /// engine.record_step(trajectoryId, 42, 0.8, 1000);
+    /// ```
+    #[wasm_bindgen(js_name = recordStep)]
+    pub fn record_step(&self, trajectory_id: u64, node_id: u32, score: f32, latency_us: u64) {
+        // Note: This is a simplified version. In production, you'd want to maintain
+        // a map of active trajectory builders
+        web_sys::console::log_1(
+            &format!(
+                "Recording step: traj={}, node={}, score={}, latency={}us",
+                trajectory_id, node_id, score, latency_us
+            )
+            .into(),
+        );
+    }
+
+    /// End the trajectory and submit for learning
+    ///
+    /// # Arguments
+    /// * `trajectory_id` - ID returned from start_trajectory
+    /// * `final_score` - Overall trajectory quality [0.0, 1.0]
+    ///
+    /// # Example
+    /// ```javascript
+    /// engine.end_trajectory(trajectoryId, 0.85);
+    /// ```
+    #[wasm_bindgen(js_name = endTrajectory)]
+    pub fn end_trajectory(&self, trajectory_id: u64, final_score: f32) {
+        web_sys::console::log_1(
+            &format!(
+                "Ending trajectory: traj={}, score={}",
+                trajectory_id, final_score
+            )
+            .into(),
+        );
+    }
+
+    /// Apply learning from user feedback
+    ///
+    /// # Arguments
+    /// * `success` - Whether the operation succeeded
+    /// * `latency_ms` - Operation latency in milliseconds
+    /// * `quality` - User-perceived quality [0.0, 1.0]
+    ///
+    /// # Example
+    /// ```javascript
+    /// engine.learn_from_feedback(true, 50.0, 0.9);
+    /// ```
+    #[wasm_bindgen(js_name = learnFromFeedback)]
+    pub fn learn_from_feedback(&self, success: bool, latency_ms: f32, quality: f32) {
+        let reward = if success { quality } else { -quality };
+        web_sys::console::log_1(
+            &format!(
+                "Feedback: success={}, latency={}ms, quality={}, reward={}",
+                success, latency_ms, quality, reward
+            )
+            .into(),
+        );
+    }
+
+    /// Apply LoRA transformation to input vector
+    ///
+    /// # Arguments
+    /// * `input` - Input vector as Float32Array
+    ///
+    /// # Returns
+    /// Transformed vector as Float32Array
+    ///
+    /// # Example
+    /// ```javascript
+    /// const input = new Float32Array(256).fill(1.0);
+    /// const output = engine.apply_lora(input);
+    /// ```
+    #[wasm_bindgen(js_name = applyLora)]
+    pub fn apply_lora(&self, input: Vec<f32>) -> Vec<f32> {
+        let mut output = vec![0.0; input.len()];
+        let engine = self.inner.read();
+        engine.apply_micro_lora(&input, &mut output);
+        output
+    }
+
+    /// Apply LoRA transformation to specific layer
+    ///
+    /// # Arguments
+    /// * `layer_idx` - Layer index
+    /// * `input` - Input vector as Float32Array
+    ///
+    /// # Returns
+    /// Transformed vector as Float32Array
+    #[wasm_bindgen(js_name = applyLoraLayer)]
+    pub fn apply_lora_layer(&self, layer_idx: usize, input: Vec<f32>) -> Vec<f32> {
+        let mut output = vec![0.0; input.len()];
+        let engine = self.inner.read();
+        engine.apply_base_lora(layer_idx, &input, &mut output);
+        output
+    }
+
+    /// Run instant learning cycle
+    ///
+    /// Flushes accumulated micro-LoRA updates
+    ///
+    /// # Example
+    /// ```javascript
+    /// engine.run_instant_cycle();
+    /// ```
+    #[wasm_bindgen(js_name = runInstantCycle)]
+    pub fn run_instant_cycle(&self) {
+        let engine = self.inner.read();
+        engine.flush();
+    }
+
+    /// Try to run background learning cycle
+    ///
+    /// Returns true if cycle was executed, false if not due yet
+    ///
+    /// # Example
+    /// ```javascript
+    /// if (engine.tick()) {
+    ///   console.log('Background learning completed');
+    /// }
+    /// ```
+    #[wasm_bindgen]
+    pub fn tick(&self) -> bool {
+        let engine = self.inner.read();
+        engine.tick().is_some()
+    }
+
+    /// Force background learning cycle
+    ///
+    /// # Returns
+    /// Learning statistics as JSON string
+    ///
+    /// # Example
+    /// ```javascript
+    /// const stats = engine.force_learn();
+    /// console.log('Learning results:', stats);
+    /// ```
+    #[wasm_bindgen(js_name = forceLearn)]
+    pub fn force_learn(&self) -> String {
+        let engine = self.inner.read();
+        engine.force_learn()
+    }
+
+    /// Get engine statistics
+    ///
+    /// # Returns
+    /// Statistics as JSON object
+    ///
+    /// # Example
+    /// ```javascript
+    /// const stats = engine.get_stats();
+    /// console.log('Trajectories buffered:', stats.trajectories_buffered);
+    /// console.log('Patterns learned:', stats.patterns_learned);
+    /// ```
+    #[wasm_bindgen(js_name = getStats)]
+    pub fn get_stats(&self) -> JsValue {
+        let engine = self.inner.read();
+        let stats = engine.stats();
+        serde_wasm_bindgen::to_value(&stats).unwrap_or(JsValue::NULL)
+    }
+
+    /// Enable or disable the engine
+    ///
+    /// # Arguments
+    /// * `enabled` - Whether to enable the engine
+    ///
+    /// # Example
+    /// ```javascript
+    /// engine.set_enabled(false); // Pause learning
+    /// ```
+    #[wasm_bindgen(js_name = setEnabled)]
+    pub fn set_enabled(&self, enabled: bool) {
+        let mut engine = self.inner.write();
+        engine.set_enabled(enabled);
+    }
+
+    /// Check if engine is enabled
+    ///
+    /// # Returns
+    /// true if enabled, false otherwise
+    #[wasm_bindgen(js_name = isEnabled)]
+    pub fn is_enabled(&self) -> bool {
+        let engine = self.inner.read();
+        engine.is_enabled()
+    }
+
+    /// Get configuration
+    ///
+    /// # Returns
+    /// Configuration as JSON object
+    #[wasm_bindgen(js_name = getConfig)]
+    pub fn get_config(&self) -> JsValue {
+        let engine = self.inner.read();
+        let config = engine.config();
+        serde_wasm_bindgen::to_value(config).unwrap_or(JsValue::NULL)
+    }
+
+    /// Find similar patterns to query
+    ///
+    /// # Arguments
+    /// * `query_embedding` - Query vector as Float32Array
+    /// * `k` - Number of patterns to return
+    ///
+    /// # Returns
+    /// Array of similar patterns as JSON
+    ///
+    /// # Example
+    /// ```javascript
+    /// const query = new Float32Array(256).fill(0.5);
+    /// const patterns = engine.find_patterns(query, 5);
+    /// console.log('Similar patterns:', patterns);
+    /// ```
+    #[wasm_bindgen(js_name = findPatterns)]
+    pub fn find_patterns(&self, query_embedding: Vec<f32>, k: usize) -> JsValue {
+        let engine = self.inner.read();
+        let patterns = engine.find_patterns(&query_embedding, k);
+        serde_wasm_bindgen::to_value(&patterns).unwrap_or(JsValue::NULL)
+    }
+}
+
+/// Initialize WASM module (called automatically)
+#[wasm_bindgen(start)]
+pub fn wasm_init() {
+    #[cfg(feature = "console_error_panic_hook")]
+    console_error_panic_hook::set_once();
+
+    web_sys::console::log_1(&"SONA WASM module initialized".into());
+}
+
+// ============================================================================
+// Federated Learning WASM Bindings
+// ============================================================================
+
+use crate::training::{
+    EphemeralAgent as RustEphemeralAgent, FederatedCoordinator as RustFederatedCoordinator,
+    FederatedTopology,
+};
+
+/// WASM-compatible Ephemeral Agent for federated learning
+///
+/// Lightweight agent wrapper (~5MB footprint) for distributed training.
+/// Agents process tasks, collect trajectories, and export state for aggregation.
+///
+/// # Example
+/// ```javascript
+/// const agent = new WasmEphemeralAgent("agent-1");
+///
+/// // Process tasks
+/// const embedding = new Float32Array(256).fill(0.1);
+/// agent.process_task(embedding, 0.85);
+///
+/// // Export state for coordinator
+/// const state = agent.export_state();
+/// ```
+#[wasm_bindgen]
+pub struct WasmEphemeralAgent {
+    inner: RustEphemeralAgent,
+}
+
+#[wasm_bindgen]
+impl WasmEphemeralAgent {
+    /// Create a new ephemeral agent with default config
+    ///
+    /// # Arguments
+    /// * `agent_id` - Unique identifier for this agent
+    ///
+    /// # Example
+    /// ```javascript
+    /// const agent = new WasmEphemeralAgent("agent-1");
+    /// ```
+    #[wasm_bindgen(constructor)]
+    pub fn new(agent_id: &str) -> Result<WasmEphemeralAgent, JsValue> {
+        let config = SonaConfig::for_ephemeral();
+        Ok(Self {
+            inner: RustEphemeralAgent::new(agent_id, config),
+        })
+    }
+
+    /// Create agent with custom configuration
+    ///
+    /// # Arguments
+    /// * `agent_id` - Unique identifier
+    /// * `config` - JSON configuration object
+    ///
+    /// # Example
+    /// ```javascript
+    /// const config = {
+    ///   hidden_dim: 256,
+    ///   trajectory_capacity: 500,
+    ///   pattern_clusters: 25
+    /// };
+    /// const agent = WasmEphemeralAgent.with_config("agent-1", config);
+    /// ```
+    #[wasm_bindgen(js_name = withConfig)]
+    pub fn with_config(agent_id: &str, config: JsValue) -> Result<WasmEphemeralAgent, JsValue> {
+        let config: SonaConfig = serde_wasm_bindgen::from_value(config)?;
+        Ok(Self {
+            inner: RustEphemeralAgent::new(agent_id, config),
+        })
+    }
+
+    /// Process a task and record trajectory
+    ///
+    /// # Arguments
+    /// * `embedding` - Query embedding as Float32Array
+    /// * `quality` - Task quality score [0.0, 1.0]
+    ///
+    /// # Example
+    /// ```javascript
+    /// const embedding = new Float32Array(256).fill(0.1);
+    /// agent.process_task(embedding, 0.85);
+    /// ```
+    #[wasm_bindgen(js_name = processTask)]
+    pub fn process_task(&mut self, embedding: Vec<f32>, quality: f32) {
+        self.inner.process_task(embedding, quality);
+    }
+
+    /// Process task with model route information
+    ///
+    /// # Arguments
+    /// * `embedding` - Query embedding
+    /// * `quality` - Quality score
+    /// * `route` - Model route used (e.g., "gpt-4", "claude-3")
+    #[wasm_bindgen(js_name = processTaskWithRoute)]
+    pub fn process_task_with_route(&mut self, embedding: Vec<f32>, quality: f32, route: &str) {
+        self.inner
+            .process_task_with_route(embedding, quality, route);
+    }
+
+    /// Export agent state for coordinator aggregation
+    ///
+    /// # Returns
+    /// JSON object containing agent state, trajectories, and statistics
+    ///
+    /// # Example
+    /// ```javascript
+    /// const state = agent.export_state();
+    /// console.log('Trajectories:', state.trajectories.length);
+    /// coordinator.aggregate(state);
+    /// ```
+    #[wasm_bindgen(js_name = exportState)]
+    pub fn export_state(&self) -> JsValue {
+        let export = self.inner.export_state();
+        serde_wasm_bindgen::to_value(&export).unwrap_or(JsValue::NULL)
+    }
+
+    /// Get agent statistics
+    ///
+    /// # Returns
+    /// JSON object with trajectory count, quality stats, uptime
+    #[wasm_bindgen(js_name = getStats)]
+    pub fn get_stats(&self) -> JsValue {
+        let stats = self.inner.stats();
+        serde_wasm_bindgen::to_value(&stats).unwrap_or(JsValue::NULL)
+    }
+
+    /// Get number of collected trajectories
+    #[wasm_bindgen(js_name = trajectoryCount)]
+    pub fn trajectory_count(&self) -> usize {
+        self.inner.trajectory_count()
+    }
+
+    /// Get average quality of collected trajectories
+    #[wasm_bindgen(js_name = averageQuality)]
+    pub fn average_quality(&self) -> f32 {
+        self.inner.average_quality()
+    }
+
+    /// Get agent uptime in seconds
+    #[wasm_bindgen(js_name = uptimeSeconds)]
+    pub fn uptime_seconds(&self) -> u64 {
+        self.inner.uptime_seconds()
+    }
+
+    /// Clear collected trajectories (after export)
+    #[wasm_bindgen]
+    pub fn clear(&mut self) {
+        self.inner.clear();
+    }
+
+    /// Force learning cycle on agent's engine
+    #[wasm_bindgen(js_name = forceLearn)]
+    pub fn force_learn(&self) -> String {
+        self.inner.force_learn()
+    }
+
+    /// Get learned patterns from agent
+    #[wasm_bindgen(js_name = getPatterns)]
+    pub fn get_patterns(&self) -> JsValue {
+        let patterns = self.inner.get_patterns();
+        serde_wasm_bindgen::to_value(&patterns).unwrap_or(JsValue::NULL)
+    }
+}
+
+/// WASM-compatible Federated Coordinator
+///
+/// Central aggregator for federated learning with quality filtering.
+/// Coordinates multiple ephemeral agents using star topology.
+///
+/// # Example
+/// ```javascript
+/// const coordinator = new WasmFederatedCoordinator("central");
+///
+/// // Aggregate agent exports
+/// const agentState = agent.export_state();
+/// const result = coordinator.aggregate(agentState);
+///
+/// // Check stats
+/// const stats = coordinator.get_stats();
+/// console.log('Total agents:', stats.total_agents);
+/// ```
+#[wasm_bindgen]
+pub struct WasmFederatedCoordinator {
+    inner: RustFederatedCoordinator,
+}
+
+#[wasm_bindgen]
+impl WasmFederatedCoordinator {
+    /// Create a new federated coordinator with default config
+    ///
+    /// # Arguments
+    /// * `coordinator_id` - Unique identifier for this coordinator
+    ///
+    /// # Example
+    /// ```javascript
+    /// const coordinator = new WasmFederatedCoordinator("central");
+    /// ```
+    #[wasm_bindgen(constructor)]
+    pub fn new(coordinator_id: &str) -> Result<WasmFederatedCoordinator, JsValue> {
+        let config = SonaConfig::for_coordinator();
+        Ok(Self {
+            inner: RustFederatedCoordinator::new(coordinator_id, config),
+        })
+    }
+
+    /// Create coordinator with custom configuration
+    ///
+    /// # Arguments
+    /// * `coordinator_id` - Unique identifier
+    /// * `config` - JSON configuration object
+    ///
+    /// # Example
+    /// ```javascript
+    /// const config = {
+    ///   hidden_dim: 256,
+    ///   trajectory_capacity: 50000,
+    ///   pattern_clusters: 200,
+    ///   ewc_lambda: 2000.0
+    /// };
+    /// const coordinator = WasmFederatedCoordinator.with_config("central", config);
+    /// ```
+    #[wasm_bindgen(js_name = withConfig)]
+    pub fn with_config(
+        coordinator_id: &str,
+        config: JsValue,
+    ) -> Result<WasmFederatedCoordinator, JsValue> {
+        let config: SonaConfig = serde_wasm_bindgen::from_value(config)?;
+        Ok(Self {
+            inner: RustFederatedCoordinator::new(coordinator_id, config),
+        })
+    }
+
+    /// Set quality threshold for accepting trajectories
+    ///
+    /// # Arguments
+    /// * `threshold` - Minimum quality [0.0, 1.0], default 0.4
+    #[wasm_bindgen(js_name = setQualityThreshold)]
+    pub fn set_quality_threshold(&mut self, threshold: f32) {
+        self.inner.set_quality_threshold(threshold);
+    }
+
+    /// Aggregate agent export into coordinator
+    ///
+    /// # Arguments
+    /// * `agent_export` - JSON export from agent.export_state()
+    ///
+    /// # Returns
+    /// JSON aggregation result with accepted/rejected counts
+    ///
+    /// # Example
+    /// ```javascript
+    /// const agentState = agent.export_state();
+    /// const result = coordinator.aggregate(agentState);
+    /// console.log('Accepted:', result.accepted);
+    /// ```
+    #[wasm_bindgen]
+    pub fn aggregate(&mut self, agent_export: JsValue) -> JsValue {
+        use crate::training::AgentExport;
+
+        match serde_wasm_bindgen::from_value::<AgentExport>(agent_export) {
+            Ok(export) => {
+                let result = self.inner.aggregate(export);
+                serde_wasm_bindgen::to_value(&result).unwrap_or(JsValue::NULL)
+            }
+            Err(e) => {
+                web_sys::console::error_1(&format!("Failed to parse agent export: {:?}", e).into());
+                JsValue::NULL
+            }
+        }
+    }
+
+    /// Consolidate learning from all aggregated trajectories
+    ///
+    /// Should be called periodically after aggregating multiple agents.
+    ///
+    /// # Returns
+    /// Learning result as JSON string
+    #[wasm_bindgen]
+    pub fn consolidate(&self) -> String {
+        self.inner.consolidate()
+    }
+
+    /// Get coordinator statistics
+    ///
+    /// # Returns
+    /// JSON object with agent count, trajectory count, quality stats
+    #[wasm_bindgen(js_name = getStats)]
+    pub fn get_stats(&self) -> JsValue {
+        let stats = self.inner.stats();
+        serde_wasm_bindgen::to_value(&stats).unwrap_or(JsValue::NULL)
+    }
+
+    /// Get total number of contributing agents
+    #[wasm_bindgen(js_name = agentCount)]
+    pub fn agent_count(&self) -> usize {
+        self.inner.agent_count()
+    }
+
+    /// Get total trajectories aggregated
+    #[wasm_bindgen(js_name = totalTrajectories)]
+    pub fn total_trajectories(&self) -> usize {
+        self.inner.total_trajectories()
+    }
+
+    /// Get all learned patterns from coordinator
+    #[wasm_bindgen(js_name = getPatterns)]
+    pub fn get_patterns(&self) -> JsValue {
+        let patterns = self.inner.get_all_patterns();
+        serde_wasm_bindgen::to_value(&patterns).unwrap_or(JsValue::NULL)
+    }
+
+    /// Find similar patterns to query
+    ///
+    /// # Arguments
+    /// * `query_embedding` - Query vector
+    /// * `k` - Number of patterns to return
+    #[wasm_bindgen(js_name = findPatterns)]
+    pub fn find_patterns(&self, query_embedding: Vec<f32>, k: usize) -> JsValue {
+        let patterns = self.inner.find_patterns(&query_embedding, k);
+        serde_wasm_bindgen::to_value(&patterns).unwrap_or(JsValue::NULL)
+    }
+
+    /// Apply coordinator's learned LoRA to input
+    #[wasm_bindgen(js_name = applyLora)]
+    pub fn apply_lora(&self, input: Vec<f32>) -> Vec<f32> {
+        self.inner.apply_lora(&input)
+    }
+
+    /// Clear all agent contributions (reset coordinator)
+    #[wasm_bindgen]
+    pub fn clear(&mut self) {
+        self.inner.clear();
+    }
+}
+
+// Additional helper for serde support
+#[cfg(feature = "wasm")]
+mod serde_wasm_bindgen {
+    use super::*;
+    use serde::Serialize;
+
+    pub fn to_value<T: Serialize>(value: &T) -> Result<JsValue, JsValue> {
+        serde_json::to_string(value)
+            .map(|s| JsValue::from_str(&s))
+            .map_err(|e| JsValue::from_str(&e.to_string()))
+    }
+
+    pub fn from_value<T: serde::de::DeserializeOwned>(value: JsValue) -> Result<T, JsValue> {
+        if let Some(s) = value.as_string() {
+            serde_json::from_str(&s).map_err(|e| JsValue::from_str(&e.to_string()))
+        } else {
+            Err(JsValue::from_str("Expected JSON string"))
+        }
+    }
+}