Skip to main content

khive_runtime/
fusion.rs

1//! Fusion strategies for combining ranked result lists.
2
3use std::collections::{hash_map::Entry, HashMap, HashSet};
4
5use uuid::Uuid;
6
7use khive_score::DeterministicScore;
8use khive_storage::types::{
9    PageRequest, TextFilter, TextQueryMode, TextSearchHit, TextSearchRequest, VectorSearchHit,
10};
11use khive_storage::EntityFilter;
12use khive_types::SubstrateKind;
13
14use crate::error::{RuntimeError, RuntimeResult};
15use crate::retrieval::{SearchHit, SearchSource};
16use crate::runtime::{KhiveRuntime, NamespaceToken};
17
18pub use khive_fusion::FusionStrategy;
19
20/// A single ranked candidate stream fed into a [`FusionExecutor`] โ€” the
21/// entity/note ID keyed shape used throughout hybrid search (ADR-012
22/// `FusionStrategy::Custom` ยง"strategy executor").
23pub type CandidateStream = Vec<(Uuid, DeterministicScore)>;
24
25/// One fused, ranked `(id, score)` pair returned by a [`FusionExecutor`].
26pub type RankedHit = (Uuid, DeterministicScore);
27
28/// Runtime-registered custom fusion strategy (ADR-012).
29///
30/// Packs implement this to plug a strategy into `FusionStrategy::Custom { name,
31/// .. }` via [`KhiveRuntime::register_fusion_strategy`] โ€” the seam a
32/// learned-sparse (SPLADE) retrieval leg plugs into. Async so an executor can
33/// perform I/O (e.g. a decay/posterior lookup) while fusing, and fallible so
34/// it can reject malformed `params` instead of degrading silently.
35#[async_trait::async_trait]
36pub trait FusionExecutor: Send + Sync + 'static {
37    /// Combine `streams` into a single ranked list, honoring `limit` as a
38    /// hint (the dispatch boundary re-sorts and truncates the result with the
39    /// crate's canonical comparator regardless, so an executor need not sort
40    /// or truncate defensively itself).
41    async fn fuse(
42        &self,
43        streams: Vec<CandidateStream>,
44        params: &serde_json::Value,
45        limit: usize,
46    ) -> RuntimeResult<Vec<RankedHit>>;
47}
48
49const CANDIDATE_MULTIPLIER: u32 = 4;
50
51/// RRF convenience wrapper used by operations.rs (k=60 note search path).
52pub(crate) async fn rrf_fuse_k(
53    rt: &KhiveRuntime,
54    text_hits: Vec<TextSearchHit>,
55    vector_hits: Vec<VectorSearchHit>,
56    k: usize,
57    limit: usize,
58) -> RuntimeResult<Vec<SearchHit>> {
59    rt.fuse_with_strategy(text_hits, vector_hits, &FusionStrategy::Rrf { k }, limit)
60        .await
61}
62
63impl KhiveRuntime {
64    /// Fuse text and vector hits using the given strategy, returning at most
65    /// `limit` results. Positional weighted strategies use `[vector, keyword]`
66    /// order.
67    ///
68    /// `FusionStrategy::Custom { name, .. }` is resolved against this
69    /// runtime's registered executors (see
70    /// [`register_fusion_strategy`](KhiveRuntime::register_fusion_strategy)).
71    /// An unregistered name fails closed with
72    /// `RuntimeError::UnknownFusionStrategy` rather than silently falling
73    /// back to RRF.
74    pub(crate) async fn fuse_with_strategy(
75        &self,
76        text_hits: Vec<TextSearchHit>,
77        vector_hits: Vec<VectorSearchHit>,
78        strategy: &FusionStrategy,
79        limit: usize,
80    ) -> RuntimeResult<Vec<SearchHit>> {
81        match strategy {
82            FusionStrategy::VectorOnly => {
83                self.fuse_sources(Vec::new(), vector_hits, strategy, limit)
84                    .await
85            }
86            FusionStrategy::KeywordOnly => {
87                self.fuse_sources(text_hits, Vec::new(), strategy, limit)
88                    .await
89            }
90            FusionStrategy::Rrf { .. }
91            | FusionStrategy::Weighted { .. }
92            | FusionStrategy::Union
93            | FusionStrategy::Custom { .. } => {
94                self.fuse_sources(text_hits, vector_hits, strategy, limit)
95                    .await
96            }
97        }
98    }
99
100    async fn fuse_sources(
101        &self,
102        text_hits: Vec<TextSearchHit>,
103        vector_hits: Vec<VectorSearchHit>,
104        strategy: &FusionStrategy,
105        limit: usize,
106    ) -> RuntimeResult<Vec<SearchHit>> {
107        let mut metadata: HashMap<Uuid, SearchHit> =
108            HashMap::with_capacity(text_hits.len() + vector_hits.len());
109
110        let text_source: Vec<(Uuid, DeterministicScore)> = text_hits
111            .into_iter()
112            .map(|h| {
113                let hit = SearchHit {
114                    entity_id: h.subject_id,
115                    score: h.score,
116                    source: SearchSource::Text,
117                    title: h.title,
118                    snippet: h.snippet,
119                };
120                let id = hit.entity_id;
121                let score = hit.score;
122                merge_metadata(&mut metadata, hit);
123                (id, score)
124            })
125            .collect();
126
127        let vector_source: Vec<(Uuid, DeterministicScore)> = vector_hits
128            .into_iter()
129            .map(|h| {
130                let hit = SearchHit {
131                    entity_id: h.subject_id,
132                    score: h.score,
133                    source: SearchSource::Vector,
134                    title: None,
135                    snippet: None,
136                };
137                let id = hit.entity_id;
138                let score = hit.score;
139                merge_metadata(&mut metadata, hit);
140                (id, score)
141            })
142            .collect();
143
144        // Canonical positional order is [vector, keyword]. Empty arms remain in
145        // place: removing one would shift the surviving arm onto the wrong weight.
146        let sources: Vec<Vec<(Uuid, DeterministicScore)>> = vec![vector_source, text_source];
147
148        let fused = self.dispatch_fusion(sources, strategy, limit).await?;
149
150        Ok(fused
151            .into_iter()
152            .filter_map(|(id, score)| {
153                let mut hit = metadata.remove(&id)?;
154                hit.score = score;
155                Some(hit)
156            })
157            .collect())
158    }
159
160    /// Resolve `strategy` against either the built-in `khive-fusion`
161    /// dispatcher or a registered [`FusionExecutor`], applying the crate's
162    /// canonical score-desc/id-asc ordering at the boundary either way.
163    ///
164    /// `Custom` names are resolved *before* the empty-input/zero-limit short
165    /// circuit, so a misconfigured name errors on every call -- including
166    /// zero-result ones -- rather than being indistinguishable from a valid
167    /// empty result.
168    async fn dispatch_fusion(
169        &self,
170        sources: Vec<Vec<(Uuid, DeterministicScore)>>,
171        strategy: &FusionStrategy,
172        limit: usize,
173    ) -> RuntimeResult<Vec<(Uuid, DeterministicScore)>> {
174        let FusionStrategy::Custom { name, params } = strategy else {
175            return Ok(khive_fusion::fuse(sources, strategy, limit)?);
176        };
177
178        let executor = self.fusion_executor(name)?;
179
180        if limit == 0 || sources.iter().all(Vec::is_empty) {
181            return Ok(Vec::new());
182        }
183
184        let mut hits = executor.fuse(sources, params, limit).await?;
185        hits.sort_by(khive_fusion::cmp_desc_then_id);
186        hits.truncate(limit);
187        Ok(hits)
188    }
189}
190
191fn merge_metadata(metadata: &mut HashMap<Uuid, SearchHit>, hit: SearchHit) {
192    match metadata.entry(hit.entity_id) {
193        Entry::Occupied(mut entry) => {
194            let existing = entry.get_mut();
195            existing.source = merge_sources(existing.source, hit.source);
196            if existing.title.is_none() {
197                existing.title = hit.title;
198            }
199            if existing.snippet.is_none() {
200                existing.snippet = hit.snippet;
201            }
202        }
203        Entry::Vacant(entry) => {
204            entry.insert(hit);
205        }
206    }
207}
208
209fn merge_sources(left: SearchSource, right: SearchSource) -> SearchSource {
210    match (left, right) {
211        (SearchSource::Both, _) | (_, SearchSource::Both) => SearchSource::Both,
212        (SearchSource::Text, SearchSource::Vector) | (SearchSource::Vector, SearchSource::Text) => {
213            SearchSource::Both
214        }
215        (SearchSource::Text, SearchSource::Text) => SearchSource::Text,
216        (SearchSource::Vector, SearchSource::Vector) => SearchSource::Vector,
217    }
218}
219
220impl KhiveRuntime {
221    async fn retain_alive_search_hits(
222        &self,
223        token: &NamespaceToken,
224        mut fused: Vec<SearchHit>,
225        limit: usize,
226    ) -> RuntimeResult<Vec<SearchHit>> {
227        // Filter out soft-deleted entities. A single query fetches all alive IDs from the
228        // fused candidate pool; any ID absent from the result has been soft-deleted.
229        if !fused.is_empty() {
230            let candidate_ids: Vec<Uuid> = fused.iter().map(|h| h.entity_id).collect();
231            let alive_page = self
232                .entities(token)?
233                .query_entities(
234                    token.namespace().as_str(),
235                    EntityFilter {
236                        ids: candidate_ids,
237                        ..EntityFilter::default()
238                    },
239                    PageRequest {
240                        offset: 0,
241                        limit: u32::try_from(fused.len()).unwrap_or(u32::MAX),
242                    },
243                )
244                .await?;
245            let alive: HashSet<Uuid> = alive_page.items.into_iter().map(|e| e.id).collect();
246            fused.retain(|h| alive.contains(&h.entity_id));
247        }
248
249        fused.truncate(limit);
250        Ok(fused)
251    }
252
253    /// Hybrid search with a caller-supplied fusion strategy.
254    ///
255    /// `FusionStrategy::Custom { name, .. }` is resolved against this
256    /// runtime's registered executors (see
257    /// [`register_fusion_strategy`](KhiveRuntime::register_fusion_strategy));
258    /// an unregistered name fails closed with
259    /// `RuntimeError::UnknownFusionStrategy`.
260    pub async fn hybrid_search_with_strategy(
261        &self,
262        token: &NamespaceToken,
263        query_text: &str,
264        query_vector: Option<Vec<f32>>,
265        strategy: FusionStrategy,
266        limit: u32,
267    ) -> RuntimeResult<Vec<SearchHit>> {
268        let candidates = limit.saturating_mul(CANDIDATE_MULTIPLIER).max(limit);
269
270        let ns = token.namespace().as_str().to_owned();
271        // sanitize_fts5_query strips known-unsafe metacharacters, but residual
272        // punctuation can still trip the FTS5 parser at runtime; that error must
273        // fail loud rather than silently degrade to vector-only fusion. Errors
274        // from other legs (vector search) still propagate normally.
275        let text_search_result = self
276            .text(token)?
277            .search(TextSearchRequest {
278                query: query_text.to_string(),
279                mode: TextQueryMode::Plain,
280                filter: Some(TextFilter {
281                    namespaces: vec![ns.clone()],
282                    ..TextFilter::default()
283                }),
284                top_k: candidates,
285                snippet_chars: 200,
286            })
287            .await;
288        let text_hits = crate::error::fts_text_leg_or_err(
289            text_search_result.map_err(RuntimeError::from),
290            "hybrid_search_with_strategy",
291            query_text,
292        )?;
293
294        let vector_hits = if query_vector.is_some() || self.config().embedding_model.is_some() {
295            self.vector_search(
296                token,
297                query_vector,
298                Some(query_text),
299                candidates,
300                Some(SubstrateKind::Entity),
301            )
302            .await?
303        } else {
304            Vec::new()
305        };
306
307        // Each arm fetched `candidates` independently, so their union can contain
308        // twice that many distinct IDs. Keep the complete fetched pool through
309        // ranking and the alive check; truncating it first lets stale hits hide
310        // live candidates from the other arm.
311        let fusion_limit = text_hits.len().saturating_add(vector_hits.len());
312        let fused = self
313            .fuse_with_strategy(text_hits, vector_hits, &strategy, fusion_limit)
314            .await?;
315        self.retain_alive_search_hits(token, fused, limit as usize)
316            .await
317    }
318}
319
320#[cfg(test)]
321mod tests {
322    use super::*;
323    use chrono::Utc;
324    use khive_storage::types::{TextDocument, TextSearchHit, VectorSearchHit, VectorSearchRequest};
325    use khive_storage::Entity;
326    use lattice_embed::EmbeddingModel;
327    use std::sync::Arc;
328
329    use crate::RuntimeConfig;
330
331    fn text_hit(id: Uuid, score: f64, title: &str) -> TextSearchHit {
332        TextSearchHit {
333            subject_id: id,
334            score: DeterministicScore::from_f64(score),
335            rank: 1,
336            title: Some(title.to_string()),
337            snippet: Some("...".to_string()),
338        }
339    }
340
341    fn vector_hit(id: Uuid, score: f64) -> VectorSearchHit {
342        VectorSearchHit {
343            subject_id: id,
344            score: DeterministicScore::from_f64(score),
345            rank: 1,
346        }
347    }
348
349    fn cosine_fixture_vector(dimensions: usize, x: f32, y: f32) -> Vec<f32> {
350        let mut vector = vec![0.0; dimensions];
351        vector[0] = x;
352        vector[1] = y;
353        vector
354    }
355
356    async fn stale_full_prefix_fixture() -> (
357        KhiveRuntime,
358        NamespaceToken,
359        &'static str,
360        Vec<f32>,
361        Vec<TextSearchHit>,
362        Vec<VectorSearchHit>,
363        HashSet<Uuid>,
364    ) {
365        let model = EmbeddingModel::AllMiniLmL6V2;
366        let dimensions = model.dimensions();
367        let rt = KhiveRuntime::new(RuntimeConfig {
368            db_path: None,
369            embedding_model: Some(model),
370            additional_embedding_models: vec![],
371            ..RuntimeConfig::default()
372        })
373        .unwrap();
374        let tok = NamespaceToken::local();
375        let query_text = "fusionrefillterm";
376        let query_vector = cosine_fixture_vector(dimensions, 1.0, 0.0);
377
378        let common_stale_a = Uuid::from_u128(1);
379        let common_stale_b = Uuid::from_u128(2);
380        let text_only_stale = Uuid::from_u128(3);
381        let vector_only_stale = Uuid::from_u128(4);
382
383        let live_text = Entity::new("local", "concept", "live text candidate");
384        let live_vector = Entity::new("local", "concept", "live vector candidate");
385        rt.entities(&tok)
386            .unwrap()
387            .upsert_entities(vec![live_text.clone(), live_vector.clone()])
388            .await
389            .unwrap();
390
391        let document = |subject_id, repetitions: usize| TextDocument {
392            subject_id,
393            kind: SubstrateKind::Entity,
394            namespace: "local".to_string(),
395            title: None,
396            body: std::iter::repeat_n(query_text, repetitions)
397                .collect::<Vec<_>>()
398                .join(" "),
399            tags: vec![],
400            metadata: None,
401            updated_at: Utc::now(),
402        };
403        rt.text(&tok)
404            .unwrap()
405            .upsert_documents(vec![
406                document(common_stale_a, 12),
407                document(common_stale_b, 8),
408                document(text_only_stale, 4),
409                document(live_text.id, 1),
410            ])
411            .await
412            .unwrap();
413
414        let vectors = rt.vectors(&tok).unwrap();
415        for (id, vector) in [
416            (common_stale_a, cosine_fixture_vector(dimensions, 1.0, 0.0)),
417            (common_stale_b, cosine_fixture_vector(dimensions, 0.8, 0.6)),
418            (
419                vector_only_stale,
420                cosine_fixture_vector(dimensions, 0.5, 0.866_025_4),
421            ),
422            (live_vector.id, cosine_fixture_vector(dimensions, -1.0, 0.0)),
423        ] {
424            vectors
425                .insert(
426                    id,
427                    SubstrateKind::Entity,
428                    "local",
429                    "entity.body",
430                    vec![vector],
431                )
432                .await
433                .unwrap();
434        }
435
436        let text_hits = rt
437            .text(&tok)
438            .unwrap()
439            .search(TextSearchRequest {
440                query: query_text.to_string(),
441                mode: TextQueryMode::Plain,
442                filter: Some(TextFilter {
443                    namespaces: vec!["local".to_string()],
444                    ..TextFilter::default()
445                }),
446                top_k: CANDIDATE_MULTIPLIER,
447                snippet_chars: 0,
448            })
449            .await
450            .unwrap();
451        let vector_hits = vectors
452            .search(VectorSearchRequest {
453                query_vectors: vec![query_vector.clone()],
454                top_k: CANDIDATE_MULTIPLIER,
455                namespace: Some("local".to_string()),
456                kind: Some(SubstrateKind::Entity),
457                embedding_model: None,
458                filter: None,
459                backend_hints: None,
460            })
461            .await
462            .unwrap();
463
464        assert_eq!(text_hits.len(), CANDIDATE_MULTIPLIER as usize);
465        assert_eq!(vector_hits.len(), CANDIDATE_MULTIPLIER as usize);
466        let live = HashSet::from([live_text.id, live_vector.id]);
467        (
468            rt,
469            tok,
470            query_text,
471            query_vector,
472            text_hits,
473            vector_hits,
474            live,
475        )
476    }
477
478    // 1. RRF with custom k produces different ordering than k=60
479    #[tokio::test]
480    async fn rrf_custom_k_differs_from_k60() {
481        let rt = KhiveRuntime::memory().unwrap();
482        let a = Uuid::new_v4();
483        let b = Uuid::new_v4();
484        // Single-source input makes a and b tie in relative order at both k values,
485        // so assert on raw score magnitude (smaller k widens the rank-1-vs-rank-2 gap)
486        // rather than ordering.
487        let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
488        let hits_k1 = rt
489            .fuse_with_strategy(text.clone(), vec![], &FusionStrategy::Rrf { k: 1 }, 10)
490            .await
491            .unwrap();
492        let hits_k60 = rt
493            .fuse_with_strategy(text, vec![], &FusionStrategy::Rrf { k: 60 }, 10)
494            .await
495            .unwrap();
496        // Both should have a first (rank 1 always wins in single-source)
497        assert_eq!(hits_k1[0].entity_id, a);
498        assert_eq!(hits_k60[0].entity_id, a);
499        // k=1 produces higher raw score for rank 1 than k=60
500        assert!(hits_k1[0].score > hits_k60[0].score);
501    }
502
503    // 2. Canonical [vector, keyword] weights change ordering as documented.
504    #[tokio::test]
505    async fn weighted_ordering_depends_on_weights() {
506        let rt = KhiveRuntime::memory().unwrap();
507        let a = Uuid::new_v4();
508        let b = Uuid::new_v4();
509        // a scores high in text, b scores high in vector
510        let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
511        let vec_hits = vec![vector_hit(b, 0.9), vector_hit(a, 0.1)];
512
513        let heavy_vector = rt
514            .fuse_with_strategy(
515                text.clone(),
516                vec_hits.clone(),
517                &FusionStrategy::Weighted {
518                    weights: vec![0.7, 0.3],
519                },
520                10,
521            )
522            .await
523            .unwrap();
524        let heavy_keyword = rt
525            .fuse_with_strategy(
526                text,
527                vec_hits,
528                &FusionStrategy::Weighted {
529                    weights: vec![0.3, 0.7],
530                },
531                10,
532            )
533            .await
534            .unwrap();
535
536        assert_eq!(heavy_vector[0].entity_id, b);
537        assert_eq!(heavy_keyword[0].entity_id, a);
538    }
539
540    // 3. Weighted [7.0, 3.0] = Weighted [0.7, 0.3] (normalization)
541    #[tokio::test]
542    async fn weighted_scale_invariant() {
543        let rt = KhiveRuntime::memory().unwrap();
544        let a = Uuid::new_v4();
545        let b = Uuid::new_v4();
546        let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
547        let vec_hits = vec![vector_hit(b, 0.9), vector_hit(a, 0.1)];
548
549        let w1 = rt
550            .fuse_with_strategy(
551                text.clone(),
552                vec_hits.clone(),
553                &FusionStrategy::Weighted {
554                    weights: vec![0.7, 0.3],
555                },
556                10,
557            )
558            .await
559            .unwrap();
560        let w2 = rt
561            .fuse_with_strategy(
562                text,
563                vec_hits,
564                &FusionStrategy::Weighted {
565                    weights: vec![7.0, 3.0],
566                },
567                10,
568            )
569            .await
570            .unwrap();
571
572        assert_eq!(w1[0].entity_id, w2[0].entity_id);
573        assert_eq!(w1[1].entity_id, w2[1].entity_id);
574        let diff = (w1[0].score.to_f64() - w2[0].score.to_f64()).abs();
575        assert!(diff < 1e-9, "scores differ by {diff}");
576    }
577
578    // 4. Weighted [0.0, 0.0] falls back to equal weights
579    #[tokio::test]
580    async fn weighted_zero_weights_equal_fallback() {
581        let rt = KhiveRuntime::memory().unwrap();
582        let a = Uuid::new_v4();
583        let b = Uuid::new_v4();
584        // Both sources agree: a > b
585        let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
586        let vec_hits = vec![vector_hit(a, 0.9), vector_hit(b, 0.1)];
587
588        let hits = rt
589            .fuse_with_strategy(
590                text,
591                vec_hits,
592                &FusionStrategy::Weighted {
593                    weights: vec![0.0, 0.0],
594                },
595                10,
596            )
597            .await
598            .unwrap();
599        assert_eq!(hits[0].entity_id, a);
600    }
601
602    // 5. Weighted with negative weight clamps to 0
603    #[tokio::test]
604    async fn weighted_negative_weight_clamped() {
605        let rt = KhiveRuntime::memory().unwrap();
606        let a = Uuid::new_v4();
607        let text = vec![text_hit(a, 0.9, "a")];
608        // Negative vector weight โ†’ only keyword/text contributes.
609        let hits = rt
610            .fuse_with_strategy(
611                text,
612                vec![],
613                &FusionStrategy::Weighted {
614                    weights: vec![-0.5, 1.0],
615                },
616                10,
617            )
618            .await
619            .unwrap();
620        assert_eq!(hits.len(), 1);
621        assert_eq!(hits[0].entity_id, a);
622    }
623
624    #[tokio::test]
625    async fn weighted_empty_arm_keeps_canonical_position() {
626        let rt = KhiveRuntime::memory().unwrap();
627        let text_only = Uuid::new_v4();
628        let hits = rt
629            .fuse_with_strategy(
630                vec![text_hit(text_only, 0.9, "text")],
631                vec![],
632                &FusionStrategy::Weighted {
633                    // Canonical [vector, keyword]: the only non-empty arm has zero weight.
634                    weights: vec![1.0, 0.0],
635                },
636                10,
637            )
638            .await
639            .unwrap();
640        assert!(
641            hits.is_empty(),
642            "dropping the empty vector arm would incorrectly rebind text to its weight"
643        );
644    }
645
646    // 6. Union returns max score per entity when same id appears in both lists
647    #[tokio::test]
648    async fn union_max_score_per_entity() {
649        let rt = KhiveRuntime::memory().unwrap();
650        let a = Uuid::new_v4();
651        let text = vec![text_hit(a, 0.3, "a")];
652        let vec_hits = vec![vector_hit(a, 0.9)];
653
654        let hits = rt
655            .fuse_with_strategy(text, vec_hits, &FusionStrategy::Union, 10)
656            .await
657            .unwrap();
658        assert_eq!(hits.len(), 1);
659        assert!((hits[0].score.to_f64() - 0.9).abs() < 1e-6);
660        assert_eq!(hits[0].source, SearchSource::Both);
661    }
662
663    // 7. VectorOnly returns vector hits only (text hits dropped)
664    #[tokio::test]
665    async fn vector_only_drops_text() {
666        let rt = KhiveRuntime::memory().unwrap();
667        let a = Uuid::new_v4();
668        let b = Uuid::new_v4();
669        let text = vec![text_hit(b, 0.9, "b")];
670        let vec_hits = vec![vector_hit(a, 0.8)];
671
672        let hits = rt
673            .fuse_with_strategy(text, vec_hits, &FusionStrategy::VectorOnly, 10)
674            .await
675            .unwrap();
676        assert_eq!(hits.len(), 1);
677        assert_eq!(hits[0].entity_id, a);
678        assert_eq!(hits[0].source, SearchSource::Vector);
679        assert!(hits[0].title.is_none());
680    }
681
682    #[tokio::test]
683    async fn keyword_only_drops_vector() {
684        let rt = KhiveRuntime::memory().unwrap();
685        let text_id = Uuid::new_v4();
686        let vector_id = Uuid::new_v4();
687        let hits = rt
688            .fuse_with_strategy(
689                vec![text_hit(text_id, 0.8, "text")],
690                vec![vector_hit(vector_id, 0.9)],
691                &FusionStrategy::KeywordOnly,
692                10,
693            )
694            .await
695            .unwrap();
696        assert_eq!(hits.len(), 1);
697        assert_eq!(hits[0].entity_id, text_id);
698        assert_eq!(hits[0].source, SearchSource::Text);
699    }
700
701    /// Test-only executor: flattens all streams and reverses their order,
702    /// keeping each candidate's original score.
703    struct ReverseOrderExecutor;
704
705    #[async_trait::async_trait]
706    impl FusionExecutor for ReverseOrderExecutor {
707        async fn fuse(
708            &self,
709            streams: Vec<CandidateStream>,
710            _params: &serde_json::Value,
711            _limit: usize,
712        ) -> RuntimeResult<Vec<RankedHit>> {
713            let mut flat: Vec<_> = streams.into_iter().flatten().collect();
714            flat.reverse();
715            Ok(flat)
716        }
717    }
718
719    /// Test-only executor: inverts each candidate's score (`1.0 - score`) so
720    /// the fused ranking is the reverse of what score-descending built-ins
721    /// (RRF, Union, Weighted) would produce on the same fixture -- unlike a
722    /// mere insertion-order reversal, this survives the dispatch boundary's
723    /// canonical re-sort, since the *scores* (not just the order) differ.
724    struct InvertScoreExecutor;
725
726    #[async_trait::async_trait]
727    impl FusionExecutor for InvertScoreExecutor {
728        async fn fuse(
729            &self,
730            streams: Vec<CandidateStream>,
731            _params: &serde_json::Value,
732            _limit: usize,
733        ) -> RuntimeResult<Vec<RankedHit>> {
734            Ok(streams
735                .into_iter()
736                .flatten()
737                .map(|(id, score)| (id, DeterministicScore::from_f64(1.0 - score.to_f64())))
738                .collect())
739        }
740    }
741
742    /// Test-only executor: returns every candidate at an identical score, in
743    /// the arbitrary order the input streams happened to flatten to -- used
744    /// to prove the dispatch boundary re-sorts by the canonical comparator
745    /// rather than trusting executor output order.
746    struct EqualScoreExecutor;
747
748    #[async_trait::async_trait]
749    impl FusionExecutor for EqualScoreExecutor {
750        async fn fuse(
751            &self,
752            streams: Vec<CandidateStream>,
753            _params: &serde_json::Value,
754            _limit: usize,
755        ) -> RuntimeResult<Vec<RankedHit>> {
756            Ok(streams
757                .into_iter()
758                .flatten()
759                .map(|(id, _)| (id, DeterministicScore::from_f64(1.0)))
760                .collect())
761        }
762    }
763
764    // 7b. A registered custom executor dispatches and yields a different
765    // ranking than RRF on the same fixture.
766    #[tokio::test]
767    async fn custom_strategy_dispatches_through_executor_and_differs_from_rrf() {
768        let rt = KhiveRuntime::memory().unwrap();
769        let a = Uuid::new_v4();
770        let b = Uuid::new_v4();
771        let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.5, "b")];
772
773        rt.register_fusion_strategy("invert", Arc::new(InvertScoreExecutor));
774        let strategy =
775            FusionStrategy::try_custom("invert".to_string(), serde_json::Value::Null).unwrap();
776
777        let custom = rt
778            .fuse_with_strategy(text.clone(), vec![], &strategy, 10)
779            .await
780            .unwrap();
781        let rrf = rt
782            .fuse_with_strategy(text, vec![], &FusionStrategy::rrf(), 10)
783            .await
784            .unwrap();
785
786        let custom_ids: Vec<_> = custom.iter().map(|h| h.entity_id).collect();
787        let rrf_ids: Vec<_> = rrf.iter().map(|h| h.entity_id).collect();
788        assert_ne!(
789            custom_ids, rrf_ids,
790            "custom and RRF must yield different orderings on this fixture"
791        );
792    }
793
794    // 7c. An unregistered Custom name fails closed rather than falling back to RRF.
795    #[tokio::test]
796    async fn custom_strategy_unknown_name_fails_closed() {
797        let rt = KhiveRuntime::memory().unwrap();
798        let a = Uuid::new_v4();
799        let text = vec![text_hit(a, 0.9, "a")];
800        let strategy =
801            FusionStrategy::try_custom("nonexistent".to_string(), serde_json::Value::Null).unwrap();
802
803        let result = rt.fuse_with_strategy(text, vec![], &strategy, 10).await;
804        assert!(matches!(
805            result,
806            Err(RuntimeError::UnknownFusionStrategy(name)) if name == "nonexistent"
807        ));
808    }
809
810    // 7d. Unknown name errors even with empty sources -- it must not be
811    // indistinguishable from a valid empty result.
812    #[tokio::test]
813    async fn custom_strategy_unknown_name_fails_closed_even_on_empty_input() {
814        let rt = KhiveRuntime::memory().unwrap();
815        let strategy =
816            FusionStrategy::try_custom("nonexistent".to_string(), serde_json::Value::Null).unwrap();
817
818        let result = rt.fuse_with_strategy(vec![], vec![], &strategy, 10).await;
819        assert!(matches!(
820            result,
821            Err(RuntimeError::UnknownFusionStrategy(name)) if name == "nonexistent"
822        ));
823    }
824
825    // 7e. Empty sources with a *registered* name is a valid empty result, not
826    // an error -- distinguishing "misconfigured" from "genuinely nothing".
827    #[tokio::test]
828    async fn custom_strategy_registered_name_empty_input_returns_ok_empty() {
829        let rt = KhiveRuntime::memory().unwrap();
830        rt.register_fusion_strategy("reverse", Arc::new(ReverseOrderExecutor));
831        let strategy =
832            FusionStrategy::try_custom("reverse".to_string(), serde_json::Value::Null).unwrap();
833
834        let result = rt
835            .fuse_with_strategy(vec![], vec![], &strategy, 10)
836            .await
837            .unwrap();
838        assert!(result.is_empty());
839    }
840
841    // 7f. Registering a custom strategy never perturbs the default (non-Custom) path.
842    #[tokio::test]
843    async fn registered_custom_strategy_leaves_default_path_unaffected() {
844        let rt = KhiveRuntime::memory().unwrap();
845        let a = Uuid::new_v4();
846        let b = Uuid::new_v4();
847        let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.5, "b")];
848
849        rt.register_fusion_strategy("reverse", Arc::new(ReverseOrderExecutor));
850
851        let via_rt_with_registration = rt
852            .fuse_with_strategy(text.clone(), vec![], &FusionStrategy::rrf(), 10)
853            .await
854            .unwrap();
855        let rt2 = KhiveRuntime::memory().unwrap();
856        let via_rt_without_registration = rt2
857            .fuse_with_strategy(text, vec![], &FusionStrategy::rrf(), 10)
858            .await
859            .unwrap();
860
861        let ids_with: Vec<_> = via_rt_with_registration
862            .iter()
863            .map(|h| h.entity_id)
864            .collect();
865        let ids_without: Vec<_> = via_rt_without_registration
866            .iter()
867            .map(|h| h.entity_id)
868            .collect();
869        assert_eq!(ids_with, ids_without);
870    }
871
872    // 7g. A custom executor returning equal-score IDs in arbitrary/reversed
873    // order still yields the crate's canonical score-desc/id-asc order --
874    // the dispatch boundary re-sorts rather than trusting executor output.
875    #[tokio::test]
876    async fn custom_executor_output_is_sorted_by_canonical_comparator() {
877        let rt = KhiveRuntime::memory().unwrap();
878        // Deliberately not in ID order, so a passthrough bug would be visible.
879        let ids: Vec<Uuid> = vec![Uuid::from_u128(3), Uuid::from_u128(1), Uuid::from_u128(2)];
880        let text: Vec<TextSearchHit> = ids.iter().map(|&id| text_hit(id, 0.5, "tied")).collect();
881
882        rt.register_fusion_strategy("equal_score", Arc::new(EqualScoreExecutor));
883        let strategy =
884            FusionStrategy::try_custom("equal_score".to_string(), serde_json::Value::Null).unwrap();
885
886        let hits = rt
887            .fuse_with_strategy(text, vec![], &strategy, 10)
888            .await
889            .unwrap();
890
891        let mut expected = ids.clone();
892        expected.sort();
893        let actual: Vec<_> = hits.iter().map(|h| h.entity_id).collect();
894        assert_eq!(
895            actual, expected,
896            "equal-score executor output must be tie-broken by ascending ID"
897        );
898    }
899
900    // 8. Default strategy is Rrf{k:60}
901    #[test]
902    fn default_strategy_is_rrf_k60() {
903        assert_eq!(FusionStrategy::default(), FusionStrategy::Rrf { k: 60 });
904    }
905
906    #[tokio::test]
907    async fn hybrid_union_alive_filter_refills_below_complete_four_x_prefix() {
908        let (rt, tok, query_text, query_vector, text_hits, vector_hits, live) =
909            stale_full_prefix_fixture().await;
910        let truncated = rt
911            .fuse_with_strategy(
912                text_hits,
913                vector_hits,
914                &FusionStrategy::Union,
915                CANDIDATE_MULTIPLIER as usize,
916            )
917            .await
918            .unwrap();
919        assert!(truncated.iter().all(|hit| !live.contains(&hit.entity_id)));
920
921        let hits = rt
922            .hybrid_search_with_strategy(
923                &tok,
924                query_text,
925                Some(query_vector),
926                FusionStrategy::Union,
927                1,
928            )
929            .await
930            .unwrap();
931
932        assert_eq!(hits.len(), 1);
933        assert!(live.contains(&hits[0].entity_id));
934    }
935
936    #[tokio::test]
937    async fn hybrid_rrf_alive_filter_refills_below_complete_four_x_prefix() {
938        let (rt, tok, query_text, query_vector, text_hits, vector_hits, live) =
939            stale_full_prefix_fixture().await;
940        let strategy = FusionStrategy::Rrf { k: 60 };
941        let truncated = rt
942            .fuse_with_strategy(
943                text_hits,
944                vector_hits,
945                &strategy,
946                CANDIDATE_MULTIPLIER as usize,
947            )
948            .await
949            .unwrap();
950        assert!(truncated.iter().all(|hit| !live.contains(&hit.entity_id)));
951
952        let hits = rt
953            .hybrid_search_with_strategy(&tok, query_text, Some(query_vector), strategy, 1)
954            .await
955            .unwrap();
956
957        assert_eq!(hits.len(), 1);
958        assert!(live.contains(&hits[0].entity_id));
959    }
960
961    #[tokio::test]
962    async fn hybrid_default_rrf_alive_filter_refills_below_complete_four_x_prefix() {
963        let (rt, tok, query_text, query_vector, _text_hits, _vector_hits, live) =
964            stale_full_prefix_fixture().await;
965
966        let hits = rt
967            .hybrid_search(
968                &tok,
969                query_text,
970                Some(query_vector),
971                1,
972                None,
973                None,
974                &[],
975                None,
976            )
977            .await
978            .unwrap();
979
980        assert_eq!(hits.len(), 1);
981        assert!(live.contains(&hits[0].entity_id));
982    }
983
984    // 9. Roundtrip serde preserves variant
985    #[test]
986    fn serde_roundtrip() {
987        let cases = vec![
988            FusionStrategy::Rrf { k: 60 },
989            FusionStrategy::Rrf { k: 20 },
990            FusionStrategy::Weighted {
991                weights: vec![0.7, 0.3],
992            },
993            FusionStrategy::Union,
994            FusionStrategy::VectorOnly,
995            FusionStrategy::KeywordOnly,
996        ];
997        for strategy in cases {
998            let json = serde_json::to_string(&strategy).expect("serialize");
999            let back: FusionStrategy = serde_json::from_str(&json).expect("deserialize");
1000            assert_eq!(strategy, back, "roundtrip failed for {json}");
1001        }
1002    }
1003
1004    // 10. hybrid_search_with_strategy must not hard-fail on a query containing FTS5
1005    // metacharacters like `$`, since sanitize_fts5_query strips them before the query
1006    // reaches SQLite. This covers the sanitizer path; test 11 covers the fail-loud
1007    // path for characters the sanitizer does not strip.
1008    #[tokio::test]
1009    async fn hybrid_search_with_strategy_dollar_sign_query_does_not_error() {
1010        let rt = KhiveRuntime::memory().unwrap();
1011        let tok = NamespaceToken::local();
1012        rt.create_entity(
1013            &tok,
1014            "concept",
1015            None,
1016            "DSL docs",
1017            Some("use $prev.id to chain calls"),
1018            None,
1019            vec![],
1020        )
1021        .await
1022        .unwrap();
1023
1024        let result = rt
1025            .hybrid_search_with_strategy(&tok, "$prev.id", None, FusionStrategy::default(), 10)
1026            .await;
1027
1028        assert!(
1029            result.is_ok(),
1030            "#388 hybrid_search_with_strategy must not hard-fail on a '$'-bearing query, got: {:?}",
1031            result.err()
1032        );
1033    }
1034
1035    // 11. #916: `@` used to reach SQLite FTS5's bareword parser raw and error,
1036    // surfacing as RuntimeError::InvalidInput per #569's fail-loud policy.
1037    // sanitize_fts5_token_group's bareword-safety gate now routes it through the
1038    // quoted-phrase alternative instead, so the query succeeds and the fail-loud
1039    // arm is no longer reached for ordinary punctuation.
1040    #[tokio::test]
1041    async fn hybrid_search_with_strategy_residual_fts5_char_now_sanitized() {
1042        let rt = KhiveRuntime::memory().unwrap();
1043        let tok = NamespaceToken::local();
1044        rt.create_entity(
1045            &tok,
1046            "concept",
1047            None,
1048            "DSL docs",
1049            Some("use foo@bar to chain calls"),
1050            None,
1051            vec![],
1052        )
1053        .await
1054        .unwrap();
1055
1056        let result = rt
1057            .hybrid_search_with_strategy(&tok, "foo@bar", None, FusionStrategy::default(), 10)
1058            .await;
1059
1060        let hits = result.unwrap_or_else(|e| {
1061            panic!(
1062                "#916 hybrid_search_with_strategy must not fail on an '@'-bearing query, got: {e:?}"
1063            )
1064        });
1065        assert!(
1066            !hits.is_empty(),
1067            "#916 '@'-bearing query must still find the seeded 'foo@bar' content via the \
1068             quoted-phrase alternative"
1069        );
1070    }
1071}