use std::time::{Duration, Instant};
use anyhow::Result;
use tracing::{debug, warn};
use crate::embedding::{EmbeddingError, EmbeddingProvider};
use crate::storage::metadata::MetadataStore;
use crate::storage::vector::{MAX_KNN_K, VectorStore};
use crate::types::SearchResult;
#[derive(Debug, thiserror::Error)]
pub enum VectorSearchError {
#[error("embedding API unavailable: {source}")]
EmbeddingUnavailable {
#[from]
source: EmbeddingError,
},
#[error("storage error: {0:#}")]
StorageError(#[from] anyhow::Error),
}
pub async fn search_vector_with_stores(
vector_store: &VectorStore,
metadata_store: &MetadataStore,
provider: &impl EmbeddingProvider,
query: &str,
limit: usize,
) -> Result<Vec<SearchResult>, VectorSearchError> {
search_vector_with_stores_timed(vector_store, metadata_store, provider, query, limit)
.await
.map(|(results, _)| results)
}
pub async fn search_vector_with_stores_timed(
vector_store: &VectorStore,
metadata_store: &MetadataStore,
provider: &impl EmbeddingProvider,
query: &str,
limit: usize,
) -> Result<(Vec<SearchResult>, Duration), VectorSearchError> {
if limit == 0 {
return Ok((Vec::new(), Duration::ZERO));
}
let embed_start = Instant::now();
let query_embedding = generate_query_embedding(provider, query, vector_store.dim()).await?;
let embed_elapsed = embed_start.elapsed();
debug!(
query = query,
dim = query_embedding.len(),
"generated query embedding"
);
let results =
search_vector_from_embedding(vector_store, metadata_store, query, limit, &query_embedding)?;
Ok((results, embed_elapsed))
}
pub(crate) async fn search_vector_with_cached_stores_timed(
vector_store: &std::sync::Mutex<VectorStore>,
metadata_store: &std::sync::Mutex<MetadataStore>,
provider: &impl EmbeddingProvider,
query: &str,
limit: usize,
) -> Result<(Vec<SearchResult>, Duration), VectorSearchError> {
if limit == 0 {
return Ok((Vec::new(), Duration::ZERO));
}
let stored_dim = vector_store
.lock()
.map_err(|_| {
VectorSearchError::StorageError(anyhow::anyhow!("vector store lock poisoned"))
})?
.dim();
let embed_start = Instant::now();
let query_embedding = generate_query_embedding(provider, query, stored_dim).await?;
let embed_elapsed = embed_start.elapsed();
debug!(
query = query,
dim = query_embedding.len(),
"generated query embedding"
);
let vector_store = vector_store.lock().map_err(|_| {
VectorSearchError::StorageError(anyhow::anyhow!("vector store lock poisoned"))
})?;
let metadata_store = metadata_store.lock().map_err(|_| {
VectorSearchError::StorageError(anyhow::anyhow!("metadata store lock poisoned"))
})?;
let results = search_vector_from_embedding(
&vector_store,
&metadata_store,
query,
limit,
&query_embedding,
)?;
Ok((results, embed_elapsed))
}
fn search_vector_from_embedding(
vector_store: &VectorStore,
metadata_store: &MetadataStore,
query: &str,
limit: usize,
query_embedding: &[f32],
) -> Result<Vec<SearchResult>, VectorSearchError> {
let (requested, candidates) = candidate_pool(limit);
if requested > candidates {
warn!(
requested,
fetched = candidates,
"candidate pool exceeds the sqlite-vec KNN cap; the filter and \
metadata over-fetch are inert above it"
);
}
let vector_results = vector_store
.search(query_embedding, candidates)
.map_err(|e| VectorSearchError::StorageError(e.context("vector search failed")))?;
debug!(
query = query,
raw_results = vector_results.len(),
"vector search returned candidates"
);
let ids: Vec<String> = vector_results
.iter()
.map(|vr| vr.chunk_id.clone())
.collect();
let mut chunk_by_id = metadata_store.get_chunks_by_ids(&ids).map_err(|e| {
VectorSearchError::StorageError(e.context("failed to batch-fetch chunk metadata"))
})?;
let mut results = Vec::with_capacity(vector_results.len());
for vr in &vector_results {
let Some(chunk) = chunk_by_id.remove(&vr.chunk_id) else {
debug!(
chunk_id = %vr.chunk_id,
"chunk metadata not found, skipping"
);
continue;
};
let score = distance_to_similarity(vr.distance);
results.push(chunk.into_search_result(score));
if results.len() >= limit {
break;
}
}
debug!(
query = query,
returned = results.len(),
"vector search complete"
);
Ok(results)
}
fn candidate_pool(limit: usize) -> (usize, usize) {
let requested = limit
.saturating_add(limit / 2)
.max(limit.saturating_add(10));
(requested, requested.min(MAX_KNN_K))
}
async fn generate_query_embedding(
provider: &impl EmbeddingProvider,
query: &str,
stored_dim: usize,
) -> Result<Vec<f32>, EmbeddingError> {
let texts = vec![provider.prepare_query_text(query)];
let mut vectors = provider.embed_batch(&texts).await?;
if vectors.is_empty() {
return Err(EmbeddingError::ResponseError {
message: "embedding API returned no vectors for query".to_string(),
});
}
let mut vector = vectors.swap_remove(0);
if vector.len() > stored_dim {
vector.truncate(stored_dim);
}
if vector.len() != stored_dim {
return Err(EmbeddingError::ResponseError {
message: format!(
"query embedding dimension {} does not match stored dimension {}",
vector.len(),
stored_dim
),
});
}
Ok(vector)
}
fn distance_to_similarity(distance: f64) -> f64 {
1.0 / (1.0 + distance)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::embedding::test_helpers::MockProvider;
use crate::types::{Chunk, Language, SymbolType};
use std::collections::HashMap;
#[test]
fn candidate_pool_is_bounded_by_the_knn_cap() {
assert_eq!(candidate_pool(10), (20, 20));
assert_eq!(candidate_pool(100), (150, 150));
let (requested, fetched) = candidate_pool(MAX_KNN_K);
assert!(
requested > MAX_KNN_K,
"over-fetch should exceed the cap here"
);
assert_eq!(fetched, MAX_KNN_K);
assert_eq!(candidate_pool(usize::MAX).1, MAX_KNN_K);
}
fn sample_chunks() -> Vec<Chunk> {
vec![
Chunk {
id: "src/alloc.rs:0".to_string(),
file_path: "src/alloc.rs".to_string(),
line_start: 1,
line_end: 15,
content: "pub fn alloc_page(size: usize) -> *mut u8 {\n \
let layout = Layout::from_size_align(size, 4096).unwrap();\n \
unsafe { std::alloc::alloc(layout) }\n}"
.to_string(),
language: Language::Rust,
symbol_type: Some(SymbolType::Function),
symbol_name: Some("alloc_page".to_string()),
},
Chunk {
id: "src/alloc.rs:1".to_string(),
file_path: "src/alloc.rs".to_string(),
line_start: 17,
line_end: 30,
content: "pub fn dealloc_page(ptr: *mut u8, size: usize) {\n \
let layout = Layout::from_size_align(size, 4096).unwrap();\n \
unsafe { std::alloc::dealloc(ptr, layout) }\n}"
.to_string(),
language: Language::Rust,
symbol_type: Some(SymbolType::Function),
symbol_name: Some("dealloc_page".to_string()),
},
Chunk {
id: "src/auth.rs:0".to_string(),
file_path: "src/auth.rs".to_string(),
line_start: 1,
line_end: 12,
content: "pub fn authenticate(user: &str, password: &str) -> Result<Token> {\n \
let hash = hash_password(password);\n \
verify_credentials(user, &hash)\n}"
.to_string(),
language: Language::Rust,
symbol_type: Some(SymbolType::Function),
symbol_name: Some("authenticate".to_string()),
},
Chunk {
id: "src/db.py:0".to_string(),
file_path: "src/db.py".to_string(),
line_start: 1,
line_end: 10,
content: "class DatabaseConnection:\n \
def __init__(self, host, port):\n \
self.conn = psycopg2.connect(host=host, port=port)\n \
def execute_query(self, sql):\n \
return self.conn.execute(sql)"
.to_string(),
language: Language::Python,
symbol_type: Some(SymbolType::Class),
symbol_name: Some("DatabaseConnection".to_string()),
},
Chunk {
id: "src/cache.go:0".to_string(),
file_path: "src/cache.go".to_string(),
line_start: 1,
line_end: 15,
content: "func NewLRUCache(capacity int) *LRUCache {\n \
return &LRUCache{\n \
capacity: capacity,\n \
items: make(map[string]*list.Element),\n \
order: list.New(),\n }\n}"
.to_string(),
language: Language::Go,
symbol_type: Some(SymbolType::Function),
symbol_name: Some("NewLRUCache".to_string()),
},
Chunk {
id: "src/server.ts:0".to_string(),
file_path: "src/server.ts".to_string(),
line_start: 1,
line_end: 10,
content: "function handleRequest(req: Request): Response {\n \
const auth = authenticate(req.headers);\n \
if (!auth) return new Response('Unauthorized', { status: 401 });\n \
return processRequest(req);\n}"
.to_string(),
language: Language::TypeScript,
symbol_type: Some(SymbolType::Function),
symbol_name: Some("handleRequest".to_string()),
},
]
}
async fn setup_test_stores(dim: usize) -> (VectorStore, MetadataStore) {
let chunks = sample_chunks();
let provider = MockProvider::new(dim);
let metadata_store = MetadataStore::open_in_memory().unwrap();
metadata_store.insert_chunks(&chunks).unwrap();
let vector_store = VectorStore::open_in_memory(dim).unwrap();
crate::embedding::test_helpers::embed_and_insert_vectors(&vector_store, &provider, &chunks)
.await;
(vector_store, metadata_store)
}
#[test]
fn distance_zero_gives_similarity_one() {
let score = distance_to_similarity(0.0);
assert!((score - 1.0).abs() < f64::EPSILON);
}
#[test]
fn distance_positive_gives_score_between_zero_and_one() {
let score = distance_to_similarity(1.0);
assert!(score > 0.0);
assert!(score < 1.0);
assert!((score - 0.5).abs() < f64::EPSILON);
}
#[test]
fn distance_large_gives_score_near_zero() {
let score = distance_to_similarity(1000.0);
assert!(score > 0.0);
assert!(score < 0.01);
}
#[test]
fn similarity_is_monotonically_decreasing() {
let distances = [0.0, 0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 100.0];
let scores: Vec<f64> = distances
.iter()
.map(|d| distance_to_similarity(*d))
.collect();
for i in 1..scores.len() {
assert!(
scores[i - 1] > scores[i],
"similarity must decrease as distance increases: {} > {} at index {i}",
scores[i - 1],
scores[i],
);
}
}
#[test]
fn storage_error_display_includes_error_chain() {
let error = anyhow::anyhow!("root cause").context("outer context");
let display = VectorSearchError::StorageError(error).to_string();
assert!(display.contains("outer context"));
assert!(display.contains("root cause"));
}
#[tokio::test]
async fn query_embedding_has_correct_dimension() {
let provider = MockProvider::new(8);
let embedding = generate_query_embedding(&provider, "test query", 8)
.await
.unwrap();
assert_eq!(embedding.len(), 8);
}
#[tokio::test]
async fn query_embedding_truncates_to_stored_dim() {
let provider = MockProvider::new(16);
let embedding = generate_query_embedding(&provider, "test query", 8)
.await
.unwrap();
assert_eq!(embedding.len(), 8);
}
#[tokio::test]
async fn query_embedding_rejects_dim_mismatch() {
let provider = MockProvider::new(4);
let result = generate_query_embedding(&provider, "test query", 8).await;
assert!(result.is_err());
let err = result.unwrap_err();
assert!(
err.to_string().contains("dimension"),
"error should mention dimension: {err}"
);
}
#[tokio::test]
async fn query_embedding_propagates_auth_error() {
let provider = MockProvider::failing(EmbeddingError::AuthError {
message: "invalid key".to_string(),
});
let result = generate_query_embedding(&provider, "test query", 4).await;
assert!(result.is_err());
assert!(
matches!(result.unwrap_err(), EmbeddingError::AuthError { .. }),
"should propagate auth error"
);
}
#[tokio::test]
async fn query_embedding_propagates_connection_error() {
let provider = MockProvider::failing(EmbeddingError::ConnectionError {
message: "unreachable".to_string(),
});
let result = generate_query_embedding(&provider, "test query", 4).await;
assert!(result.is_err());
assert!(
matches!(result.unwrap_err(), EmbeddingError::ConnectionError { .. }),
"should propagate connection error"
);
}
#[tokio::test]
async fn search_returns_results_for_indexed_content() {
let dim = 8;
let (vector_store, metadata_store) = setup_test_stores(dim).await;
let provider = MockProvider::new(dim);
let results =
search_vector_with_stores(&vector_store, &metadata_store, &provider, "alloc", 10)
.await
.unwrap();
assert!(!results.is_empty(), "should find results for 'alloc'");
}
#[tokio::test]
async fn results_sorted_by_score_descending() {
let dim = 8;
let (vector_store, metadata_store) = setup_test_stores(dim).await;
let provider = MockProvider::new(dim);
let results = search_vector_with_stores(
&vector_store,
&metadata_store,
&provider,
"database connection query",
10,
)
.await
.unwrap();
assert!(
results.len() >= 2,
"need multiple results to verify ordering"
);
for i in 1..results.len() {
assert!(
results[i - 1].score >= results[i].score,
"scores must be descending: {} >= {} at position {i}",
results[i - 1].score,
results[i].score,
);
}
}
#[tokio::test]
async fn results_include_full_metadata() {
let dim = 8;
let (vector_store, metadata_store) = setup_test_stores(dim).await;
let provider = MockProvider::new(dim);
let results =
search_vector_with_stores(&vector_store, &metadata_store, &provider, "cache", 10)
.await
.unwrap();
assert!(!results.is_empty());
let top = &results[0];
assert!(!top.file_path.is_empty(), "file_path should be set");
assert!(top.line_start > 0, "line_start should be 1-based");
assert!(top.line_end >= top.line_start, "line_end >= line_start");
assert!(!top.content.is_empty(), "content should be present");
assert!(top.score > 0.0, "score should be positive");
assert!(top.score <= 1.0, "similarity score should be <= 1.0");
}
#[tokio::test]
async fn search_respects_limit() {
let dim = 8;
let (vector_store, metadata_store) = setup_test_stores(dim).await;
let provider = MockProvider::new(dim);
let results =
search_vector_with_stores(&vector_store, &metadata_store, &provider, "function", 2)
.await
.unwrap();
assert!(results.len() <= 2, "results should respect the limit of 2");
}
#[tokio::test]
async fn search_zero_limit_skips_embedding() {
let dim = 8;
let vector_store = VectorStore::open_in_memory(dim).unwrap();
let metadata_store = MetadataStore::open_in_memory().unwrap();
let provider = MockProvider::failing(EmbeddingError::ConnectionError {
message: "should not be called".to_string(),
});
let results =
search_vector_with_stores(&vector_store, &metadata_store, &provider, "function", 0)
.await
.unwrap();
assert!(results.is_empty());
}
#[tokio::test]
async fn scores_are_positive_and_bounded() {
let dim = 8;
let (vector_store, metadata_store) = setup_test_stores(dim).await;
let provider = MockProvider::new(dim);
let results = search_vector_with_stores(
&vector_store,
&metadata_store,
&provider,
"authenticate",
10,
)
.await
.unwrap();
for result in &results {
assert!(result.score > 0.0, "score should be positive");
assert!(result.score <= 1.0, "score should be <= 1.0");
}
}
#[tokio::test]
async fn search_with_embedding_error_returns_error() {
let dim = 8;
let (vector_store, metadata_store) = setup_test_stores(dim).await;
let provider = MockProvider::failing(EmbeddingError::ConnectionError {
message: "API down".to_string(),
});
let result =
search_vector_with_stores(&vector_store, &metadata_store, &provider, "test", 10).await;
assert!(result.is_err(), "should return error when embedding fails");
assert!(
matches!(
result.unwrap_err(),
VectorSearchError::EmbeddingUnavailable { .. }
),
"should be an embedding unavailable error"
);
}
#[tokio::test]
async fn search_returns_results_from_multiple_languages() {
let dim = 8;
let (vector_store, metadata_store) = setup_test_stores(dim).await;
let provider = MockProvider::new(dim);
let results = search_vector_with_stores(
&vector_store,
&metadata_store,
&provider,
"code function",
10,
)
.await
.unwrap();
let languages: std::collections::HashSet<_> = results.iter().map(|r| r.language).collect();
assert!(
languages.len() >= 2,
"should return results from multiple languages, got: {languages:?}"
);
}
#[tokio::test]
async fn search_with_truncation() {
let dim = 8;
let (vector_store, metadata_store) = setup_test_stores(dim).await;
let query_provider = MockProvider::new(16);
let results =
search_vector_with_stores(&vector_store, &metadata_store, &query_provider, "cache", 10)
.await
.unwrap();
assert!(
!results.is_empty(),
"should work with truncated query embeddings"
);
}
#[tokio::test]
async fn empty_vector_store_returns_empty_results() {
let dim = 8;
let vector_store = VectorStore::open_in_memory(dim).unwrap();
let metadata_store = MetadataStore::open_in_memory().unwrap();
let provider = MockProvider::new(dim);
let results =
search_vector_with_stores(&vector_store, &metadata_store, &provider, "anything", 10)
.await
.unwrap();
assert!(results.is_empty(), "empty store should return no results");
}
#[tokio::test]
async fn batch_chunk_fetch_preserves_vector_distance_order() {
let dim = 8;
let metadata_store = MetadataStore::open_in_memory().unwrap();
let chunks = vec![
Chunk {
id: "a".to_string(),
file_path: "src/a.rs".to_string(),
line_start: 1,
line_end: 2,
content: "fn a() {}".to_string(),
language: Language::Rust,
symbol_type: Some(SymbolType::Function),
symbol_name: Some("a".to_string()),
},
Chunk {
id: "b".to_string(),
file_path: "src/b.rs".to_string(),
line_start: 1,
line_end: 2,
content: "fn b() {}".to_string(),
language: Language::Rust,
symbol_type: Some(SymbolType::Function),
symbol_name: Some("b".to_string()),
},
Chunk {
id: "c".to_string(),
file_path: "src/c.rs".to_string(),
line_start: 1,
line_end: 2,
content: "fn c() {}".to_string(),
language: Language::Rust,
symbol_type: Some(SymbolType::Function),
symbol_name: Some("c".to_string()),
},
];
metadata_store.insert_chunks(&chunks).unwrap();
let vector_store = VectorStore::open_in_memory(dim).unwrap();
let provider = MockProvider::new(dim);
crate::embedding::test_helpers::embed_and_insert_vectors(&vector_store, &provider, &chunks)
.await;
let query_embedding = generate_query_embedding(&provider, "fn", dim)
.await
.unwrap();
let vector_results = vector_store.search(&query_embedding, chunks.len()).unwrap();
assert_eq!(vector_results.len(), chunks.len());
let chunk_by_id: HashMap<&str, &Chunk> =
chunks.iter().map(|c| (c.id.as_str(), c)).collect();
let expected: Vec<(&str, &str, f64)> = vector_results
.iter()
.map(|vr| {
let chunk = chunk_by_id[vr.chunk_id.as_str()];
(
chunk.file_path.as_str(),
chunk.content.as_str(),
distance_to_similarity(vr.distance),
)
})
.collect();
let expected_paths: Vec<&str> = expected.iter().map(|(path, _, _)| *path).collect();
let storage_order_paths: Vec<&str> = chunks.iter().map(|c| c.file_path.as_str()).collect();
assert_ne!(
expected_paths, storage_order_paths,
"fixture is not discriminating: distance order equals insertion and primary-key order"
);
let results =
search_vector_with_stores(&vector_store, &metadata_store, &provider, "fn", 10)
.await
.unwrap();
assert_eq!(
results.len(),
expected.len(),
"batch fetch dropped candidates"
);
let actual: Vec<(&str, &str, f64)> = results
.iter()
.map(|r| (r.file_path.as_str(), r.content.as_str(), r.score))
.collect();
assert_eq!(
actual, expected,
"each chunk must come back paired with its own distance, in vector-distance order"
);
}
#[tokio::test]
async fn result_content_matches_source_chunk() {
let dim = 8;
let chunks = sample_chunks();
let (vector_store, metadata_store) = setup_test_stores(dim).await;
let provider = MockProvider::new(dim);
let results =
search_vector_with_stores(&vector_store, &metadata_store, &provider, "alloc page", 10)
.await
.unwrap();
assert!(!results.is_empty());
let alloc_result = results.iter().find(|r| r.file_path == "src/alloc.rs");
assert!(alloc_result.is_some(), "should find result from alloc.rs");
let alloc_result = alloc_result.unwrap();
let matching_chunk = chunks
.iter()
.find(|c| c.file_path == alloc_result.file_path && c.content == alloc_result.content);
assert!(
matching_chunk.is_some(),
"result content should match a source chunk"
);
}
}