1use 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
20pub type CandidateStream = Vec<(Uuid, DeterministicScore)>;
24
25pub type RankedHit = (Uuid, DeterministicScore);
27
28#[async_trait::async_trait]
36pub trait FusionExecutor: Send + Sync + 'static {
37 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
51pub(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 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 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 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 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 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 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 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 #[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 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 assert_eq!(hits_k1[0].entity_id, a);
498 assert_eq!(hits_k60[0].entity_id, a);
499 assert!(hits_k1[0].score > hits_k60[0].score);
501 }
502
503 #[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 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 #[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 #[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 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 #[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 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 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 #[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 #[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 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 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 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 #[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 #[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 #[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 #[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 #[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 #[tokio::test]
876 async fn custom_executor_output_is_sorted_by_canonical_comparator() {
877 let rt = KhiveRuntime::memory().unwrap();
878 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 #[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 #[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 #[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 #[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}