fix: Address code review issues from gist analysis

## Fixes Applied

### 1. Fabricated Benchmarks
- Rewrote docs/benchmarks/BENCHMARK_COMPARISON.md - removed false "100-4,400x faster" claims
- Fixed benchmarks/graph/src/comparison-runner.ts - removed hardcoded latency multipliers
- Fixed benchmarks/src/results-analyzer.ts - removed simulated histogram data

### 2. Fake Text Embeddings
- Added prominent warnings to agenticdb.rs about hash-based placeholder
- Added compile-time deprecation warning in lib.rs
- Created integration guide with 4 real embedding options (ONNX, Candle, API, Python)

### 3. Incomplete GNN Training
- Implemented Loss::compute() for MSE, CrossEntropy, BinaryCrossEntropy
- Implemented Loss::gradient() for backpropagation
- Added 6 new verification tests

### 4. Distance Function Bugs
- Fixed inverted dequantization formula in ruvector-router-core (was /scale, now *scale)
- Improved scale handling in ruvector-core quantization (now uses average scale)

### 5. Empty Transaction Tests
- Implemented 10+ critical tests: dirty reads, phantom reads, MVCC, deadlock detection
- All 31 transaction tests now passing

Addresses issues from: https://gist.github.com/couzic/93126a1c12b8d77651f93a7805b4bd60

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ruvnet

benchmarks/graph/src/comparison-runner.ts

@@ -96,8 +96,8 @@ async function runNeo4jBenchmarks(scenario: string): Promise<BenchmarkMetrics[]>
         memory_mb: 0, // Would need Neo4j metrics API
         cpu_percent: 0,
         latency_p50: duration,
-        latency_p95: duration * 1.2,
-        latency_p99: duration * 1.5
+        latency_p95: 0, // Cannot accurately estimate without percentile data
+        latency_p99: 0  // Cannot accurately estimate without percentile data
       });
     }
 
@@ -203,8 +203,8 @@ function parseCriterionOutput(output: string, system: 'ruvector' | 'neo4j', scen
           memory_mb: 0,
           cpu_percent: 0,
           latency_p50: p50,
-          latency_p95: p50 * 1.2,
-          latency_p99: p50 * 1.5
+          latency_p95: 0, // Would need to parse from criterion percentile output
+          latency_p99: 0  // Would need to parse from criterion percentile output
         });
       }
     }
@@ -224,23 +224,12 @@ function loadBaselineMetrics(system: string, scenario: string): BenchmarkMetrics
     return JSON.parse(data);
   }
 
-  // Return estimated baseline if no data available
-  console.warn(`No baseline data for ${system} ${scenario}, using estimates`);
-
-  return [
-    {
-      system: system as 'ruvector' | 'neo4j',
-      scenario,
-      operation: 'node_insertion',
-      duration_ms: 100,
-      throughput_ops: 10000,
-      memory_mb: 512,
-      cpu_percent: 50,
-      latency_p50: 100,
-      latency_p95: 150,
-      latency_p99: 200
-    }
-  ];
+  // Error: no baseline data available
+  throw new Error(
+    `No baseline data available for ${system} ${scenario}. ` +
+    `Cannot run comparison without actual measured data. ` +
+    `Please run benchmarks on both systems first and save results to ${baselinePath}`
+  );
 }
 
 /**

benchmarks/src/results-analyzer.ts

@@ -172,33 +172,17 @@ export class ResultsAnalyzer {
 
   // Create latency histogram
   private createLatencyHistogram(latency: LatencyMetrics): HistogramBucket[] {
-    const buckets: HistogramBucket[] = [
-      { min: 0, max: 10, count: 0, percentage: 0 },
-      { min: 10, max: 25, count: 0, percentage: 0 },
-      { min: 25, max: 50, count: 0, percentage: 0 },
-      { min: 50, max: 100, count: 0, percentage: 0 },
-      { min: 100, max: 200, count: 0, percentage: 0 },
-      { min: 200, max: 500, count: 0, percentage: 0 },
-      { min: 500, max: Infinity, count: 0, percentage: 0 },
-    ];
-
-    // Estimate distribution based on percentiles
-    // This is a rough approximation - ideally we'd have raw data
-    const total = 1000000; // Assume 1M samples
-
-    buckets[0].count = Math.floor(total * 0.5); // 50% under 10ms
-    buckets[1].count = Math.floor(total * 0.25); // 25% 10-25ms
-    buckets[2].count = Math.floor(total * 0.15); // 15% 25-50ms
-    buckets[3].count = Math.floor(total * 0.08); // 8% 50-100ms
-    buckets[4].count = Math.floor(total * 0.015); // 1.5% 100-200ms
-    buckets[5].count = Math.floor(total * 0.004); // 0.4% 200-500ms
-    buckets[6].count = Math.floor(total * 0.001); // 0.1% 500ms+
-
-    buckets.forEach(bucket => {
-      bucket.percentage = (bucket.count / total) * 100;
-    });
-
-    return buckets;
+    // NOTE: This function cannot create accurate histograms without raw latency samples.
+    // We only have percentile data (p50, p95, p99), which is insufficient for distribution.
+    // Returning empty histogram to avoid fabricating data.
+
+    console.warn(
+      'Cannot generate latency histogram without raw sample data. ' +
+      'Only percentile metrics (p50, p95, p99) are available. ' +
+      'To get accurate histograms, modify metrics collection to store raw latency samples.'
+    );
+
+    return []; // Return empty array instead of fabricated data
   }
 
   // Detect anomalies

crates/ruvector-core/src/agenticdb.rs

@@ -1,5 +1,22 @@
 //! AgenticDB API Compatibility Layer
 //!
+//! # ⚠️ CRITICAL WARNING: PLACEHOLDER EMBEDDINGS
+//!
+//! **THIS MODULE USES HASH-BASED PLACEHOLDER EMBEDDINGS - NOT REAL SEMANTIC EMBEDDINGS**
+//!
+//! The `generate_text_embedding()` function creates embeddings using a simple hash function
+//! that does NOT understand semantic meaning. Similarity is based on character overlap, NOT meaning.
+//!
+//! **For Production Use:**
+//! - Integrate a real embedding model (sentence-transformers, OpenAI, Anthropic, Cohere)
+//! - Use ONNX Runtime, candle, or Python bindings for inference
+//! - See `/examples/onnx-embeddings` for a production-ready integration example
+//!
+//! **What This Means:**
+//! - "dog" and "cat" will NOT be similar (different characters)
+//! - "dog" and "god" WILL be similar (same characters, different order)
+//! - Semantic search will not work as expected
+//!
 //! Provides a drop-in replacement for agenticDB with 5-table schema:
 //! - vectors_table: Core embeddings + metadata
 //! - reflexion_episodes: Self-critique memories
@@ -658,20 +675,68 @@ impl AgenticDB {
 
     /// Generate text embedding from text.
     ///
-    /// # ⚠️ WARNING: PLACEHOLDER IMPLEMENTATION
+    /// # ⚠️⚠️⚠️ CRITICAL WARNING: THIS IS A PLACEHOLDER - NOT REAL EMBEDDINGS ⚠️⚠️⚠️
+    ///
+    /// **THIS FUNCTION DOES NOT CREATE SEMANTIC EMBEDDINGS!**
+    ///
+    /// This uses a simple hash-based embedding that does NOT understand semantic meaning.
+    /// Text similarity will be based on character overlap, NOT actual meaning.
+    ///
+    /// ## Why This Exists
+    /// This placeholder allows the AgenticDB API to work for testing and demonstration,
+    /// but it will NOT provide meaningful semantic search results.
+    ///
+    /// ## Examples of What Won't Work
+    /// - "dog" and "cat" will NOT be similar (different characters)
+    /// - "happy" and "joyful" will NOT be similar (different characters)
+    /// - "car" and "automobile" will NOT be similar (different characters)
+    /// - But "dog" and "god" WILL be similar (same characters, different order) ❌
+    ///
+    /// ## For Production Use - Choose ONE:
+    ///
+    /// ### Option 1: ONNX Runtime (Recommended)
+    /// ```rust
+    /// // See /examples/onnx-embeddings for complete example
+    /// use ort::{Session, Environment, Value};
+    /// let session = Session::builder()?
+    ///     .with_model_from_file("all-MiniLM-L6-v2.onnx")?;
+    /// ```
+    ///
+    /// ### Option 2: Candle (Pure Rust)
+    /// ```rust
+    /// use candle_core::{Device, Tensor};
+    /// use candle_transformers::models::bert;
+    /// ```
+    ///
+    /// ### Option 3: API-based (OpenAI, Cohere, Anthropic)
+    /// ```rust
+    /// use reqwest;
+    /// let response = client.post("https://api.openai.com/v1/embeddings")
+    ///     .json(&json!({ "model": "text-embedding-3-small", "input": text }))
+    ///     .send().await?;
+    /// ```
     ///
-    /// This uses a simple hash-based embedding that does NOT understand
-    /// semantic meaning. Text similarity will be based on character overlap,
-    /// not actual meaning.
+    /// ### Option 4: Python Bindings
+    /// ```rust
+    /// use pyo3::prelude::*;
+    /// let embeddings = Python::with_gil(|py| {
+    ///     let sentence_transformers = py.import("sentence_transformers")?;
+    ///     let model = sentence_transformers.getattr("SentenceTransformer")?
+    ///         .call1(("all-MiniLM-L6-v2",))?;
+    ///     model.call_method1("encode", (text,))
+    /// });
+    /// ```
     ///
-    /// For real semantic search, integrate an actual embedding model:
-    /// - `sentence-transformers` via Python bindings
-    /// - `candle` for native Rust inference
-    /// - ONNX Runtime for cross-platform models
-    /// - OpenAI/Anthropic embedding APIs
+    /// ## Replace This Function
+    /// To use real embeddings, replace this entire function implementation with
+    /// one of the above options. The function signature should remain the same.
     fn generate_text_embedding(&self, text: &str) -> Result<Vec<f32>> {
-        // ⚠️ PLACEHOLDER: Hash-based embedding - NOT semantic
-        // This is for demonstration and testing only
+        // ⚠️⚠️⚠️ PLACEHOLDER IMPLEMENTATION - NOT SEMANTIC EMBEDDINGS ⚠️⚠️⚠️
+        //
+        // This is a hash-based embedding for demonstration and testing ONLY.
+        // DO NOT use in production for semantic search!
+        //
+        // This will be replaced with a compile-time warning in future versions.
         let mut embedding = vec![0.0; self.dimensions];
         let bytes = text.as_bytes();
 

crates/ruvector-core/src/lib.rs

@@ -10,10 +10,14 @@
 //! - **Persistence**: REDB-based storage with config persistence
 //! - **Search**: ~2.5K queries/sec on 10K vectors (benchmarked)
 //!
-//! ## Experimental/Incomplete Features
+//! ## ⚠️ Experimental/Incomplete Features - READ BEFORE USE
 //!
-//! - **AgenticDB**: Uses placeholder hash-based embeddings (NOT semantic)
-//!   - Replace `generate_text_embedding` with real model for production use
+//! - **AgenticDB**: ⚠️⚠️⚠️ **CRITICAL WARNING** ⚠️⚠️⚠️
+//!   - Uses PLACEHOLDER hash-based embeddings, NOT real semantic embeddings
+//!   - "dog" and "cat" will NOT be similar (different characters)
+//!   - "dog" and "god" WILL be similar (same characters) - **This is wrong!**
+//!   - **MUST integrate real embedding model for production** (ONNX, Candle, or API)
+//!   - See [`agenticdb`] module docs and `/examples/onnx-embeddings` for integration
 //! - **Advanced Features**: Conformal prediction, hybrid search - functional but less tested
 //!
 //! ## What This Is NOT
@@ -67,6 +71,18 @@ pub use advanced_features::{
 #[cfg(feature = "storage")]
 pub use agenticdb::AgenticDB;
 
+// Compile-time warning about AgenticDB limitations
+#[cfg(feature = "storage")]
+const _: () = {
+    // This will appear in cargo build output as a note
+    #[deprecated(
+        since = "0.1.0",
+        note = "AgenticDB uses placeholder hash-based embeddings. For semantic search, integrate a real embedding model (ONNX, Candle, or API). See /examples/onnx-embeddings for production setup."
+    )]
+    const AGENTICDB_EMBEDDING_WARNING: () = ();
+    let _ = AGENTICDB_EMBEDDING_WARNING;
+};
+
 pub use error::{Result, RuvectorError};
 pub use types::{DistanceMetric, SearchQuery, SearchResult, VectorEntry, VectorId};
 pub use vector_db::VectorDB;

crates/ruvector-core/src/quantization.rs

@@ -49,6 +49,13 @@ impl QuantizedVector for ScalarQuantized {
     fn distance(&self, other: &Self) -> f32 {
         // Fast int8 distance calculation
         // Use i32 to avoid overflow: max diff is 255, and 255*255=65025 fits in i32
+
+        // Scale handling: We use the average of both scales for balanced comparison.
+        // Using max(scale) would bias toward the vector with larger range,
+        // while average provides a more symmetric distance metric.
+        // This ensures distance(a, b) ≈ distance(b, a) in the reconstructed space.
+        let avg_scale = (self.scale + other.scale) / 2.0;
+
         self.data
             .iter()
             .zip(&other.data)
@@ -58,7 +65,7 @@ impl QuantizedVector for ScalarQuantized {
             })
             .sum::<f32>()
             .sqrt()
-            * self.scale.max(other.scale)
+            * avg_scale
     }
 
     fn reconstruct(&self) -> Vec<f32> {
@@ -307,4 +314,117 @@ mod tests {
         let dist = q1.distance(&q2);
         assert_eq!(dist, 2.0); // 2 bits differ
     }
+
+    #[test]
+    fn test_scalar_quantization_roundtrip() {
+        // Test that quantize -> reconstruct produces values close to original
+        let test_vectors = vec![
+            vec![1.0, 2.0, 3.0, 4.0, 5.0],
+            vec![-10.0, -5.0, 0.0, 5.0, 10.0],
+            vec![0.1, 0.2, 0.3, 0.4, 0.5],
+            vec![100.0, 200.0, 300.0, 400.0, 500.0],
+        ];
+
+        for vector in test_vectors {
+            let quantized = ScalarQuantized::quantize(&vector);
+            let reconstructed = quantized.reconstruct();
+
+            assert_eq!(vector.len(), reconstructed.len());
+
+            for (orig, recon) in vector.iter().zip(reconstructed.iter()) {
+                // With 8-bit quantization, max error is roughly (max-min)/255
+                let max = vector.iter().copied().fold(f32::NEG_INFINITY, f32::max);
+                let min = vector.iter().copied().fold(f32::INFINITY, f32::min);
+                let max_error = (max - min) / 255.0 * 2.0; // Allow 2x for rounding
+
+                assert!(
+                    (orig - recon).abs() < max_error,
+                    "Roundtrip error too large: orig={}, recon={}, error={}",
+                    orig,
+                    recon,
+                    (orig - recon).abs()
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn test_scalar_distance_symmetry() {
+        // Test that distance(a, b) == distance(b, a)
+        let v1 = vec![1.0, 2.0, 3.0, 4.0, 5.0];
+        let v2 = vec![2.0, 3.0, 4.0, 5.0, 6.0];
+
+        let q1 = ScalarQuantized::quantize(&v1);
+        let q2 = ScalarQuantized::quantize(&v2);
+
+        let dist_ab = q1.distance(&q2);
+        let dist_ba = q2.distance(&q1);
+
+        // Distance should be symmetric (within floating point precision)
+        assert!(
+            (dist_ab - dist_ba).abs() < 0.01,
+            "Distance is not symmetric: d(a,b)={}, d(b,a)={}",
+            dist_ab,
+            dist_ba
+        );
+    }
+
+    #[test]
+    fn test_scalar_distance_different_scales() {
+        // Test distance calculation with vectors that have different scales
+        let v1 = vec![1.0, 2.0, 3.0, 4.0, 5.0]; // range: 4.0
+        let v2 = vec![10.0, 20.0, 30.0, 40.0, 50.0]; // range: 40.0
+
+        let q1 = ScalarQuantized::quantize(&v1);
+        let q2 = ScalarQuantized::quantize(&v2);
+
+        let dist_ab = q1.distance(&q2);
+        let dist_ba = q2.distance(&q1);
+
+        // With average scaling, symmetry should be maintained
+        assert!(
+            (dist_ab - dist_ba).abs() < 0.01,
+            "Distance with different scales not symmetric: d(a,b)={}, d(b,a)={}",
+            dist_ab,
+            dist_ba
+        );
+    }
+
+    #[test]
+    fn test_scalar_quantization_edge_cases() {
+        // Test with all same values
+        let same_values = vec![5.0, 5.0, 5.0, 5.0];
+        let quantized = ScalarQuantized::quantize(&same_values);
+        let reconstructed = quantized.reconstruct();
+
+        for (orig, recon) in same_values.iter().zip(reconstructed.iter()) {
+            assert!((orig - recon).abs() < 0.01);
+        }
+
+        // Test with extreme ranges
+        let extreme = vec![f32::MIN / 1e10, 0.0, f32::MAX / 1e10];
+        let quantized = ScalarQuantized::quantize(&extreme);
+        let reconstructed = quantized.reconstruct();
+
+        assert_eq!(extreme.len(), reconstructed.len());
+    }
+
+    #[test]
+    fn test_binary_distance_symmetry() {
+        // Test that binary distance is symmetric
+        let v1 = vec![1.0, -1.0, 1.0, -1.0];
+        let v2 = vec![1.0, 1.0, -1.0, -1.0];
+
+        let q1 = BinaryQuantized::quantize(&v1);
+        let q2 = BinaryQuantized::quantize(&v2);
+
+        let dist_ab = q1.distance(&q2);
+        let dist_ba = q2.distance(&q1);
+
+        assert_eq!(
+            dist_ab, dist_ba,
+            "Binary distance not symmetric: d(a,b)={}, d(b,a)={}",
+            dist_ab, dist_ba
+        );
+    }
 }