Skip to main content

khive_runtime/
retrieval.rs

1//! Retrieval operations: local embedding generation and hybrid search with RRF fusion.
2
3use std::collections::{HashMap, HashSet};
4
5use lattice_embed::{EmbeddingModel, MAX_TEXT_CHARS};
6use uuid::Uuid;
7
8use crate::config::{parse_embedding_model_alias, sanitize_key};
9use crate::curation::note_fts_document;
10use crate::error::{RuntimeError, RuntimeResult};
11use crate::runtime::{KhiveRuntime, NamespaceToken};
12use khive_score::{rrf_score, DeterministicScore};
13use khive_storage::types::{
14    PageRequest, TextFilter, TextQueryMode, TextSearchHit, TextSearchRequest, VectorSearchHit,
15    VectorSearchRequest,
16};
17use khive_storage::EntityFilter;
18use khive_types::SubstrateKind;
19
20// Fault-injection flag for backfill reader errors (test / `fault-injection` builds only).
21#[cfg(any(test, feature = "fault-injection"))]
22std::thread_local! {
23    static BACKFILL_READER_FAIL: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
24}
25
26/// Arm the backfill reader fault injection: the next `backfill_missing_embeddings`
27/// call substitutes a `StorageError::Pool` for `sql.reader().await`'s result, then
28/// resets the flag. The injected error passes through the same
29/// `map_err(RuntimeError::Storage)?` path as a real reader failure, exercising the
30/// fail-closed guard rather than bypassing it.
31#[cfg(any(test, feature = "fault-injection"))]
32pub fn arm_backfill_reader_fail() {
33    BACKFILL_READER_FAIL.with(|c| c.set(true));
34}
35
36/// A unified search result combining vector and text signals.
37#[derive(Clone, Debug)]
38pub struct SearchHit {
39    pub entity_id: Uuid,
40    pub score: DeterministicScore,
41    pub source: SearchSource,
42    pub title: Option<String>,
43    pub snippet: Option<String>,
44}
45
46/// Which retrieval path(s) contributed to a hit.
47#[derive(Clone, Copy, Debug, PartialEq, Eq)]
48pub enum SearchSource {
49    Vector,
50    Text,
51    Both,
52}
53
54impl SearchSource {
55    /// Combine retrieval-leg membership from two appearances of the same hit.
56    #[must_use]
57    pub const fn union(self, other: Self) -> Self {
58        match (self, other) {
59            (Self::Text, Self::Text) => Self::Text,
60            (Self::Vector, Self::Vector) => Self::Vector,
61            _ => Self::Both,
62        }
63    }
64
65    /// Lowercase wire representation used by search serializers.
66    #[must_use]
67    pub const fn as_str(self) -> &'static str {
68        match self {
69            Self::Vector => "vector",
70            Self::Text => "text",
71            Self::Both => "both",
72        }
73    }
74}
75
76/// RRF constant. Controls how strongly top ranks dominate.
77///
78/// The paper's k=60 over-compresses scores at KG scale (tens–thousands of
79/// entities): rank 1 ≈ 0.016, rank 10 ≈ 0.014, spread ≈ 0.002. k=10 gives
80/// rank 1 ≈ 0.091, rank 10 ≈ 0.050, spread ≈ 0.041 — 20× better discrimination,
81/// which dedup-before-create needs at graph sizes of 50–2700 entities.
82const RRF_K: usize = 10;
83
84/// Candidates pulled per path before fusion. Higher = better recall, more work.
85const CANDIDATE_MULTIPLIER: u32 = 4;
86
87/// Advisory emitted by write verbs when only the embedding input was bounded.
88pub const EMBEDDING_INPUT_TRUNCATED_WARNING: &str =
89    "embedding input was truncated to the embedder maximum; full content was stored unchanged";
90
91/// What the embedding service actually received for one document.
92#[derive(Clone, Debug)]
93pub struct DocumentEmbeddingOutcome {
94    pub model_name: String,
95    pub vector: Vec<f32>,
96    pub source_bytes: usize,
97    pub embedded_bytes: usize,
98    pub truncated: bool,
99}
100
101/// Aggregate truncation accounting for one logical write or reindex batch.
102#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Deserialize, serde::Serialize)]
103pub struct EmbeddingTruncationReport {
104    pub truncated: u64,
105    pub discarded_bytes: u64,
106}
107
108impl EmbeddingTruncationReport {
109    pub fn observe(&mut self, outcome: &DocumentEmbeddingOutcome) {
110        if outcome.truncated {
111            self.truncated += 1;
112            self.discarded_bytes +=
113                outcome.source_bytes.saturating_sub(outcome.embedded_bytes) as u64;
114        }
115    }
116
117    #[must_use]
118    pub const fn any_truncated(&self) -> bool {
119        self.truncated > 0
120    }
121
122    /// Add another batch's counters without wrapping on overflow.
123    pub fn merge(&mut self, other: Self) {
124        self.truncated = self.truncated.saturating_add(other.truncated);
125        self.discarded_bytes = self.discarded_bytes.saturating_add(other.discarded_bytes);
126    }
127}
128
129/// Maximum document bytes accepted before the embedding service adds its model prefix.
130pub fn document_embedding_budget(model_name: &str) -> usize {
131    parse_embedding_model_alias(model_name)
132        .and_then(|model| model.document_instruction())
133        .map_or(MAX_TEXT_CHARS, |prefix| {
134            MAX_TEXT_CHARS.saturating_sub(prefix.len())
135        })
136}
137
138/// Return the longest UTF-8-safe prefix of `text` within `max_bytes` and whether it was shortened.
139pub fn bounded_embedding_input(text: &str, max_bytes: usize) -> (&str, bool) {
140    if text.len() <= max_bytes {
141        return (text, false);
142    }
143
144    let end = text
145        .char_indices()
146        .map(|(index, _)| index)
147        .take_while(|index| *index <= max_bytes)
148        .last()
149        .unwrap_or(0);
150    (&text[..end], true)
151}
152
153impl KhiveRuntime {
154    /// Generate an embedding vector for `text` using the configured default model.
155    ///
156    /// First call lazily loads model weights (cold start cost). Subsequent calls reuse them.
157    /// Returns `Unconfigured("embedding_model")` if no model is configured.
158    pub async fn embed(&self, text: &str) -> RuntimeResult<Vec<f32>> {
159        let model_name = self.default_embedder_name();
160        if model_name.is_empty() {
161            return Err(RuntimeError::Unconfigured("embedding_model".into()));
162        }
163        self.embed_with_model(model_name, text).await
164    }
165
166    /// Generate an embedding vector for `text` using the named model.
167    ///
168    /// Accepts both built-in lattice model names/aliases and custom provider
169    /// names registered via [`KhiveRuntime::register_embedder`]. For lattice
170    /// models the resolved `EmbeddingModel` enum is forwarded to `embed_one`
171    /// so the service can select the correct model variant. For custom
172    /// providers, `embed_one` is called with `EmbeddingModel::default()`
173    /// because custom services are expected to ignore the enum argument (they
174    /// own a single model implicitly).
175    ///
176    /// Applies no instruction prefix (generic role). Use
177    /// [`Self::embed_document_with_model`] / [`Self::embed_query_with_model`] for
178    /// instruction-tuned models where the asymmetric prefix matters.
179    ///
180    /// Returns `UnknownModel` if `model_name` is not in the embedder registry.
181    pub async fn embed_with_model(&self, model_name: &str, text: &str) -> RuntimeResult<Vec<f32>> {
182        let model = parse_embedding_model_alias(model_name);
183        let service = self.embedder(model_name).await?;
184        let emb_model = model.unwrap_or_default();
185        // Issued-at-dispatch: count before the provider await so a call that
186        // was handed to the provider is counted even if this task is aborted
187        // while parked on the await (drain_embed_join_set cancellation path).
188        crate::usage::count(crate::usage::UsageUnit::EmbedCalls, 1);
189        let out = service.embed_one(text, emb_model).await;
190        Ok(out?)
191    }
192
193    /// Embed a document/passage for indexing using the named model.
194    ///
195    /// Applies `EmbeddingService::embed_passage`, which prepends the model's
196    /// `document_instruction()` prefix when defined (e.g. `"passage: "` for
197    /// multilingual-e5). For models with no document prefix (MiniLM, BGE) this
198    /// is identical to [`Self::embed_with_model`].
199    ///
200    /// Use this for all index/store/backfill paths so that instruction-tuned
201    /// models produce passage-side vectors.
202    ///
203    /// **Reindex caveat**: switching from an unprefixed model (or a model with no
204    /// `document_instruction`) to an instruction-tuned model changes the vector
205    /// representation. Vectors stored under the old scheme are not comparable to
206    /// newly prefixed vectors. Operators must trigger a full reindex
207    /// (`knowledge.index(rebuild_ann=true)` / `kkernel reindex`) after changing
208    /// the embedding model config.
209    ///
210    /// Returns `UnknownModel` if `model_name` is not registered.
211    pub async fn embed_document_with_model(
212        &self,
213        model_name: &str,
214        text: &str,
215    ) -> RuntimeResult<Vec<f32>> {
216        Ok(self
217            .embed_document_with_model_outcome_inner(None, model_name, text)
218            .await?
219            .vector)
220    }
221
222    pub async fn embed_document_with_model_outcome(
223        &self,
224        model_name: &str,
225        text: &str,
226    ) -> RuntimeResult<DocumentEmbeddingOutcome> {
227        self.embed_document_with_model_outcome_inner(None, model_name, text)
228            .await
229    }
230
231    pub(crate) async fn embed_document_with_model_outcome_for_token(
232        &self,
233        token: &NamespaceToken,
234        model_name: &str,
235        text: &str,
236    ) -> RuntimeResult<DocumentEmbeddingOutcome> {
237        self.embed_document_with_model_outcome_inner(Some(token), model_name, text)
238            .await
239    }
240
241    async fn embed_document_with_model_outcome_inner(
242        &self,
243        token: Option<&NamespaceToken>,
244        model_name: &str,
245        text: &str,
246    ) -> RuntimeResult<DocumentEmbeddingOutcome> {
247        let model = parse_embedding_model_alias(model_name);
248        let service = match token {
249            Some(token) => self.embedder_with_token(token, model_name).await?,
250            None => self.embedder(model_name).await?,
251        };
252        let emb_model = model.unwrap_or_default();
253        let source_bytes = text.len();
254        let (text, truncated) =
255            bounded_embedding_input(text, document_embedding_budget(model_name));
256        let embedded_bytes = text.len();
257        // Issued-at-dispatch: counted before the await — see embed_with_model.
258        crate::usage::count(crate::usage::UsageUnit::EmbedCalls, 1);
259        let embeddings = service.embed_passage(&[text.to_string()], emb_model).await;
260        let mut vectors = embeddings?;
261        if vectors.len() != 1 {
262            return Err(RuntimeError::Internal(format!(
263                "embed_passage returned {} vectors for 1 input",
264                vectors.len()
265            )));
266        }
267        let out = vectors.pop().expect("checked len == 1 above");
268        Ok(DocumentEmbeddingOutcome {
269            model_name: model_name.to_owned(),
270            vector: out,
271            source_bytes,
272            embedded_bytes,
273            truncated,
274        })
275    }
276
277    /// Embed a query string for retrieval using the named model.
278    ///
279    /// Applies the pre-0.6 query-role behavior. E5 and Qwen models retain
280    /// their query instructions, while BGE and custom providers receive the
281    /// original unprefixed query text.
282    ///
283    /// Use this for all search/recall/suggest query embedding paths so that
284    /// instruction-tuned models land in the correct side of their retrieval
285    /// space.
286    ///
287    /// Returns `UnknownModel` if `model_name` is not registered.
288    pub async fn embed_query_with_model(
289        &self,
290        model_name: &str,
291        text: &str,
292    ) -> RuntimeResult<Vec<f32>> {
293        self.embed_query_with_model_inner(None, model_name, text)
294            .await
295    }
296
297    pub(crate) async fn embed_query_with_model_for_token(
298        &self,
299        token: &NamespaceToken,
300        model_name: &str,
301        text: &str,
302    ) -> RuntimeResult<Vec<f32>> {
303        self.embed_query_with_model_inner(Some(token), model_name, text)
304            .await
305    }
306
307    async fn embed_query_with_model_inner(
308        &self,
309        token: Option<&NamespaceToken>,
310        model_name: &str,
311        text: &str,
312    ) -> RuntimeResult<Vec<f32>> {
313        let model = parse_embedding_model_alias(model_name);
314        let service = match token {
315            Some(token) => self.embedder_with_token(token, model_name).await?,
316            None => self.embedder(model_name).await?,
317        };
318        let texts = [text.to_string()];
319        let emb_model = model.unwrap_or_default();
320        // Issued-at-dispatch: counted before the await — see embed_with_model.
321        crate::usage::count(crate::usage::UsageUnit::EmbedCalls, 1);
322        let embeddings = match emb_model {
323            EmbeddingModel::BgeSmallEnV15
324            | EmbeddingModel::BgeBaseEnV15
325            | EmbeddingModel::BgeLargeEnV15 => service.embed(&texts, emb_model).await,
326            _ => service.embed_query(&texts, emb_model).await,
327        };
328        let out = embeddings?
329            .into_iter()
330            .next()
331            .ok_or_else(|| RuntimeError::Internal("embed_query returned empty vec".into()))?;
332        Ok(out)
333    }
334
335    /// Embed a document for indexing using the configured default model.
336    ///
337    /// Delegates to [`Self::embed_document_with_model`]. Use for entity/note
338    /// create and reindex paths.
339    ///
340    /// Returns `Unconfigured("embedding_model")` if no model is configured.
341    pub async fn embed_document(&self, text: &str) -> RuntimeResult<Vec<f32>> {
342        let model_name = self.default_embedder_name();
343        if model_name.is_empty() {
344            return Err(RuntimeError::Unconfigured("embedding_model".into()));
345        }
346        self.embed_document_with_model(model_name, text).await
347    }
348
349    /// Embed a query for retrieval using the configured default model.
350    ///
351    /// Delegates to [`Self::embed_query_with_model`]. Use for vector search and
352    /// hybrid search query paths.
353    ///
354    /// Returns `Unconfigured("embedding_model")` if no model is configured.
355    pub async fn embed_query(&self, text: &str) -> RuntimeResult<Vec<f32>> {
356        let model_name = self.default_embedder_name();
357        if model_name.is_empty() {
358            return Err(RuntimeError::Unconfigured("embedding_model".into()));
359        }
360        self.embed_query_with_model(model_name, text).await
361    }
362
363    async fn embed_query_for_token(
364        &self,
365        token: &NamespaceToken,
366        text: &str,
367    ) -> RuntimeResult<Vec<f32>> {
368        let model_name = self.default_embedder_name();
369        if model_name.is_empty() {
370            return Err(RuntimeError::Unconfigured("embedding_model".into()));
371        }
372        self.embed_query_with_model_for_token(token, model_name, text)
373            .await
374    }
375
376    /// Generate embeddings for multiple texts in one call using the configured default model.
377    ///
378    /// Delegates to the cached `EmbeddingService::embed`, so repeated texts within
379    /// and across calls benefit from the runtime-level LRU cache.
380    ///
381    /// Returns an empty vec for empty input without hitting the embedding service.
382    /// Returns `Unconfigured("embedding_model")` if no model is configured.
383    pub async fn embed_batch(&self, texts: &[String]) -> RuntimeResult<Vec<Vec<f32>>> {
384        if texts.is_empty() {
385            return Ok(vec![]);
386        }
387        let model_name = self.default_embedder_name();
388        if model_name.is_empty() {
389            return Err(RuntimeError::Unconfigured("embedding_model".into()));
390        }
391        self.embed_batch_with_model(model_name, texts).await
392    }
393
394    /// Generate embeddings for multiple texts using the named model.
395    ///
396    /// Accepts lattice model names/aliases and custom provider names.
397    /// Returns `UnknownModel` if `model_name` is not in the embedder registry.
398    pub async fn embed_batch_with_model(
399        &self,
400        model_name: &str,
401        texts: &[String],
402    ) -> RuntimeResult<Vec<Vec<f32>>> {
403        if texts.is_empty() {
404            return Ok(vec![]);
405        }
406        let model = parse_embedding_model_alias(model_name);
407        let service = self.embedder(model_name).await?;
408        let emb_model = model.unwrap_or_default();
409        let out = service.embed(texts, emb_model).await;
410        crate::usage::count(crate::usage::UsageUnit::EmbedCalls, texts.len() as u64);
411        Ok(out?)
412    }
413
414    /// Embed a batch of documents for indexing using the named model.
415    ///
416    /// Applies `EmbeddingService::embed_passage`. Use for all bulk
417    /// index/backfill/reindex operations to apply the passage-side prefix.
418    /// A mixed batch is bounded into one ordered owned batch so truncation never
419    /// fragments one provider batch into sequential singleton inference calls.
420    ///
421    /// **Reindex caveat**: see [`Self::embed_document_with_model`] — the same
422    /// incomparability applies to batch-indexed vectors when switching models.
423    ///
424    /// Returns `UnknownModel` if `model_name` is not registered.
425    pub async fn embed_document_batch_with_model(
426        &self,
427        model_name: &str,
428        texts: &[String],
429    ) -> RuntimeResult<Vec<Vec<f32>>> {
430        if texts.is_empty() {
431            return Ok(vec![]);
432        }
433        Ok(self
434            .embed_document_batch_with_model_outcomes(model_name, texts)
435            .await?
436            .into_iter()
437            .map(|outcome| outcome.vector)
438            .collect())
439    }
440
441    pub async fn embed_document_batch_with_model_outcomes(
442        &self,
443        model_name: &str,
444        texts: &[String],
445    ) -> RuntimeResult<Vec<DocumentEmbeddingOutcome>> {
446        if texts.is_empty() {
447            return Ok(vec![]);
448        }
449        let model = parse_embedding_model_alias(model_name);
450        let service = self.embedder(model_name).await?;
451        let emb_model = model.unwrap_or_default();
452        let budget = document_embedding_budget(model_name);
453        let out = if texts.iter().all(|text| text.len() <= budget) {
454            service.embed_passage(texts, emb_model).await
455        } else {
456            let bounded_texts: Vec<String> = texts
457                .iter()
458                .map(|text| bounded_embedding_input(text, budget).0.to_owned())
459                .collect();
460            service.embed_passage(&bounded_texts, emb_model).await
461        };
462        crate::usage::count(crate::usage::UsageUnit::EmbedCalls, texts.len() as u64);
463        let vectors = out?;
464        if vectors.len() != texts.len() {
465            return Err(RuntimeError::Internal(format!(
466                "embed_passage returned {} vectors for {} inputs",
467                vectors.len(),
468                texts.len()
469            )));
470        }
471        Ok(texts
472            .iter()
473            .zip(vectors)
474            .map(|(text, vector)| {
475                let (bounded, truncated) = bounded_embedding_input(text, budget);
476                DocumentEmbeddingOutcome {
477                    model_name: model_name.to_owned(),
478                    vector,
479                    source_bytes: text.len(),
480                    embedded_bytes: bounded.len(),
481                    truncated,
482                }
483            })
484            .collect())
485    }
486
487    /// Embed a batch of documents for indexing using the configured default model.
488    ///
489    /// Convenience delegate to [`Self::embed_document_batch_with_model`]. Use for
490    /// bulk knowledge-atom and section indexing paths.
491    ///
492    /// Returns `Unconfigured("embedding_model")` if no model is configured.
493    pub async fn embed_document_batch(&self, texts: &[String]) -> RuntimeResult<Vec<Vec<f32>>> {
494        if texts.is_empty() {
495            return Ok(vec![]);
496        }
497        let model_name = self.default_embedder_name();
498        if model_name.is_empty() {
499            return Err(RuntimeError::Unconfigured("embedding_model".into()));
500        }
501        self.embed_document_batch_with_model(model_name, texts)
502            .await
503    }
504
505    /// Embed documents with the default model and retain actual input-bounding metadata.
506    pub async fn embed_document_batch_outcomes(
507        &self,
508        texts: &[String],
509    ) -> RuntimeResult<Vec<DocumentEmbeddingOutcome>> {
510        if texts.is_empty() {
511            return Ok(vec![]);
512        }
513        let model_name = self.default_embedder_name();
514        if model_name.is_empty() {
515            return Err(RuntimeError::Unconfigured("embedding_model".into()));
516        }
517        self.embed_document_batch_with_model_outcomes(model_name, texts)
518            .await
519    }
520
521    /// Embed a batch of queries for retrieval using the named model.
522    ///
523    /// Applies the same pre-0.6 query-role compatibility behavior as
524    /// [`Self::embed_query_with_model`].
525    ///
526    /// Returns `UnknownModel` if `model_name` is not registered.
527    pub async fn embed_query_batch_with_model(
528        &self,
529        model_name: &str,
530        texts: &[String],
531    ) -> RuntimeResult<Vec<Vec<f32>>> {
532        if texts.is_empty() {
533            return Ok(vec![]);
534        }
535        let model = parse_embedding_model_alias(model_name);
536        let service = self.embedder(model_name).await?;
537        let emb_model = model.unwrap_or_default();
538        let out = match emb_model {
539            EmbeddingModel::BgeSmallEnV15
540            | EmbeddingModel::BgeBaseEnV15
541            | EmbeddingModel::BgeLargeEnV15 => service.embed(texts, emb_model).await,
542            _ => service.embed_query(texts, emb_model).await,
543        };
544        crate::usage::count(crate::usage::UsageUnit::EmbedCalls, texts.len() as u64);
545        Ok(out?)
546    }
547
548    /// Search vectors using either a caller-provided embedding or query text.
549    ///
550    /// Existing callers pass `query_embedding: Some(vec)` to avoid re-embedding.
551    /// Text callers pass `query_embedding: None, query_text: Some(...)` and the
552    /// runtime embeds internally.
553    pub async fn vector_search(
554        &self,
555        token: &NamespaceToken,
556        query_embedding: Option<Vec<f32>>,
557        query_text: Option<&str>,
558        top_k: u32,
559        kind: Option<SubstrateKind>,
560    ) -> RuntimeResult<Vec<VectorSearchHit>> {
561        let embedding = match query_embedding {
562            Some(vec) => vec,
563            None => {
564                let text = query_text.ok_or_else(|| {
565                    RuntimeError::InvalidInput(
566                        "vector search requires query_embedding or query_text".into(),
567                    )
568                })?;
569                if text.trim().is_empty() {
570                    return Err(RuntimeError::InvalidInput(
571                        "query_text must not be empty".into(),
572                    ));
573                }
574                self.embed_query_for_token(token, text).await?
575            }
576        };
577
578        let ns = token.namespace().as_str().to_owned();
579        let hits = self
580            .vectors(token)?
581            .search(VectorSearchRequest {
582                query_vectors: vec![embedding],
583                top_k,
584                namespace: Some(ns),
585                kind,
586                embedding_model: None,
587                filter: None,
588                backend_hints: None,
589            })
590            .await;
591        crate::usage::count(crate::usage::UsageUnit::VectorPasses, 1);
592        Ok(hits?)
593    }
594
595    /// Hybrid search: text (FTS5) + vector retrieval fused via Reciprocal Rank Fusion.
596    ///
597    /// - Always performs text search over `query_text`.
598    /// - If `query_vector` is `Some`, also performs vector search and fuses both lists.
599    /// - If `None`, returns text-only results — no vector store needed.
600    /// - If `entity_kind` is `Some`, the alive-set query filters to that kind.
601    ///   The text/vector candidate pools are unfiltered up front; the kind
602    ///   filter applies at the alive-check stage where we already fetch each
603    ///   candidate to confirm it isn't soft-deleted.
604    /// - `tags_any`: when non-empty, only entities that have at least one of these
605    ///   tags (case-insensitive) survive the alive-set intersection. Applied BEFORE
606    ///   truncation so matches ranked beyond `limit` in the raw fusion are not lost.
607    /// - `properties_filter`: when `Some`, only entities whose properties are a
608    ///   superset of the given JSON object survive. Applied BEFORE truncation.
609    ///
610    /// `limit` caps the final returned list; internally pulls `limit * 4` candidates per path.
611    ///
612    /// # Cross-namespace visibility (entity search — primary namespace only; deferred)
613    ///
614    /// Both the **FTS leg** and the **vector/ANN leg** of entity search (`hybrid_search`)
615    /// are restricted to the **primary namespace only**.
616    ///
617    /// Rationale: each namespace owns a separate FTS table (`fts_entities_{ns}`)
618    /// and a separate ANN index instance. Cross-namespace entity-search fanout
619    /// requires iterating over every visible namespace's store, issuing parallel
620    /// search requests, and fusing the results: this is deferred.
621    ///
622    /// Note: this is distinct from `memory.recall`'s cross-namespace fanout, which
623    /// already iterates `visible_namespaces` across both the FTS and vector legs.
624    /// Entity search fanout is the remaining deferred piece; memory recall fanout
625    /// is not deferred.
626    ///
627    /// The `visible_ns` list is forwarded in the `TextFilter.namespaces` field,
628    /// which limits results to those namespaces within the primary store. Because
629    /// entities from extra namespaces live in their own FTS tables, this filter has
630    /// no cross-namespace effect today.
631    ///
632    /// Callers with a multi-namespace visible set can READ cross-namespace entities
633    /// directly via `get_entity` / `resolve`, but `hybrid_search` returns only
634    /// primary-namespace hits until entity-search cross-namespace fanout ships.
635    #[allow(clippy::too_many_arguments)]
636    pub async fn hybrid_search(
637        &self,
638        token: &NamespaceToken,
639        query_text: &str,
640        query_vector: Option<Vec<f32>>,
641        limit: u32,
642        entity_kind: Option<&str>,
643        entity_type: Option<&str>,
644        tags_any: &[String],
645        properties_filter: Option<&serde_json::Value>,
646    ) -> RuntimeResult<Vec<SearchHit>> {
647        self.hybrid_search_inner(
648            token,
649            query_text,
650            query_vector,
651            limit,
652            entity_kind,
653            entity_type,
654            tags_any,
655            properties_filter,
656            None,
657        )
658        .await
659    }
660
661    /// `vector_similarity_floor` is a cosine-similarity value in `[-1.0,
662    /// 1.0]`, matching both the canonical vector-store score contract and the
663    /// scale documented on the `resolve` verb and on
664    /// `SEARCH_VECTOR_SIMILARITY_FLOOR`.
665    #[allow(clippy::too_many_arguments)]
666    pub(crate) async fn hybrid_search_with_vector_similarity_floor(
667        &self,
668        token: &NamespaceToken,
669        query_text: &str,
670        query_vector: Option<Vec<f32>>,
671        limit: u32,
672        entity_kind: Option<&str>,
673        entity_type: Option<&str>,
674        tags_any: &[String],
675        properties_filter: Option<&serde_json::Value>,
676        vector_similarity_floor: f64,
677    ) -> RuntimeResult<Vec<SearchHit>> {
678        self.hybrid_search_inner(
679            token,
680            query_text,
681            query_vector,
682            limit,
683            entity_kind,
684            entity_type,
685            tags_any,
686            properties_filter,
687            Some(vector_similarity_floor),
688        )
689        .await
690    }
691
692    #[allow(clippy::too_many_arguments)]
693    async fn hybrid_search_inner(
694        &self,
695        token: &NamespaceToken,
696        query_text: &str,
697        query_vector: Option<Vec<f32>>,
698        limit: u32,
699        entity_kind: Option<&str>,
700        entity_type: Option<&str>,
701        tags_any: &[String],
702        properties_filter: Option<&serde_json::Value>,
703        vector_similarity_floor: Option<f64>,
704    ) -> RuntimeResult<Vec<SearchHit>> {
705        let candidates = limit.saturating_mul(CANDIDATE_MULTIPLIER).max(limit);
706
707        let visible_ns: Vec<String> = token
708            .visible_namespaces()
709            .iter()
710            .map(|ns| ns.as_str().to_owned())
711            .collect();
712        // sanitize_fts5_query strips known-unsafe FTS5 metacharacters up front, but if
713        // the lexical leg still errors at runtime on residual punctuation the sanitizer
714        // doesn't strip, this fails loud instead of degrading to vector-only fusion.
715        let text_search_result = self
716            .text(token)?
717            .search(TextSearchRequest {
718                query: query_text.to_string(),
719                mode: TextQueryMode::Plain,
720                filter: Some(TextFilter {
721                    namespaces: visible_ns.clone(),
722                    ..TextFilter::default()
723                }),
724                top_k: candidates,
725                snippet_chars: 200,
726            })
727            .await;
728        // FtsPasses is counted inside the store's `search()` (khive-db
729        // stores/text.rs), only once a real FTS5 statement is prepared —
730        // an empty/fully-sanitized query short-circuits there before any
731        // statement exists and must not count.
732        let text_hits = crate::error::fts_text_leg_or_err(
733            text_search_result.map_err(RuntimeError::from),
734            "hybrid_search",
735            query_text,
736        )?;
737
738        let mut vector_hits = if query_vector.is_some() || self.config().embedding_model.is_some() {
739            self.vector_search(
740                token,
741                query_vector,
742                Some(query_text),
743                candidates,
744                Some(SubstrateKind::Entity),
745            )
746            .await?
747        } else {
748            Vec::new()
749        };
750        if let Some(cosine_floor) = vector_similarity_floor {
751            // Vector store scores use canonical cosine similarity (`1 - distance`),
752            // so the caller's raw-cosine floor is already on the comparison scale.
753            let score_floor = DeterministicScore::from_f64(cosine_floor);
754            vector_hits.retain(|hit| hit.score >= score_floor);
755        }
756
757        // Each arm fetched `candidates` independently, so their union can contain
758        // twice that many distinct IDs. Keep the complete fetched pool through
759        // ranking and the alive/kind/tag/property filters below; reusing one arm's
760        // cap here lets stale or filtered hits hide live candidates from the other.
761        let fusion_limit = text_hits.len().saturating_add(vector_hits.len());
762        let mut fused = rrf_fuse(text_hits, vector_hits, fusion_limit, query_text);
763
764        // tags_any has a SQL column and is pushed into query_entities; properties
765        // filtering has no SQL column and is applied in Rust below on the fetched records.
766        if !fused.is_empty() {
767            let candidate_ids: Vec<Uuid> = fused.iter().map(|h| h.entity_id).collect();
768            let alive_page = self
769                .entities(token)?
770                .query_entities(
771                    token.namespace().as_str(),
772                    EntityFilter {
773                        ids: candidate_ids,
774                        kinds: entity_kind.map(|k| vec![k.to_string()]).unwrap_or_default(),
775                        entity_types: entity_type.map(|t| vec![t.to_string()]).unwrap_or_default(),
776                        namespaces: visible_ns,
777                        tags_any: tags_any.to_vec(),
778                        ..EntityFilter::default()
779                    },
780                    PageRequest {
781                        offset: 0,
782                        limit: u32::try_from(fused.len()).unwrap_or(u32::MAX),
783                    },
784                )
785                .await?;
786            let mut entity_meta: HashMap<Uuid, (String, Option<String>)> = HashMap::new();
787            let mut alive: HashSet<Uuid> = HashSet::new();
788            for e in alive_page.items {
789                // Drop non-matching candidates here, before the alive set is built,
790                // so they're excluded ahead of truncation.
791                if let Some(pf) = properties_filter {
792                    if !entity_props_match(e.properties.as_ref(), pf) {
793                        continue;
794                    }
795                }
796                alive.insert(e.id);
797                entity_meta.insert(e.id, (e.name, e.description));
798            }
799
800            fused.retain(|h| alive.contains(&h.entity_id));
801
802            // Enrich vector-only hits (title/snippet == None) from entity record.
803            for hit in &mut fused {
804                if let Some((name, description)) = entity_meta.get(&hit.entity_id) {
805                    if hit.title.is_none() {
806                        hit.title = Some(name.clone());
807                    }
808                    if hit.snippet.is_none() {
809                        hit.snippet = description.clone();
810                    }
811                }
812            }
813        }
814
815        fused.truncate(limit as usize);
816        Ok(fused)
817    }
818
819    /// Exact KNN over the full namespace's vector store.
820    ///
821    /// sqlite-vec uses brute-force cosine — results are exact, not approximate.
822    /// Cost is O(N · D) per query. For small-to-medium namespaces (~hundreds of
823    /// thousands of vectors) this is well within latency budgets.
824    pub async fn knn(
825        &self,
826        token: &NamespaceToken,
827        query_vector: Vec<f32>,
828        top_k: u32,
829    ) -> RuntimeResult<Vec<VectorSearchHit>> {
830        let ns = token.namespace().as_str().to_owned();
831        Ok(self
832            .vectors(token)?
833            .search(VectorSearchRequest {
834                query_vectors: vec![query_vector],
835                top_k,
836                namespace: Some(ns),
837                kind: Some(SubstrateKind::Entity),
838                embedding_model: None,
839                filter: None,
840                backend_hints: None,
841            })
842            .await?)
843    }
844
845    /// Exact KNN restricted to a candidate set.
846    ///
847    /// Useful for reranking the top-N results from `hybrid_search` (or any other
848    /// retrieval path) with exact cosine similarity against a query vector.
849    /// Returns hits sorted by similarity (highest first), truncated to `top_k`.
850    pub async fn rerank(
851        &self,
852        token: &NamespaceToken,
853        query_vector: &[f32],
854        candidate_ids: &[Uuid],
855        top_k: u32,
856    ) -> RuntimeResult<Vec<VectorSearchHit>> {
857        let candidate_set: HashSet<Uuid> = candidate_ids.iter().copied().collect();
858        let ns = token.namespace().as_str().to_owned();
859        let all_hits = self
860            .vectors(token)?
861            .search(VectorSearchRequest {
862                query_vectors: vec![query_vector.to_vec()],
863                top_k: candidate_ids.len() as u32,
864                namespace: Some(ns),
865                kind: Some(SubstrateKind::Entity),
866                embedding_model: None,
867                filter: None,
868                backend_hints: None,
869            })
870            .await?;
871        let mut hits: Vec<VectorSearchHit> = all_hits
872            .into_iter()
873            .filter(|h| candidate_set.contains(&h.subject_id))
874            .collect();
875        hits.sort_by_key(|hit| std::cmp::Reverse(hit.score));
876        hits.truncate(top_k as usize);
877        Ok(hits)
878    }
879
880    /// Backfill vector and FTS index entries for entities and notes that are missing them.
881    ///
882    /// Intended to run once at startup as a background task (warm-up sequence steps 2–4).
883    /// Queries the SQL substrate for entity descriptions and note contents that have no
884    /// corresponding entry in the vector store for any registered embedding model, then
885    /// embeds and inserts them. FTS entries missing for notes are also repopulated.
886    ///
887    /// The operation is best-effort: individual embed/insert failures are logged and
888    /// skipped rather than aborting the whole backfill. If no embedding models are
889    /// registered, returns immediately with 0.
890    ///
891    /// Returns the total number of records backfilled across all models.
892    pub async fn backfill_missing_embeddings(&self, token: &NamespaceToken) -> RuntimeResult<u64> {
893        use khive_storage::types::{SqlRow, SqlStatement, SqlValue};
894
895        let model_names = self.registered_embedding_model_names();
896        if model_names.is_empty() {
897            tracing::debug!(
898                "backfill_missing_embeddings: no embedding models registered, skipping"
899            );
900            return Ok(0);
901        }
902
903        let ns = token.namespace().as_str().to_string();
904        let mut total_backfilled = 0u64;
905
906        for model_name in &model_names {
907            let mut model_truncation = EmbeddingTruncationReport::default();
908            // Must match vec_model_key's naming logic.
909            let vec_table = format!("vec_{}", sanitize_key(model_name));
910
911            // --- Entities: embed description where no vector entry exists ---
912            // Each inserted row satisfies the NOT IN (SELECT subject_id FROM vec_table ...)
913            // clause going forward, so no OFFSET is needed between pages.
914            const PAGE_SIZE: usize = 500;
915            let mut entity_total = 0usize;
916            loop {
917                let entity_sql = SqlStatement {
918                    sql: format!(
919                        "SELECT id, name, description FROM entities \
920                         WHERE namespace = ?1 AND deleted_at IS NULL \
921                         AND id NOT IN (\
922                             SELECT subject_id FROM {vec_table} \
923                             WHERE namespace = ?1 AND embedding_model = ?2 \
924                         ) LIMIT {PAGE_SIZE}"
925                    ),
926                    params: vec![
927                        SqlValue::Text(ns.clone()),
928                        SqlValue::Text(model_name.clone()),
929                    ],
930                    label: Some("backfill_entities".into()),
931                };
932
933                let entity_rows: Vec<SqlRow> = {
934                    let sql = self.sql();
935                    let reader_result = sql.reader().await;
936                    #[cfg(any(test, feature = "fault-injection"))]
937                    let reader_result = if BACKFILL_READER_FAIL.with(|c| c.get()) {
938                        BACKFILL_READER_FAIL.with(|c| c.set(false));
939                        Err(khive_storage::StorageError::Pool {
940                            operation: "reader".into(),
941                            message: "injected failure".into(),
942                        })
943                    } else {
944                        reader_result
945                    };
946                    let mut reader = reader_result.map_err(RuntimeError::Storage)?;
947                    reader
948                        .query_all(entity_sql)
949                        .await
950                        .map_err(RuntimeError::Storage)?
951                };
952
953                let batch_len = entity_rows.len();
954                entity_total += batch_len;
955
956                for row in &entity_rows {
957                    let id_str = row.columns.first().and_then(|c| {
958                        if let SqlValue::Text(s) = &c.value {
959                            Some(s.clone())
960                        } else {
961                            None
962                        }
963                    });
964                    let description = row.columns.get(2).and_then(|c| {
965                        if let SqlValue::Text(s) = &c.value {
966                            Some(s.clone())
967                        } else if let SqlValue::Null = &c.value {
968                            None
969                        } else {
970                            None
971                        }
972                    });
973
974                    let (Some(id_str), Some(desc)) = (id_str, description) else {
975                        continue;
976                    };
977                    let Ok(id) = id_str.parse::<Uuid>() else {
978                        continue;
979                    };
980                    if desc.trim().is_empty() {
981                        continue;
982                    }
983
984                    match self
985                        .embed_document_with_model_outcome_for_token(token, model_name, &desc)
986                        .await
987                    {
988                        Ok(outcome) => {
989                            model_truncation.observe(&outcome);
990                            if let Ok(vs) = self.vectors_for_model(token, model_name) {
991                                match vs
992                                    .insert(
993                                        id,
994                                        SubstrateKind::Entity,
995                                        &ns,
996                                        "entity.description",
997                                        vec![outcome.vector],
998                                    )
999                                    .await
1000                                {
1001                                    Ok(()) => {
1002                                        total_backfilled += 1;
1003                                    }
1004                                    Err(e) => {
1005                                        tracing::warn!(
1006                                            id = %id, model = %model_name,
1007                                            error = %e,
1008                                            "backfill_missing_embeddings: entity vector insert failed"
1009                                        );
1010                                    }
1011                                }
1012                            }
1013                        }
1014                        Err(e) => {
1015                            tracing::warn!(
1016                                id = %id, model = %model_name,
1017                                error = %e,
1018                                "backfill_missing_embeddings: entity embed failed"
1019                            );
1020                        }
1021                    }
1022                }
1023
1024                if batch_len < PAGE_SIZE {
1025                    break;
1026                }
1027            }
1028
1029            // --- Notes: embed content where no vector entry exists ---
1030            let text_store = self.text_for_notes(token).ok();
1031            let note_store = self.notes(token).ok();
1032            let mut note_total = 0usize;
1033            loop {
1034                // Only the id is selected here; the full Note is fetched below so
1035                // note_fts_document gets all fields and stays parity-correct.
1036                let note_sql = SqlStatement {
1037                    sql: format!(
1038                        "SELECT id FROM notes \
1039                         WHERE namespace = ?1 AND deleted_at IS NULL \
1040                         AND id NOT IN (\
1041                             SELECT subject_id FROM {vec_table} \
1042                             WHERE namespace = ?1 AND embedding_model = ?2 \
1043                         ) LIMIT {PAGE_SIZE}"
1044                    ),
1045                    params: vec![
1046                        SqlValue::Text(ns.clone()),
1047                        SqlValue::Text(model_name.clone()),
1048                    ],
1049                    label: Some("backfill_notes".into()),
1050                };
1051
1052                let note_rows: Vec<SqlRow> = {
1053                    let sql = self.sql();
1054                    let reader_result = sql.reader().await;
1055                    #[cfg(any(test, feature = "fault-injection"))]
1056                    let reader_result = if BACKFILL_READER_FAIL.with(|c| c.get()) {
1057                        BACKFILL_READER_FAIL.with(|c| c.set(false));
1058                        Err(khive_storage::StorageError::Pool {
1059                            operation: "reader".into(),
1060                            message: "injected failure".into(),
1061                        })
1062                    } else {
1063                        reader_result
1064                    };
1065                    let mut reader = reader_result.map_err(RuntimeError::Storage)?;
1066                    reader
1067                        .query_all(note_sql)
1068                        .await
1069                        .map_err(RuntimeError::Storage)?
1070                };
1071
1072                let batch_len = note_rows.len();
1073                note_total += batch_len;
1074
1075                for row in &note_rows {
1076                    let id_str = row.columns.first().and_then(|c| {
1077                        if let SqlValue::Text(s) = &c.value {
1078                            Some(s.clone())
1079                        } else {
1080                            None
1081                        }
1082                    });
1083
1084                    let Some(id_str) = id_str else {
1085                        continue;
1086                    };
1087                    let Ok(id) = id_str.parse::<Uuid>() else {
1088                        continue;
1089                    };
1090
1091                    let note = match &note_store {
1092                        Some(store) => match store.get_note(id).await {
1093                            Ok(Some(n)) => n,
1094                            _ => continue,
1095                        },
1096                        None => continue,
1097                    };
1098
1099                    if note.content.trim().is_empty() {
1100                        continue;
1101                    }
1102
1103                    // Repopulate FTS entry using the shared constructor (first model only
1104                    // to avoid N identical overwrites per note).
1105                    if model_names.first().map(|n| n.as_str()) == Some(model_name.as_str()) {
1106                        if let Some(ref ts) = text_store {
1107                            if let Err(e) = ts.upsert_document(note_fts_document(&note)).await {
1108                                tracing::warn!(id = %id, error = %e,
1109                                    "backfill_missing_embeddings: note FTS upsert failed");
1110                            }
1111                        }
1112                    }
1113
1114                    let content = note.content.clone();
1115                    match self
1116                        .embed_document_with_model_outcome_for_token(token, model_name, &content)
1117                        .await
1118                    {
1119                        Ok(outcome) => {
1120                            model_truncation.observe(&outcome);
1121                            if let Ok(vs) = self.vectors_for_model(token, model_name) {
1122                                match vs
1123                                    .insert(
1124                                        id,
1125                                        SubstrateKind::Note,
1126                                        &ns,
1127                                        "note.content",
1128                                        vec![outcome.vector],
1129                                    )
1130                                    .await
1131                                {
1132                                    Ok(()) => {
1133                                        total_backfilled += 1;
1134                                    }
1135                                    Err(e) => {
1136                                        tracing::warn!(
1137                                            id = %id, model = %model_name,
1138                                            error = %e,
1139                                            "backfill_missing_embeddings: note vector insert failed"
1140                                        );
1141                                    }
1142                                }
1143                            }
1144                        }
1145                        Err(e) => {
1146                            tracing::warn!(
1147                                id = %id, model = %model_name,
1148                                error = %e,
1149                                "backfill_missing_embeddings: note embed failed"
1150                            );
1151                        }
1152                    }
1153                }
1154
1155                if batch_len < PAGE_SIZE {
1156                    break;
1157                }
1158            }
1159
1160            tracing::info!(
1161                model = %model_name,
1162                namespace = %ns,
1163                entities = entity_total,
1164                notes = note_total,
1165                truncated = model_truncation.truncated,
1166                discarded_bytes = model_truncation.discarded_bytes,
1167                "backfill_missing_embeddings: model pass complete"
1168            );
1169        }
1170
1171        tracing::info!(
1172            namespace = %ns,
1173            total_backfilled = total_backfilled,
1174            "backfill_missing_embeddings: finished"
1175        );
1176
1177        Ok(total_backfilled)
1178    }
1179
1180    /// Sweep orphaned vector entries for all registered embedding models.
1181    ///
1182    /// A vector entry is orphaned when its `subject_id` no longer exists as a
1183    /// live row in the entity or note tables (i.e. either the row is absent or
1184    /// has `deleted_at IS NOT NULL`). Orphaned entries accumulate after
1185    /// hard-deletes because the vector store and SQL substrate are decoupled.
1186    ///
1187    /// Iterates over every registered embedding model and calls
1188    /// [`khive_storage::VectorStore::orphan_sweep`] for the token's namespace. Models whose
1189    /// backend returns [`khive_storage::StorageError::Unsupported`] are skipped without error —
1190    /// this preserves forward-compat when a newly registered model does not yet
1191    /// implement sweep.
1192    ///
1193    /// Returns the total number of vector rows deleted across all models.
1194    pub async fn sweep_orphan_vectors(
1195        &self,
1196        token: &NamespaceToken,
1197        max_delete_per_model: u32,
1198        dry_run: bool,
1199    ) -> RuntimeResult<u64> {
1200        use khive_storage::types::OrphanSweepConfig;
1201        use khive_storage::StorageError;
1202
1203        let model_names = self.registered_embedding_model_names();
1204        if model_names.is_empty() {
1205            tracing::debug!("sweep_orphan_vectors: no embedding models registered, skipping");
1206            return Ok(0);
1207        }
1208
1209        let ns = token.namespace().as_str().to_string();
1210        let mut total_deleted = 0u64;
1211
1212        for model_name in &model_names {
1213            let store = match self.vectors_for_model(token, model_name) {
1214                Ok(s) => s,
1215                Err(e) => {
1216                    tracing::warn!(
1217                        model = %model_name,
1218                        error = %e,
1219                        "sweep_orphan_vectors: failed to get vector store, skipping model"
1220                    );
1221                    continue;
1222                }
1223            };
1224
1225            let caps = store.capabilities();
1226            if !caps.supports_orphan_sweep {
1227                tracing::debug!(
1228                    model = %model_name,
1229                    "sweep_orphan_vectors: backend does not support orphan sweep, skipping"
1230                );
1231                continue;
1232            }
1233
1234            let config = OrphanSweepConfig {
1235                subject_id_allowlist: None,
1236                namespaces: vec![ns.clone()],
1237                substrate_kinds: vec![],
1238                max_delete: max_delete_per_model,
1239                dry_run,
1240            };
1241
1242            match store.orphan_sweep(&config).await {
1243                Ok(result) => {
1244                    tracing::info!(
1245                        model = %model_name,
1246                        namespace = %ns,
1247                        scanned = result.scanned,
1248                        deleted = result.deleted,
1249                        would_delete = result.would_delete,
1250                        dry_run = dry_run,
1251                        "sweep_orphan_vectors: sweep complete"
1252                    );
1253                    total_deleted += result.deleted;
1254                }
1255                Err(StorageError::Unsupported { .. }) => {
1256                    tracing::debug!(
1257                        model = %model_name,
1258                        "sweep_orphan_vectors: backend returned Unsupported, skipping"
1259                    );
1260                }
1261                Err(e) => {
1262                    tracing::warn!(
1263                        model = %model_name,
1264                        error = %e,
1265                        "sweep_orphan_vectors: sweep failed, continuing with other models"
1266                    );
1267                }
1268            }
1269        }
1270
1271        tracing::info!(
1272            namespace = %ns,
1273            total_deleted = total_deleted,
1274            dry_run = dry_run,
1275            "sweep_orphan_vectors: finished"
1276        );
1277
1278        Ok(total_deleted)
1279    }
1280}
1281
1282/// Returns `true` when `entity_props` is a superset of all key-value pairs in `filter`.
1283///
1284/// Mirrors the semantics of `khive_pack_kg::handlers::common::props_match` so that the
1285/// storage-leg predicate is identical to the handler-side post-filter.
1286fn entity_props_match(
1287    entity_props: Option<&serde_json::Value>,
1288    filter: &serde_json::Value,
1289) -> bool {
1290    let required = match filter.as_object() {
1291        Some(obj) if !obj.is_empty() => obj,
1292        _ => return true,
1293    };
1294    let actual = match entity_props.and_then(serde_json::Value::as_object) {
1295        Some(obj) => obj,
1296        None => return false,
1297    };
1298    required
1299        .iter()
1300        .all(|(k, v)| actual.get(k).is_some_and(|av| av == v))
1301}
1302
1303/// Score bonus applied when an entity's title is an exact case-insensitive match for
1304/// the query. Dominates RRF scores (~0.09–0.18 range with k=10) so that an exact
1305/// name match always ranks above any partial or semantic match.
1306const EXACT_MATCH_BOOST: f64 = 0.5;
1307
1308/// Fuse text + vector hits with Reciprocal Rank Fusion (k=10).
1309///
1310/// Entity search stays local because it uses k=10 plus exact-match boosting.
1311/// Hits in both lists get RRF scores summed. If `query_text` exactly matches
1312/// (case-insensitive) an entity's title from the text hits, a bonus of
1313/// `EXACT_MATCH_BOOST` is added to ensure exact-name matches dominate.
1314/// Sort by fused score, take top-`limit`.
1315fn rrf_fuse(
1316    text_hits: Vec<TextSearchHit>,
1317    vector_hits: Vec<VectorSearchHit>,
1318    limit: usize,
1319    query_text: &str,
1320) -> Vec<SearchHit> {
1321    #[derive(Default)]
1322    struct Bucket {
1323        score: DeterministicScore,
1324        source: Option<SearchSource>,
1325        title: Option<String>,
1326        snippet: Option<String>,
1327    }
1328
1329    let mut buckets: HashMap<Uuid, Bucket> = HashMap::new();
1330
1331    let query_lower = query_text.to_lowercase();
1332    let mut text_seen = HashSet::with_capacity(text_hits.len());
1333    for (i, hit) in text_hits.into_iter().enumerate() {
1334        if !text_seen.insert(hit.subject_id) {
1335            continue;
1336        }
1337        let rank = i + 1; // RRF is 1-indexed
1338        let entry = buckets.entry(hit.subject_id).or_default();
1339        entry.score = entry.score + rrf_score(rank, RRF_K);
1340        entry.source = Some(match entry.source {
1341            Some(SearchSource::Vector) => SearchSource::Both,
1342            _ => SearchSource::Text,
1343        });
1344        if entry.title.is_none() {
1345            // Apply exact-match boost before storing the title so we only check once.
1346            if let Some(ref title) = hit.title {
1347                if title.to_lowercase() == query_lower {
1348                    entry.score = entry.score + DeterministicScore::from_f64(EXACT_MATCH_BOOST);
1349                }
1350            }
1351            entry.title = hit.title;
1352        }
1353        if entry.snippet.is_none() {
1354            entry.snippet = hit.snippet;
1355        }
1356    }
1357
1358    let mut vector_seen = HashSet::with_capacity(vector_hits.len());
1359    for (i, hit) in vector_hits.into_iter().enumerate() {
1360        if !vector_seen.insert(hit.subject_id) {
1361            continue;
1362        }
1363        let rank = i + 1;
1364        let entry = buckets.entry(hit.subject_id).or_default();
1365        entry.score = entry.score + rrf_score(rank, RRF_K);
1366        entry.source = Some(match entry.source {
1367            Some(SearchSource::Text) => SearchSource::Both,
1368            _ => SearchSource::Vector,
1369        });
1370    }
1371
1372    let mut hits: Vec<SearchHit> = buckets
1373        .into_iter()
1374        .map(|(id, b)| SearchHit {
1375            entity_id: id,
1376            score: b.score,
1377            source: b.source.expect("each bucket gets a source"),
1378            title: b.title,
1379            snippet: b.snippet,
1380        })
1381        .collect();
1382
1383    hits.sort_by(|a, b| b.score.cmp(&a.score).then(a.entity_id.cmp(&b.entity_id)));
1384    hits.truncate(limit);
1385    hits
1386}
1387
1388#[cfg(test)]
1389mod tests {
1390    use super::*;
1391    use crate::runtime::{KhiveRuntime, NamespaceToken, RuntimeConfig};
1392    use khive_storage::types::{TextSearchHit, VectorSearchHit};
1393    use khive_types::namespace::Namespace;
1394    use lattice_embed::EmbeddingModel;
1395
1396    #[test]
1397    fn bounded_embedding_input_reserves_prefix_and_preserves_utf8() {
1398        assert_eq!(
1399            document_embedding_budget("multilingual-e5-base"),
1400            MAX_TEXT_CHARS - "passage: ".len()
1401        );
1402
1403        let input = format!("{}\u{1f980}tail", "a".repeat(MAX_TEXT_CHARS - 1));
1404        let (bounded, truncated) = bounded_embedding_input(&input, MAX_TEXT_CHARS);
1405        assert!(truncated);
1406        assert_eq!(bounded.len(), MAX_TEXT_CHARS - 1);
1407        assert!(bounded.is_char_boundary(bounded.len()));
1408        assert!(!bounded.contains('\u{1f980}'));
1409    }
1410
1411    #[test]
1412    fn bounded_embedding_input_leaves_normal_text_unchanged() {
1413        let input = "normal byte-identical embedding input";
1414        let (bounded, truncated) = bounded_embedding_input(input, MAX_TEXT_CHARS);
1415        assert!(!truncated);
1416        assert_eq!(bounded, input);
1417        assert_eq!(bounded.as_ptr(), input.as_ptr());
1418    }
1419
1420    fn text_hit(id: Uuid, rank: u32, title: &str) -> TextSearchHit {
1421        TextSearchHit {
1422            subject_id: id,
1423            score: DeterministicScore::from_f64(1.0),
1424            rank,
1425            title: Some(title.to_string()),
1426            snippet: Some("...".to_string()),
1427        }
1428    }
1429
1430    fn vector_hit(id: Uuid, rank: u32) -> VectorSearchHit {
1431        VectorSearchHit {
1432            subject_id: id,
1433            score: DeterministicScore::from_f64(0.9),
1434            rank,
1435        }
1436    }
1437
1438    #[test]
1439    fn rrf_fuse_text_only() {
1440        let a = Uuid::new_v4();
1441        let b = Uuid::new_v4();
1442        let text = vec![text_hit(a, 1, "A"), text_hit(b, 2, "B")];
1443        let hits = rrf_fuse(text, vec![], 10, "query");
1444        assert_eq!(hits.len(), 2);
1445        assert_eq!(hits[0].entity_id, a);
1446        assert_eq!(hits[0].source, SearchSource::Text);
1447        assert_eq!(hits[0].title.as_deref(), Some("A"));
1448    }
1449
1450    #[test]
1451    fn rrf_fuse_vector_only() {
1452        let a = Uuid::new_v4();
1453        let hits = rrf_fuse(vec![], vec![vector_hit(a, 1)], 10, "query");
1454        assert_eq!(hits.len(), 1);
1455        assert_eq!(hits[0].source, SearchSource::Vector);
1456        assert!(hits[0].title.is_none());
1457    }
1458
1459    #[test]
1460    fn rrf_fuse_marks_both_when_in_both_lists() {
1461        let id = Uuid::new_v4();
1462        let text = vec![text_hit(id, 1, "A")];
1463        let vec = vec![vector_hit(id, 1)];
1464        let hits = rrf_fuse(text, vec, 10, "query");
1465        assert_eq!(hits.len(), 1);
1466        assert_eq!(hits[0].source, SearchSource::Both);
1467    }
1468
1469    #[test]
1470    fn rrf_fuse_preserves_unique_leg_scores_exactly() {
1471        let text_only = Uuid::new_v4();
1472        let both = Uuid::new_v4();
1473        let vector_only = Uuid::new_v4();
1474        let text = vec![text_hit(text_only, 1, "A"), text_hit(both, 2, "B")];
1475        let vector = vec![vector_hit(both, 1), vector_hit(vector_only, 2)];
1476
1477        let hits = rrf_fuse(text, vector, 10, "query");
1478        let score_for = |id| {
1479            hits.iter()
1480                .find(|hit| hit.entity_id == id)
1481                .expect("expected fused hit")
1482                .score
1483        };
1484
1485        assert_eq!(score_for(text_only), rrf_score(1, RRF_K));
1486        assert_eq!(score_for(both), rrf_score(2, RRF_K) + rrf_score(1, RRF_K));
1487        assert_eq!(score_for(vector_only), rrf_score(2, RRF_K));
1488    }
1489
1490    #[test]
1491    fn rrf_fuse_counts_duplicate_once_per_leg() {
1492        let id = Uuid::new_v4();
1493        let text = vec![text_hit(id, 1, "A"), text_hit(id, 2, "A duplicate")];
1494        let vector = vec![vector_hit(id, 1), vector_hit(id, 2)];
1495
1496        let hits = rrf_fuse(text, vector, 10, "query");
1497
1498        assert_eq!(hits.len(), 1);
1499        assert_eq!(hits[0].source, SearchSource::Both);
1500        assert_eq!(hits[0].score, rrf_score(1, RRF_K) + rrf_score(1, RRF_K));
1501    }
1502
1503    #[test]
1504    fn rrf_fuse_respects_limit() {
1505        let hits: Vec<TextSearchHit> = (0..20)
1506            .map(|i| text_hit(Uuid::new_v4(), i + 1, "x"))
1507            .collect();
1508        let fused = rrf_fuse(hits, vec![], 5, "query");
1509        assert_eq!(fused.len(), 5);
1510    }
1511
1512    #[test]
1513    fn rrf_fuse_orders_higher_score_first() {
1514        // Same UUID in both lists at rank 1 → score 2/(10+1). Different UUIDs → 1/(10+1) each.
1515        let a = Uuid::new_v4();
1516        let b = Uuid::new_v4();
1517        let text = vec![text_hit(a, 1, "A")];
1518        let vec = vec![vector_hit(a, 1), vector_hit(b, 2)];
1519        let hits = rrf_fuse(text, vec, 10, "query");
1520        assert_eq!(hits[0].entity_id, a);
1521        assert_eq!(hits[0].source, SearchSource::Both);
1522        assert!(hits[0].score > hits[1].score);
1523    }
1524
1525    #[test]
1526    fn rrf_fuse_k10_score_spread_exceeds_threshold() {
1527        // With k=10: rank 1 → 1/11 ≈ 0.0909, rank 10 → 1/20 = 0.0500.
1528        // Spread ≈ 0.041, well above the 0.03 minimum required for reliable dedup.
1529        let ids: Vec<Uuid> = (0..10).map(|_| Uuid::new_v4()).collect();
1530        let text: Vec<TextSearchHit> = ids
1531            .iter()
1532            .enumerate()
1533            .map(|(i, &id)| text_hit(id, (i + 1) as u32, "x"))
1534            .collect();
1535        let hits = rrf_fuse(text, vec![], 10, "query");
1536        assert_eq!(hits.len(), 10);
1537        let top_score = hits[0].score.to_f64();
1538        let bottom_score = hits[9].score.to_f64();
1539        let spread = top_score - bottom_score;
1540        assert!(
1541            spread >= 0.03,
1542            "score spread {spread:.4} between rank 1 and rank 10 must be ≥ 0.03 (was {spread:.4})"
1543        );
1544    }
1545
1546    #[test]
1547    fn rrf_fuse_exact_match_boost_elevates_score() {
1548        // An entity whose title exactly matches the query should receive a score
1549        // significantly above a non-matching entity ranked first by text search.
1550        let exact_id = Uuid::new_v4();
1551        let other_id = Uuid::new_v4();
1552        // other_id ranks 1 in text, exact_id ranks 2 — but exact_id matches query.
1553        let text = vec![
1554            text_hit(other_id, 1, "something else"),
1555            text_hit(exact_id, 2, "FlashAttention"),
1556        ];
1557        let hits = rrf_fuse(text, vec![], 10, "flashattention");
1558        assert_eq!(hits.len(), 2);
1559        assert_eq!(
1560            hits[0].entity_id, exact_id,
1561            "exact match must rank first despite being rank-2 in raw text search"
1562        );
1563    }
1564
1565    // ---- embed_batch tests ----
1566
1567    #[test]
1568    fn embed_batch_unconfigured_on_memory_runtime() {
1569        // KhiveRuntime::memory() has no embedding model — embed_batch returns Unconfigured.
1570        let rt = KhiveRuntime::memory().unwrap();
1571        let result = tokio::runtime::Runtime::new()
1572            .unwrap()
1573            .block_on(rt.embed_batch(&[]));
1574        // Empty slice short-circuits before hitting the model check.
1575        assert!(result.is_ok());
1576        assert!(result.unwrap().is_empty());
1577    }
1578
1579    #[test]
1580    fn embed_batch_empty_input_returns_empty_vec() {
1581        // No model needed — empty slice is handled before the embedder is touched.
1582        let rt = KhiveRuntime::memory().unwrap();
1583        let result = tokio::runtime::Runtime::new()
1584            .unwrap()
1585            .block_on(rt.embed_batch(&[]));
1586        assert_eq!(result.unwrap(), Vec::<Vec<f32>>::new());
1587    }
1588
1589    #[test]
1590    fn embed_batch_no_model_non_empty_returns_unconfigured() {
1591        let rt = KhiveRuntime::memory().unwrap();
1592        let texts = vec!["hello".to_string()];
1593        let result = tokio::runtime::Runtime::new()
1594            .unwrap()
1595            .block_on(rt.embed_batch(&texts));
1596        match result {
1597            Err(crate::RuntimeError::Unconfigured(s)) => assert_eq!(s, "embedding_model"),
1598            Err(other) => panic!("expected Unconfigured, got {:?}", other),
1599            Ok(_) => panic!("expected Err, got Ok"),
1600        }
1601    }
1602
1603    #[test]
1604    #[ignore = "loads ~80 MB model; run with --include-ignored"]
1605    fn embed_batch_count_matches_input() {
1606        let config = RuntimeConfig {
1607            db_path: None,
1608            default_namespace: Namespace::parse("test").unwrap(),
1609            embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
1610            packs: vec!["kg".to_string()],
1611            ..RuntimeConfig::default()
1612        };
1613        let rt = KhiveRuntime::new(config).unwrap();
1614        let texts: Vec<String> = vec!["foo".to_string(), "bar".to_string(), "baz".to_string()];
1615        let result = tokio::runtime::Runtime::new()
1616            .unwrap()
1617            .block_on(rt.embed_batch(&texts));
1618        let embeddings = result.unwrap();
1619        assert_eq!(embeddings.len(), texts.len());
1620    }
1621
1622    #[test]
1623    fn vector_search_requires_embedding_or_text() {
1624        let rt = KhiveRuntime::memory().unwrap();
1625        let tok = NamespaceToken::local();
1626        let result = tokio::runtime::Runtime::new()
1627            .unwrap()
1628            .block_on(rt.vector_search(&tok, None, None, 10, Some(SubstrateKind::Entity)));
1629        match result {
1630            Err(crate::RuntimeError::InvalidInput(msg)) => {
1631                assert!(msg.contains("query_embedding or query_text"), "msg: {msg}");
1632            }
1633            other => panic!("expected InvalidInput, got {other:?}"),
1634        }
1635    }
1636
1637    #[test]
1638    fn vector_search_text_without_model_returns_unconfigured() {
1639        let rt = KhiveRuntime::memory().unwrap();
1640        let tok = NamespaceToken::local();
1641        let result = tokio::runtime::Runtime::new()
1642            .unwrap()
1643            .block_on(rt.vector_search(
1644                &tok,
1645                None,
1646                Some("attention"),
1647                10,
1648                Some(SubstrateKind::Entity),
1649            ));
1650        match result {
1651            Err(crate::RuntimeError::Unconfigured(s)) => assert_eq!(s, "embedding_model"),
1652            other => panic!("expected Unconfigured, got {other:?}"),
1653        }
1654    }
1655
1656    #[test]
1657    #[ignore = "loads ~80 MB model; run with --include-ignored"]
1658    fn embed_batch_vectors_have_expected_dimensions() {
1659        let model = EmbeddingModel::AllMiniLmL6V2;
1660        let config = RuntimeConfig {
1661            db_path: None,
1662            default_namespace: Namespace::parse("test").unwrap(),
1663            embedding_model: Some(model),
1664            packs: vec!["kg".to_string()],
1665            ..RuntimeConfig::default()
1666        };
1667        let rt = KhiveRuntime::new(config).unwrap();
1668        let texts = vec!["hello world".to_string()];
1669        let result = tokio::runtime::Runtime::new()
1670            .unwrap()
1671            .block_on(rt.embed_batch(&texts));
1672        let embeddings = result.unwrap();
1673        assert_eq!(embeddings[0].len(), model.dimensions());
1674    }
1675
1676    // ---- hybrid_search enrichment ----
1677
1678    #[tokio::test]
1679    async fn hybrid_search_entity_hit_has_title() {
1680        let rt = KhiveRuntime::memory().unwrap();
1681        let tok = NamespaceToken::local();
1682        rt.create_entity(
1683            &tok,
1684            "concept",
1685            None,
1686            "FlashAttention",
1687            Some("IO-aware exact attention using tiling"),
1688            None,
1689            vec![],
1690        )
1691        .await
1692        .unwrap();
1693
1694        let hits = rt
1695            .hybrid_search(&tok, "FlashAttention", None, 10, None, None, &[], None)
1696            .await
1697            .unwrap();
1698
1699        assert!(!hits.is_empty(), "should find the entity");
1700        let hit = &hits[0];
1701        assert!(hit.title.is_some(), "title must be populated");
1702        assert!(
1703            hit.title.as_deref().unwrap().contains("FlashAttention"),
1704            "title must contain entity name"
1705        );
1706    }
1707
1708    /// `hybrid_search` must not hard-fail on a query containing FTS5 metacharacters
1709    /// like `$` (e.g. the DSL doc query `$prev.id`). `sanitize_fts5_query` (khive-db)
1710    /// strips `$`, so this exercises the sanitizer path and takes the `Ok` arm; see
1711    /// `hybrid_search_with_residual_fts5_char_now_sanitized` below for the character
1712    /// class #916 closed (previously the fail-loud arm, prior to #916).
1713    #[tokio::test]
1714    async fn hybrid_search_with_dollar_sign_query_does_not_error() {
1715        let rt = KhiveRuntime::memory().unwrap();
1716        let tok = NamespaceToken::local();
1717        rt.create_entity(
1718            &tok,
1719            "concept",
1720            None,
1721            "DSL docs",
1722            Some("use $prev.id to chain calls"),
1723            None,
1724            vec![],
1725        )
1726        .await
1727        .unwrap();
1728
1729        let result = rt
1730            .hybrid_search(&tok, "$prev.id", None, 10, None, None, &[], None)
1731            .await;
1732
1733        assert!(
1734            result.is_ok(),
1735            "#388 hybrid_search must not hard-fail on a '$'-bearing query, got: {:?}",
1736            result.err()
1737        );
1738    }
1739
1740    /// #916: `@` was previously NOT stripped by `sanitize_fts5_query` and SQLite
1741    /// FTS5's bareword parser rejected it unconditionally, so this query used to
1742    /// reach the runtime-level fail-loud arm (`RuntimeError::InvalidInput`, #569).
1743    /// `sanitize_fts5_token_group`'s bareword-safety gate now recognizes `@` (and
1744    /// every other ASCII punctuation character not already handled) as unsafe for
1745    /// an unquoted bareword position and routes it through the quoted-phrase
1746    /// alternative instead, which FTS5 accepts literally, so the query
1747    /// now succeeds and finds the seeded content rather than erroring.
1748    #[tokio::test]
1749    async fn hybrid_search_with_residual_fts5_char_now_sanitized() {
1750        let rt = KhiveRuntime::memory().unwrap();
1751        let tok = NamespaceToken::local();
1752        rt.create_entity(
1753            &tok,
1754            "concept",
1755            None,
1756            "DSL docs",
1757            Some("use foo@bar to chain calls"),
1758            None,
1759            vec![],
1760        )
1761        .await
1762        .unwrap();
1763
1764        let result = rt
1765            .hybrid_search(&tok, "foo@bar", None, 10, None, None, &[], None)
1766            .await;
1767
1768        let hits = result.unwrap_or_else(|e| {
1769            panic!("#916 hybrid_search must not fail on an '@'-bearing query, got: {e:?}")
1770        });
1771        assert!(
1772            !hits.is_empty(),
1773            "#916 '@'-bearing query must still find the seeded 'foo@bar' content via the \
1774             quoted-phrase alternative"
1775        );
1776    }
1777
1778    /// #916 end-to-end regression, using the exact character classes from the
1779    /// issue's live-log evidence (`#682 Stage 2`, `Min-K%Prob`, `B=128`):
1780    /// `hybrid_search`'s FTS leg must not lose its lexical signal to a parser
1781    /// syntax error on `#`, `%`, or `=`. Each query below must both succeed
1782    /// and actually surface a `Text`/`Both`-sourced hit, proving the FTS leg
1783    /// contributed, not just that the vector leg papered over a degraded
1784    /// text leg.
1785    #[tokio::test]
1786    async fn hybrid_search_with_916_issue_characters_finds_text_leg_hits() {
1787        let rt = KhiveRuntime::memory().unwrap();
1788        let tok = NamespaceToken::local();
1789
1790        rt.create_entity(
1791            &tok,
1792            "concept",
1793            None,
1794            "issue tracker",
1795            Some("tracking #682 Stage 2: MoE expert-cache prefetch work"),
1796            None,
1797            vec![],
1798        )
1799        .await
1800        .unwrap();
1801        rt.create_entity(
1802            &tok,
1803            "concept",
1804            None,
1805            "benchmark notes",
1806            Some("chunkwise B=128 traffic arithmetic simdgroup_matrix DPLR"),
1807            None,
1808            vec![],
1809        )
1810        .await
1811        .unwrap();
1812        rt.create_entity(
1813            &tok,
1814            "concept",
1815            None,
1816            "sampling notes",
1817            Some("evaluated with the Min-K%Prob membership inference method"),
1818            None,
1819            vec![],
1820        )
1821        .await
1822        .unwrap();
1823
1824        for query in ["#682 Stage 2", "B=128", "Min-K%Prob"] {
1825            let result = rt
1826                .hybrid_search(&tok, query, None, 10, None, None, &[], None)
1827                .await;
1828            let hits = result.unwrap_or_else(|e| {
1829                panic!("#916 hybrid_search must not fail on query {query:?}, got: {e:?}")
1830            });
1831            assert!(
1832                hits.iter()
1833                    .any(|h| matches!(h.source, SearchSource::Text | SearchSource::Both)),
1834                "#916 query {query:?} must surface a Text/Both-sourced hit \
1835                 (the FTS leg must contribute, not just the vector leg); got {hits:?}"
1836            );
1837        }
1838    }
1839
1840    // ---- predicate pushdown before truncation ----
1841
1842    /// Entity-branch tag-filter regression.
1843    ///
1844    /// Scenario: `limit=1`, tag_filter=["target-tag"]. Two entities are inserted:
1845    ///   - "decoy_alpha_beta_gamma": many query tokens → ranks 1 in FTS (dominates).
1846    ///     Does NOT have "target-tag".
1847    ///   - "alpha_beta_gamma target": fewer query tokens → ranks 2 in FTS.
1848    ///     HAS "target-tag".
1849    ///
1850    /// Without predicate pushdown, `fused.truncate(1)` keeps only the decoy and the
1851    /// tag-matching entity is invisible: this requires `tags_any` to be passed into
1852    /// `query_entities`'s `EntityFilter` so the decoy is excluded before truncation.
1853    #[tokio::test]
1854    async fn hybrid_search_tag_filter_pushed_before_truncation() {
1855        let rt = KhiveRuntime::memory().unwrap();
1856        let tok = NamespaceToken::local();
1857
1858        // Decoy: high-ranking FTS hit (content repeats query words), no target tag.
1859        rt.create_entity(
1860            &tok,
1861            "concept",
1862            None,
1863            "alpha beta gamma decoy alpha beta gamma",
1864            Some("alpha beta gamma decoy description alpha beta gamma"),
1865            None,
1866            vec!["other-tag".to_string()],
1867        )
1868        .await
1869        .unwrap();
1870
1871        // Target: lower-ranking FTS hit, has the tag we filter on.
1872        let target = rt
1873            .create_entity(
1874                &tok,
1875                "concept",
1876                None,
1877                "alpha beta gamma target",
1878                Some("alpha beta gamma target description"),
1879                None,
1880                vec!["target-tag".to_string()],
1881            )
1882            .await
1883            .unwrap();
1884
1885        // With limit=1 and tag_filter, the fix must return the target entity despite
1886        // the decoy ranking higher. Without pushdown, the decoy occupies the single
1887        // slot and the target is silently dropped.
1888        let hits = rt
1889            .hybrid_search(
1890                &tok,
1891                "alpha beta gamma",
1892                None,
1893                1,
1894                None,
1895                None,
1896                &["target-tag".to_string()],
1897                None,
1898            )
1899            .await
1900            .unwrap();
1901
1902        assert_eq!(
1903            hits.len(),
1904            1,
1905            "exactly one hit expected (the tag-matching entity)"
1906        );
1907        assert_eq!(
1908            hits[0].entity_id, target.id,
1909            "the tag-filtered entity must be returned even when ranked below limit in raw fusion"
1910        );
1911    }
1912
1913    /// Entity-branch properties-filter regression (analogous to the tag-filter test above).
1914    ///
1915    /// Scenario: `limit=1`, properties_filter={{"domain": "target"}}. Two entities:
1916    ///   - decoy: high FTS rank, properties {{"domain": "other"}}.
1917    ///   - target: lower FTS rank, properties {{"domain": "target"}}.
1918    ///
1919    /// Without pushdown: decoy fills the slot, target is dropped. With pushdown:
1920    /// only the target survives the properties filter before truncation.
1921    #[tokio::test]
1922    async fn hybrid_search_props_filter_pushed_before_truncation() {
1923        let rt = KhiveRuntime::memory().unwrap();
1924        let tok = NamespaceToken::local();
1925
1926        rt.create_entity(
1927            &tok,
1928            "concept",
1929            None,
1930            "delta epsilon zeta decoy delta epsilon zeta",
1931            Some("delta epsilon zeta decoy description delta epsilon zeta"),
1932            Some(serde_json::json!({"domain": "other"})),
1933            vec![],
1934        )
1935        .await
1936        .unwrap();
1937
1938        let target = rt
1939            .create_entity(
1940                &tok,
1941                "concept",
1942                None,
1943                "delta epsilon zeta target",
1944                Some("delta epsilon zeta target description"),
1945                Some(serde_json::json!({"domain": "target"})),
1946                vec![],
1947            )
1948            .await
1949            .unwrap();
1950
1951        let filter = serde_json::json!({"domain": "target"});
1952        let hits = rt
1953            .hybrid_search(
1954                &tok,
1955                "delta epsilon zeta",
1956                None,
1957                1,
1958                None,
1959                None,
1960                &[],
1961                Some(&filter),
1962            )
1963            .await
1964            .unwrap();
1965
1966        assert_eq!(hits.len(), 1, "exactly one hit expected (properties match)");
1967        assert_eq!(
1968            hits[0].entity_id, target.id,
1969            "the properties-filtered entity must be returned even when ranked below limit"
1970        );
1971    }
1972
1973    // ---- embed intent tests ----
1974
1975    struct CapturingEmbeddingService {
1976        captured: std::sync::Arc<std::sync::Mutex<Vec<Vec<String>>>>,
1977    }
1978
1979    #[async_trait::async_trait]
1980    impl EmbeddingService for CapturingEmbeddingService {
1981        async fn embed(
1982            &self,
1983            texts: &[String],
1984            _model: EmbeddingModel,
1985        ) -> std::result::Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
1986            self.captured.lock().unwrap().push(texts.to_vec());
1987            Ok(texts.iter().map(|_| vec![1.0]).collect())
1988        }
1989
1990        fn supports_model(&self, _model: EmbeddingModel) -> bool {
1991            true
1992        }
1993
1994        fn name(&self) -> &'static str {
1995            "capturing-embedding-service"
1996        }
1997    }
1998
1999    struct CapturingEmbedderProvider {
2000        name: String,
2001        captured: std::sync::Arc<std::sync::Mutex<Vec<Vec<String>>>>,
2002    }
2003
2004    struct WrongCardinalityEmbeddingService;
2005
2006    #[async_trait::async_trait]
2007    impl EmbeddingService for WrongCardinalityEmbeddingService {
2008        async fn embed(
2009            &self,
2010            texts: &[String],
2011            _model: EmbeddingModel,
2012        ) -> std::result::Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
2013            Ok(texts
2014                .iter()
2015                .take(texts.len().saturating_sub(1))
2016                .map(|_| vec![1.0])
2017                .collect())
2018        }
2019
2020        fn supports_model(&self, _model: EmbeddingModel) -> bool {
2021            true
2022        }
2023
2024        fn name(&self) -> &'static str {
2025            "wrong-cardinality-embedding-service"
2026        }
2027    }
2028
2029    struct WrongCardinalityEmbedderProvider;
2030
2031    #[async_trait::async_trait]
2032    impl EmbedderProvider for WrongCardinalityEmbedderProvider {
2033        fn name(&self) -> &str {
2034            "wrong-cardinality-embedding-service"
2035        }
2036
2037        fn dimensions(&self) -> usize {
2038            1
2039        }
2040
2041        async fn build(&self) -> crate::error::RuntimeResult<std::sync::Arc<dyn EmbeddingService>> {
2042            Ok(std::sync::Arc::new(WrongCardinalityEmbeddingService))
2043        }
2044    }
2045
2046    struct SurplusCardinalityEmbeddingService;
2047
2048    #[async_trait::async_trait]
2049    impl EmbeddingService for SurplusCardinalityEmbeddingService {
2050        async fn embed(
2051            &self,
2052            texts: &[String],
2053            _model: EmbeddingModel,
2054        ) -> std::result::Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
2055            let mut vectors: Vec<Vec<f32>> = texts.iter().map(|_| vec![1.0]).collect();
2056            vectors.push(vec![1.0]);
2057            Ok(vectors)
2058        }
2059
2060        fn supports_model(&self, _model: EmbeddingModel) -> bool {
2061            true
2062        }
2063
2064        fn name(&self) -> &'static str {
2065            "surplus-cardinality-embedding-service"
2066        }
2067    }
2068
2069    struct SurplusCardinalityEmbedderProvider;
2070
2071    #[async_trait::async_trait]
2072    impl EmbedderProvider for SurplusCardinalityEmbedderProvider {
2073        fn name(&self) -> &str {
2074            "surplus-cardinality-embedding-service"
2075        }
2076
2077        fn dimensions(&self) -> usize {
2078            1
2079        }
2080
2081        async fn build(&self) -> crate::error::RuntimeResult<std::sync::Arc<dyn EmbeddingService>> {
2082            Ok(std::sync::Arc::new(SurplusCardinalityEmbeddingService))
2083        }
2084    }
2085
2086    #[async_trait::async_trait]
2087    impl EmbedderProvider for CapturingEmbedderProvider {
2088        fn name(&self) -> &str {
2089            &self.name
2090        }
2091
2092        fn dimensions(&self) -> usize {
2093            1
2094        }
2095
2096        async fn build(&self) -> crate::error::RuntimeResult<std::sync::Arc<dyn EmbeddingService>> {
2097            Ok(std::sync::Arc::new(CapturingEmbeddingService {
2098                captured: std::sync::Arc::clone(&self.captured),
2099            }))
2100        }
2101    }
2102
2103    fn runtime_with_capturing_embedder(
2104        model: EmbeddingModel,
2105    ) -> (
2106        KhiveRuntime,
2107        std::sync::Arc<std::sync::Mutex<Vec<Vec<String>>>>,
2108    ) {
2109        let runtime = KhiveRuntime::memory().unwrap();
2110        let captured = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
2111        runtime.register_embedder(CapturingEmbedderProvider {
2112            name: model.to_string(),
2113            captured: std::sync::Arc::clone(&captured),
2114        });
2115        (runtime, captured)
2116    }
2117
2118    #[tokio::test]
2119    async fn bge_query_paths_pass_raw_unprefixed_text() {
2120        const BGE_QUERY_INSTRUCTION: &str =
2121            "Represent this sentence for searching relevant passages: ";
2122        let single = "single raw query";
2123        let batch = vec![
2124            "first raw query".to_string(),
2125            "second raw query".to_string(),
2126        ];
2127
2128        for model in [
2129            EmbeddingModel::BgeSmallEnV15,
2130            EmbeddingModel::BgeBaseEnV15,
2131            EmbeddingModel::BgeLargeEnV15,
2132        ] {
2133            let (runtime, captured) = runtime_with_capturing_embedder(model);
2134            runtime
2135                .embed_query_with_model(&model.to_string(), single)
2136                .await
2137                .unwrap();
2138            runtime
2139                .embed_query_batch_with_model(&model.to_string(), &batch)
2140                .await
2141                .unwrap();
2142
2143            let calls = captured.lock().unwrap().clone();
2144            assert_eq!(
2145                calls,
2146                vec![vec![single.to_string()], batch.clone()],
2147                "{model} must receive raw query text through single and batch paths"
2148            );
2149            assert!(
2150                calls
2151                    .iter()
2152                    .flatten()
2153                    .all(|text| !text.contains(BGE_QUERY_INSTRUCTION)),
2154                "{model} must not receive the BGE retrieval instruction"
2155            );
2156        }
2157    }
2158
2159    #[tokio::test]
2160    async fn e5_query_paths_apply_query_prefix() {
2161        let model = EmbeddingModel::MultilingualE5Small;
2162        let single = "single raw query";
2163        let batch = vec![
2164            "first raw query".to_string(),
2165            "second raw query".to_string(),
2166        ];
2167        let (runtime, captured) = runtime_with_capturing_embedder(model);
2168
2169        runtime
2170            .embed_query_with_model(&model.to_string(), single)
2171            .await
2172            .unwrap();
2173        runtime
2174            .embed_query_batch_with_model(&model.to_string(), &batch)
2175            .await
2176            .unwrap();
2177
2178        assert_eq!(
2179            captured.lock().unwrap().as_slice(),
2180            [
2181                vec!["query: single raw query".to_string()],
2182                vec![
2183                    "query: first raw query".to_string(),
2184                    "query: second raw query".to_string(),
2185                ],
2186            ],
2187            "E5 must receive its query prefix through single and batch paths"
2188        );
2189    }
2190
2191    #[tokio::test]
2192    async fn mixed_document_batch_stays_one_ordered_provider_call() {
2193        let model = EmbeddingModel::AllMiniLmL6V2;
2194        let (runtime, captured) = runtime_with_capturing_embedder(model);
2195        let texts = vec![
2196            "first normal document".to_string(),
2197            "x".repeat(MAX_TEXT_CHARS + 1),
2198            "second normal document".to_string(),
2199        ];
2200
2201        let outcomes = runtime
2202            .embed_document_batch_with_model_outcomes(&model.to_string(), &texts)
2203            .await
2204            .expect("mixed batch must embed");
2205        assert_eq!(outcomes.len(), texts.len());
2206        assert!(!outcomes[0].truncated);
2207        assert_eq!(outcomes[0].source_bytes, outcomes[0].embedded_bytes);
2208        assert!(outcomes[1].truncated);
2209        assert_eq!(outcomes[1].source_bytes, MAX_TEXT_CHARS + 1);
2210        assert_eq!(outcomes[1].embedded_bytes, MAX_TEXT_CHARS);
2211        assert!(!outcomes[2].truncated);
2212        assert_eq!(
2213            captured.lock().unwrap().as_slice(),
2214            [vec![
2215                texts[0].clone(),
2216                "x".repeat(MAX_TEXT_CHARS),
2217                texts[2].clone(),
2218            ]]
2219        );
2220    }
2221
2222    #[tokio::test]
2223    async fn truncated_document_batch_rejects_provider_cardinality_mismatch() {
2224        let runtime = KhiveRuntime::memory().unwrap();
2225        runtime.register_embedder(WrongCardinalityEmbedderProvider);
2226        let model_name = "wrong-cardinality-embedding-service";
2227        let texts = vec!["x".repeat(MAX_TEXT_CHARS + 1), "normal".to_string()];
2228
2229        let error = runtime
2230            .embed_document_batch_with_model_outcomes(model_name, &texts)
2231            .await
2232            .expect_err("provider cardinality mismatch must fail the whole batch");
2233
2234        assert!(
2235            error
2236                .to_string()
2237                .contains("embed_passage returned 1 vectors for 2 inputs"),
2238            "unexpected error: {error}"
2239        );
2240    }
2241
2242    #[tokio::test]
2243    async fn singleton_document_embed_rejects_zero_vectors() {
2244        let runtime = KhiveRuntime::memory().unwrap();
2245        runtime.register_embedder(WrongCardinalityEmbedderProvider);
2246        let model_name = "wrong-cardinality-embedding-service";
2247
2248        let error = runtime
2249            .embed_document_with_model_outcome(model_name, "single document")
2250            .await
2251            .expect_err("provider returning zero vectors must fail closed");
2252
2253        assert!(
2254            error
2255                .to_string()
2256                .contains("embed_passage returned 0 vectors for 1 input"),
2257            "unexpected error: {error}"
2258        );
2259    }
2260
2261    #[tokio::test]
2262    async fn singleton_document_embed_rejects_surplus_vectors() {
2263        let runtime = KhiveRuntime::memory().unwrap();
2264        runtime.register_embedder(SurplusCardinalityEmbedderProvider);
2265        let model_name = "surplus-cardinality-embedding-service";
2266
2267        let error = runtime
2268            .embed_document_with_model_outcome(model_name, "single document")
2269            .await
2270            .expect_err("provider returning surplus vectors must fail closed");
2271
2272        assert!(
2273            error
2274                .to_string()
2275                .contains("embed_passage returned 2 vectors for 1 input"),
2276            "unexpected error: {error}"
2277        );
2278    }
2279
2280    #[test]
2281    #[ignore = "loads ~80 MB model; run with --include-ignored"]
2282    fn minilm_document_and_query_embed_are_identical_no_prefix_model() {
2283        // MiniLM has no instruction prefixes; document and query paths must
2284        // produce byte-identical vectors so that existing stored vectors remain
2285        // comparable after this change.
2286        let model = EmbeddingModel::AllMiniLmL6V2;
2287        let config = RuntimeConfig {
2288            db_path: None,
2289            default_namespace: Namespace::parse("test").unwrap(),
2290            embedding_model: Some(model),
2291            packs: vec!["kg".to_string()],
2292            ..RuntimeConfig::default()
2293        };
2294        let rt = KhiveRuntime::new(config).unwrap();
2295        let text = "attention is all you need".to_string();
2296        let rt_ref = &rt;
2297        let (doc_emb, query_emb) = tokio::runtime::Runtime::new().unwrap().block_on(async {
2298            let d = rt_ref
2299                .embed_document_with_model(&model.to_string(), &text)
2300                .await
2301                .unwrap();
2302            let q = rt_ref
2303                .embed_query_with_model(&model.to_string(), &text)
2304                .await
2305                .unwrap();
2306            (d, q)
2307        });
2308        assert_eq!(
2309            doc_emb, query_emb,
2310            "MiniLM has no instruction prefix: document and query embeds must be identical"
2311        );
2312    }
2313
2314    #[test]
2315    #[ignore = "loads multilingual-e5-small (~90 MB); run with --include-ignored"]
2316    fn e5_document_and_query_embed_differ_instruction_tuned_model() {
2317        // multilingual-e5 prepends "passage: " for documents and "query: " for
2318        // queries. The same raw text must produce different embeddings when the
2319        // correct prefixes are applied, confirming the asymmetric-retrieval
2320        // capability is now exercised.
2321        let model = EmbeddingModel::MultilingualE5Small;
2322        let config = RuntimeConfig {
2323            db_path: None,
2324            default_namespace: Namespace::parse("test").unwrap(),
2325            embedding_model: Some(model),
2326            packs: vec!["kg".to_string()],
2327            ..RuntimeConfig::default()
2328        };
2329        let rt = KhiveRuntime::new(config).unwrap();
2330        let text = "attention is all you need".to_string();
2331        let rt_ref = &rt;
2332        let (doc_emb, query_emb) = tokio::runtime::Runtime::new().unwrap().block_on(async {
2333            let d = rt_ref
2334                .embed_document_with_model(&model.to_string(), &text)
2335                .await
2336                .unwrap();
2337            let q = rt_ref
2338                .embed_query_with_model(&model.to_string(), &text)
2339                .await
2340                .unwrap();
2341            (d, q)
2342        });
2343        assert_ne!(
2344            doc_emb, query_emb,
2345            "multilingual-e5-small uses asymmetric prefixes: document ('passage: ') \
2346             and query ('query: ') embeds of the same text must differ"
2347        );
2348    }
2349
2350    // ---- backfill reader error must be propagated, not swallowed ----
2351
2352    use crate::embedder_registry::EmbedderProvider;
2353    use lattice_embed::EmbeddingService;
2354
2355    /// A stub embedder that never actually loads weights — used to satisfy the
2356    /// `registered_embedding_model_names` check inside `backfill_missing_embeddings`
2357    /// without triggering a real model load. The test fault-injects a reader error
2358    /// before any embedding call is made, so `embed()` is never reached.
2359    struct StubEmbedderProvider;
2360
2361    #[async_trait::async_trait]
2362    impl EmbedderProvider for StubEmbedderProvider {
2363        fn name(&self) -> &str {
2364            "stub-model-m07"
2365        }
2366
2367        fn dimensions(&self) -> usize {
2368            4
2369        }
2370
2371        async fn build(&self) -> crate::error::RuntimeResult<std::sync::Arc<dyn EmbeddingService>> {
2372            struct StubSvc;
2373            #[async_trait::async_trait]
2374            impl EmbeddingService for StubSvc {
2375                async fn embed(
2376                    &self,
2377                    _texts: &[String],
2378                    _model: lattice_embed::EmbeddingModel,
2379                ) -> std::result::Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
2380                    Ok(vec![])
2381                }
2382
2383                fn supports_model(&self, _model: lattice_embed::EmbeddingModel) -> bool {
2384                    true
2385                }
2386
2387                fn name(&self) -> &'static str {
2388                    "stub-svc-m07"
2389                }
2390            }
2391            Ok(std::sync::Arc::new(StubSvc))
2392        }
2393    }
2394
2395    /// `backfill_missing_embeddings` must propagate a reader error rather than
2396    /// treating it as "zero rows to embed" (a silent `Err(_) => vec![]` would
2397    /// return `Ok(0)` and skip all embeddings without any signal).
2398    ///
2399    /// The fault injection substitutes a `StorageError::Pool` for the result of
2400    /// `sql.reader().await`, exercising the `map_err(RuntimeError::Storage)?` path;
2401    /// falling back to `unwrap_or_default()` there would swallow the injected error.
2402    #[tokio::test]
2403    async fn backfill_reader_error_is_propagated_not_swallowed() {
2404        let rt = KhiveRuntime::memory().unwrap();
2405        rt.register_embedder(StubEmbedderProvider);
2406        let tok = NamespaceToken::local();
2407
2408        // Arm the fault injection: the next backfill call will substitute a
2409        // StorageError at the sql.reader().await boundary, then reset.
2410        super::arm_backfill_reader_fail();
2411
2412        let result = rt.backfill_missing_embeddings(&tok).await;
2413        assert!(
2414            result.is_err(),
2415            "backfill_missing_embeddings must propagate the reader error (got Ok instead)"
2416        );
2417        let err_msg = result.unwrap_err().to_string();
2418        assert!(
2419            err_msg.contains("injected failure"),
2420            "error must originate from the injected reader failure, got: {err_msg}"
2421        );
2422    }
2423}