Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/docs/guides/quick-fix-guide.md

@@ -0,0 +1,247 @@
+# Quick Fix Guide for Remaining Compilation Errors
+
+## Summary
+
+8 compilation errors remaining in `ruvector-core`. All errors are in two categories:
+1. **Bincode trait implementation** (3 errors)
+2. **HNSW DataId constructor** (5 errors, but same fix)
+
+## Fix 1: Bincode Decode Trait (agenticdb.rs)
+
+### Problem
+```rust
+error[E0107]: missing generics for trait `Decode`
+   --> crates/ruvector-core/src/agenticdb.rs:59:15
+    |
+ 59 | impl bincode::Decode for ReflexionEpisode {
+    |               ^^^^^^ expected 1 generic argument
+```
+
+### Solution Option A: Use Default Configuration
+
+Replace lines 59-92 in `/home/user/ruvector/crates/ruvector-core/src/agenticdb.rs`:
+
+```rust
+// Remove manual implementation and use serde-based bincode
+// This works because serde already implemented for the type
+
+// Just remove the manual bincode::Encode, bincode::Decode, and bincode::BorrowDecode impls
+// The struct already has Serialize, Deserialize which bincode can use
+
+// Or if manual implementation needed:
+use bincode::config::Configuration;
+
+impl bincode::Decode for ReflexionEpisode {
+    fn decode<D: bincode::de::Decoder>(
+        decoder: &mut D,
+    ) -> core::result::Result<Self, bincode::error::DecodeError> {
+        use bincode::Decode;
+        let id = String::decode(decoder)?;
+        let task = String::decode(decoder)?;
+        let actions = Vec::<String>::decode(decoder)?;
+        let observations = Vec::<String>::decode(decoder)?;
+        let critique = String::decode(decoder)?;
+        let embedding = Vec::<f32>::decode(decoder)?;
+        let timestamp = i64::decode(decoder)?;
+        let metadata_json = Option::<String>::decode(decoder)?;
+        let metadata = metadata_json.and_then(|s| serde_json::from_str(&s).ok());
+        Ok(Self {
+            id,
+            task,
+            actions,
+            observations,
+            critique,
+            embedding,
+            timestamp,
+            metadata,
+        })
+    }
+}
+
+impl<'de> bincode::BorrowDecode<'de> for ReflexionEpisode {
+    fn borrow_decode<D: bincode::de::BorrowDecoder<'de>>(
+        decoder: &mut D,
+    ) -> core::result::Result<Self, bincode::error::DecodeError> {
+        <Self as bincode::Decode>::decode(decoder)
+    }
+}
+```
+
+### Solution Option B: Use Serde-Based Bincode (Recommended)
+
+Since `ReflexionEpisode` already has `Serialize` and `Deserialize`, you can:
+
+1. Remove the manual `bincode::Encode`, `bincode::Decode`, and `bincode::BorrowDecode` implementations (lines 40-92)
+2. Use `bincode::serde::encode`/`decode` where needed
+
+Example usage:
+```rust
+// Encoding
+let bytes = bincode::serde::encode_to_vec(&episode, bincode::config::standard())?;
+
+// Decoding
+let episode: ReflexionEpisode = bincode::serde::decode_from_slice(&bytes, bincode::config::standard())?.0;
+```
+
+## Fix 2: HNSW DataId Constructor (index/hnsw.rs)
+
+### Problem
+```rust
+error[E0599]: no function or associated item named `new` found for type `usize`
+   --> crates/ruvector-core/src/index/hnsw.rs:191:44
+    |
+191 |                 let data_with_id = DataId::new(idx, vector.1.clone());
+    |                                            ^^^ function or associated item not found in `usize`
+```
+
+### Investigation Needed
+
+Check `hnsw_rs` documentation for `DataId`:
+
+```rust
+// Option 1: DataId might be a type alias for a tuple
+pub type DataId<T, Idx> = (Idx, Vec<T>);
+// In which case, use tuple syntax:
+let data_with_id = (idx, vector.clone());
+
+// Option 2: DataId might have a different constructor
+// Check hnsw_rs::prelude::* imports
+
+// Option 3: Use the hnsw_rs builder pattern
+// Some libraries use .with_id() or similar
+```
+
+### Recommended Fix (Needs Verification)
+
+1. Add debug logging to see what `DataId` actually is:
+```bash
+cd /home/user/ruvector
+cargo doc --open -p hnsw_rs
+# Look for DataId documentation
+```
+
+2. Check hnsw_rs source or examples:
+```bash
+cargo tree | grep hnsw_rs
+# Note version
+# Check examples at: https://github.com/jean-pierreBoth/hnswlib-rs
+```
+
+3. Most likely fix (based on typical hnsw_rs usage):
+
+In `/home/user/ruvector/crates/ruvector-core/src/index/hnsw.rs`:
+
+Replace lines 191, 254, 287:
+
+```rust
+// OLD (line 191):
+let data_with_id = DataId::new(idx, vector.1.clone());
+
+// NEW - Try tuple syntax first:
+let data_with_id = (idx, vector.1.clone());
+
+// OLD (line 254):
+let data_with_id = DataId::new(idx, vector.clone());
+
+// NEW:
+let data_with_id = (idx, vector.clone());
+
+// OLD (line 287):
+(id.clone(), idx, DataId::new(idx, vector.clone()))
+
+// NEW:
+(id.clone(), idx, (idx, vector.clone()))
+```
+
+### Alternative: Use HNSW<f32, usize> Directly
+
+Check if `Hnsw<f32, DistanceFFI>` expects different data format:
+
+```rust
+// The hnsw_rs library typically uses:
+impl Hnsw<f32, usize> {
+    pub fn insert(&mut self, data: (&[f32], usize)) { ... }
+}
+
+// So try:
+hnsw.insert((&vector, idx));
+// Instead of:
+hnsw.insert(DataId::new(idx, vector));
+```
+
+## Quick Testing Script
+
+Create `/home/user/ruvector/scripts/test-fixes.sh`:
+
+```bash
+#!/bin/bash
+set -e
+
+echo "Testing Fix 1: Bincode traits..."
+cargo build --lib -p ruvector-core 2>&1 | grep -c "error\[E0107\]" || echo "Bincode errors fixed!"
+
+echo "Testing Fix 2: HNSW DataId..."
+cargo build --lib -p ruvector-core 2>&1 | grep -c "error\[E0599\].*DataId" || echo "DataId errors fixed!"
+
+echo "Full build test..."
+cargo build --lib -p ruvector-core
+
+echo "Run tests..."
+cargo test -p ruvector-core --lib
+
+echo "All checks passed!"
+```
+
+## Verification Steps
+
+After applying fixes:
+
+```bash
+# 1. Clean build
+cargo clean
+cargo build --lib -p ruvector-core
+
+# 2. Run tests
+cargo test --lib -p ruvector-core
+
+# 3. Check no warnings
+cargo clippy --lib -p ruvector-core -- -D warnings
+
+# 4. Full workspace build
+cargo build --workspace
+
+# 5. Full test suite
+cargo test --workspace
+```
+
+## Expected Timeline
+
+- Fix 1 (Bincode): 15-30 minutes
+- Fix 2 (DataId): 30-60 minutes (includes investigation)
+- Verification: 15-30 minutes
+- **Total: 1-2 hours**
+
+## Next Steps After Fixes
+
+1. ✅ Build succeeds
+2. Run full test suite: `cargo test --workspace`
+3. Run benchmarks: `cargo bench -p ruvector-bench`
+4. Security audit: `cargo audit`
+5. Cross-platform testing
+6. Performance validation
+7. Documentation review
+8. **Release readiness assessment**
+
+## Support Resources
+
+- **hnsw_rs Documentation:** https://docs.rs/hnsw_rs/latest/hnsw_rs/
+- **bincode Documentation:** https://docs.rs/bincode/latest/bincode/
+- **Cargo Book:** https://doc.rust-lang.org/cargo/
+
+## Contact
+
+If issues persist after trying these fixes:
+1. Check hnsw_rs version in Cargo.lock
+2. Review hnsw_rs CHANGELOG for API changes
+3. Look for similar usage in hnsw_rs examples directory
+4. Consider opening an issue with specific error details