1use std::collections::{HashMap, HashSet};
4
5use uuid::Uuid;
6
7use khive_retrieval::hit::{merge_hit_metadata, SignalMerge};
8use khive_retrieval::HYBRID_CANDIDATE_MULTIPLIER as CANDIDATE_MULTIPLIER;
9use khive_score::DeterministicScore;
10use khive_storage::types::{
11 PageRequest, TextFilter, TextQueryMode, TextSearchHit, TextSearchRequest, VectorSearchHit,
12};
13use khive_storage::EntityFilter;
14use khive_types::SubstrateKind;
15
16use crate::error::{RuntimeError, RuntimeResult};
17use crate::retrieval::{RankScoreKind, SearchHit, SearchSignals, SearchSource};
18use crate::runtime::{KhiveRuntime, NamespaceToken};
19
20pub use khive_fusion::FusionStrategy;
21
22pub type CandidateStream = Vec<(Uuid, DeterministicScore)>;
26
27pub type RankedHit = (Uuid, DeterministicScore);
29
30#[async_trait::async_trait]
38pub trait FusionExecutor: Send + Sync + 'static {
39 fn rank_score_kind(&self) -> RankScoreKind;
41
42 async fn fuse(
47 &self,
48 streams: Vec<CandidateStream>,
49 params: &serde_json::Value,
50 limit: usize,
51 ) -> RuntimeResult<Vec<RankedHit>>;
52}
53
54impl KhiveRuntime {
55 pub(crate) async fn fuse_with_strategy(
66 &self,
67 text_hits: Vec<TextSearchHit>,
68 vector_hits: Vec<VectorSearchHit>,
69 strategy: &FusionStrategy,
70 limit: usize,
71 ) -> RuntimeResult<Vec<SearchHit>> {
72 match strategy {
73 FusionStrategy::VectorOnly => {
74 self.fuse_sources(Vec::new(), vector_hits, strategy, limit)
75 .await
76 }
77 FusionStrategy::KeywordOnly => {
78 self.fuse_sources(text_hits, Vec::new(), strategy, limit)
79 .await
80 }
81 FusionStrategy::Rrf { .. }
82 | FusionStrategy::WeightedRrf { .. }
83 | FusionStrategy::Weighted { .. }
84 | FusionStrategy::Union
85 | FusionStrategy::Custom { .. } => {
86 self.fuse_sources(text_hits, vector_hits, strategy, limit)
87 .await
88 }
89 }
90 }
91
92 async fn fuse_sources(
93 &self,
94 text_hits: Vec<TextSearchHit>,
95 vector_hits: Vec<VectorSearchHit>,
96 strategy: &FusionStrategy,
97 limit: usize,
98 ) -> RuntimeResult<Vec<SearchHit>> {
99 let mut metadata: HashMap<Uuid, SearchHit> =
100 HashMap::with_capacity(text_hits.len() + vector_hits.len());
101 let signal_merge = if matches!(
102 strategy,
103 FusionStrategy::Weighted { .. } | FusionStrategy::Union
104 ) {
105 SignalMerge::Maximum
106 } else {
107 SignalMerge::FirstPresent
108 };
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 rank_score_kind: RankScoreKind::Keyword,
117 signals: SearchSignals {
118 vector_similarity: None,
119 keyword_score: Some(h.score),
120 },
121 source: SearchSource::Text,
122 title: h.title,
123 snippet: h.snippet,
124 };
125 let id = hit.entity_id;
126 let score = hit.score;
127 merge_hit_metadata(&mut metadata, hit, signal_merge);
128 (id, score)
129 })
130 .collect();
131
132 let vector_source: Vec<(Uuid, DeterministicScore)> = vector_hits
133 .into_iter()
134 .map(|h| {
135 let hit = SearchHit {
136 entity_id: h.subject_id,
137 score: h.score,
138 rank_score_kind: RankScoreKind::Vector,
139 signals: SearchSignals {
140 vector_similarity: Some(h.score),
141 keyword_score: None,
142 },
143 source: SearchSource::Vector,
144 title: None,
145 snippet: None,
146 };
147 let id = hit.entity_id;
148 let score = hit.score;
149 merge_hit_metadata(&mut metadata, hit, signal_merge);
150 (id, score)
151 })
152 .collect();
153
154 let sources: Vec<Vec<(Uuid, DeterministicScore)>> = vec![vector_source, text_source];
157
158 let (rank_score_kind, fused) = self.dispatch_fusion(sources, strategy, limit).await?;
159
160 Ok(fused
161 .into_iter()
162 .filter_map(|(id, score)| {
163 let mut hit = metadata.remove(&id)?;
164 hit.score = score;
165 hit.rank_score_kind = rank_score_kind;
166 Some(hit)
167 })
168 .collect())
169 }
170
171 async fn dispatch_fusion(
180 &self,
181 sources: Vec<Vec<(Uuid, DeterministicScore)>>,
182 strategy: &FusionStrategy,
183 limit: usize,
184 ) -> RuntimeResult<(RankScoreKind, Vec<RankedHit>)> {
185 let rank_score_kind = match RankScoreKind::of(strategy) {
186 Ok(kind) => kind,
187 Err((name, params)) => {
188 let executor = self.fusion_executor(name)?;
189 let rank_score_kind = executor.rank_score_kind();
190 if limit == 0 || sources.iter().all(Vec::is_empty) {
191 return Ok((rank_score_kind, Vec::new()));
192 }
193 let mut hits = executor.fuse(sources, params, limit).await?;
194 hits.sort_by(khive_fusion::cmp_desc_then_id);
195 hits.truncate(limit);
196 return Ok((rank_score_kind, hits));
197 }
198 };
199 Ok((
200 rank_score_kind,
201 khive_fusion::fuse(sources, strategy, limit)?,
202 ))
203 }
204}
205
206impl KhiveRuntime {
207 async fn retain_alive_search_hits(
208 &self,
209 token: &NamespaceToken,
210 mut fused: Vec<SearchHit>,
211 limit: usize,
212 ) -> RuntimeResult<Vec<SearchHit>> {
213 if !fused.is_empty() {
216 let candidate_ids: Vec<Uuid> = fused.iter().map(|h| h.entity_id).collect();
217 let alive_page = self
218 .entities(token)?
219 .query_entities(
220 token.namespace().as_str(),
221 EntityFilter {
222 ids: candidate_ids,
223 ..EntityFilter::default()
224 },
225 PageRequest {
226 offset: 0,
227 limit: u32::try_from(fused.len()).unwrap_or(u32::MAX),
228 },
229 )
230 .await?;
231 let alive: HashSet<Uuid> = alive_page.items.into_iter().map(|e| e.id).collect();
232 fused.retain(|h| alive.contains(&h.entity_id));
233 }
234
235 fused.truncate(limit);
236 Ok(fused)
237 }
238
239 pub async fn hybrid_search_with_strategy(
247 &self,
248 token: &NamespaceToken,
249 query_text: &str,
250 query_vector: Option<Vec<f32>>,
251 strategy: FusionStrategy,
252 limit: u32,
253 ) -> RuntimeResult<Vec<SearchHit>> {
254 let candidates = limit.saturating_mul(CANDIDATE_MULTIPLIER).max(limit);
255
256 let text_hits = if matches!(&strategy, FusionStrategy::VectorOnly) {
257 Vec::new()
258 } else {
259 let ns = token.namespace().as_str().to_owned();
260 let text_search_result = self
265 .text(token)?
266 .search(TextSearchRequest {
267 query: query_text.to_string(),
268 mode: TextQueryMode::Plain,
269 filter: Some(TextFilter {
270 namespaces: vec![ns],
271 ..TextFilter::default()
272 }),
273 top_k: candidates,
274 snippet_chars: 200,
275 })
276 .await;
277 crate::error::fts_text_leg_or_err(
278 text_search_result.map_err(RuntimeError::from),
279 "hybrid_search_with_strategy",
280 query_text,
281 )?
282 };
283
284 let vector_hits = if !matches!(&strategy, FusionStrategy::KeywordOnly)
285 && (query_vector.is_some() || !self.default_embedder_name().is_empty())
286 {
287 self.vector_search(
288 token,
289 query_vector,
290 Some(query_text),
291 candidates,
292 Some(SubstrateKind::Entity),
293 )
294 .await?
295 } else {
296 Vec::new()
297 };
298
299 let fusion_limit = text_hits.len().saturating_add(vector_hits.len());
304 let fused = self
305 .fuse_with_strategy(text_hits, vector_hits, &strategy, fusion_limit)
306 .await?;
307 self.retain_alive_search_hits(token, fused, limit as usize)
308 .await
309 }
310}
311
312#[cfg(test)]
313mod tests {
314 use super::*;
315 use chrono::Utc;
316 use khive_storage::types::{TextDocument, TextSearchHit, VectorSearchHit, VectorSearchRequest};
317 use khive_storage::Entity;
318 use lattice_embed::{EmbedError, EmbeddingModel, EmbeddingService};
319 use std::sync::atomic::{AtomicUsize, Ordering};
320 use std::sync::Arc;
321
322 use crate::{EmbedderProvider, RuntimeConfig};
323
324 fn text_hit(id: Uuid, score: f64, title: &str) -> TextSearchHit {
325 TextSearchHit {
326 subject_id: id,
327 score: DeterministicScore::from_f64(score),
328 rank: 1,
329 title: Some(title.to_string()),
330 snippet: Some("...".to_string()),
331 }
332 }
333
334 fn vector_hit(id: Uuid, score: f64) -> VectorSearchHit {
335 VectorSearchHit {
336 subject_id: id,
337 score: DeterministicScore::from_f64(score),
338 rank: 1,
339 }
340 }
341
342 fn evidence_runtime() -> KhiveRuntime {
343 let backend = Arc::new(crate::StorageBackend::memory().expect("in-memory backend"));
344 backend.prepare_core_schema().expect("core schema");
345 KhiveRuntime::from_backend(
346 backend,
347 RuntimeConfig {
348 db_path: None,
349 events_split: None,
350 actor_id: Some("test:fusion-evidence".into()),
351 ..RuntimeConfig::no_embeddings()
352 },
353 )
354 }
355
356 struct CountingEmbeddingService {
357 calls: Arc<AtomicUsize>,
358 dimensions: usize,
359 }
360
361 #[async_trait::async_trait]
362 impl EmbeddingService for CountingEmbeddingService {
363 async fn embed(
364 &self,
365 texts: &[String],
366 _model: EmbeddingModel,
367 ) -> Result<Vec<Vec<f32>>, EmbedError> {
368 self.calls.fetch_add(1, Ordering::SeqCst);
369 Ok(texts.iter().map(|_| vec![1.0; self.dimensions]).collect())
370 }
371
372 fn supports_model(&self, _model: EmbeddingModel) -> bool {
373 true
374 }
375
376 fn name(&self) -> &'static str {
377 "fusion-counting-embedding"
378 }
379 }
380
381 struct CountingEmbedderProvider {
382 name: String,
383 calls: Arc<AtomicUsize>,
384 dimensions: usize,
385 }
386
387 #[async_trait::async_trait]
388 impl EmbedderProvider for CountingEmbedderProvider {
389 fn name(&self) -> &str {
390 &self.name
391 }
392
393 fn dimensions(&self) -> usize {
394 self.dimensions
395 }
396
397 async fn build(&self) -> RuntimeResult<Arc<dyn EmbeddingService>> {
398 Ok(Arc::new(CountingEmbeddingService {
399 calls: Arc::clone(&self.calls),
400 dimensions: self.dimensions,
401 }))
402 }
403 }
404
405 fn counting_embedding_runtime() -> (KhiveRuntime, Arc<AtomicUsize>) {
406 let model = EmbeddingModel::AllMiniLmL6V2;
407 let rt = KhiveRuntime::new(RuntimeConfig {
408 db_path: None,
409 embedding_model: Some(model),
410 packs: vec!["kg".to_string()],
411 ..RuntimeConfig::no_embeddings()
412 })
413 .expect("in-memory runtime");
414 let calls = Arc::new(AtomicUsize::new(0));
415 rt.register_embedder(CountingEmbedderProvider {
416 name: model.to_string(),
417 calls: Arc::clone(&calls),
418 dimensions: model.dimensions(),
419 });
420 (rt, calls)
421 }
422
423 #[tokio::test]
424 async fn keyword_only_search_skips_embedding_and_vector_arm() {
425 let (rt, embed_calls) = counting_embedding_runtime();
426 let tok = NamespaceToken::local();
427 let entity = Entity::new("local", "concept", "keyword candidate");
428 rt.entities(&tok)
429 .unwrap()
430 .upsert_entities(vec![entity.clone()])
431 .await
432 .unwrap();
433 rt.text(&tok)
434 .unwrap()
435 .upsert_document(TextDocument {
436 subject_id: entity.id,
437 kind: SubstrateKind::Entity,
438 record_kind: None,
439 namespace: "local".to_string(),
440 title: None,
441 body: "fusionkeyword".to_string(),
442 tags: vec![],
443 metadata: None,
444 updated_at: Utc::now(),
445 })
446 .await
447 .unwrap();
448
449 let hits = rt
450 .hybrid_search_with_strategy(
451 &tok,
452 "fusionkeyword",
453 None,
454 FusionStrategy::KeywordOnly,
455 10,
456 )
457 .await
458 .unwrap();
459 assert_eq!(hits.len(), 1);
460 assert_eq!(hits[0].entity_id, entity.id);
461 assert_eq!(hits[0].source, SearchSource::Text);
462 assert_eq!(embed_calls.load(Ordering::SeqCst), 0);
463
464 let mixed = rt
465 .hybrid_search_with_strategy(&tok, "fusionkeyword", None, FusionStrategy::rrf(), 10)
466 .await
467 .unwrap();
468 assert_eq!(mixed[0].entity_id, entity.id);
469 assert_eq!(embed_calls.load(Ordering::SeqCst), 1);
470 }
471
472 #[tokio::test]
473 async fn vector_only_search_skips_unavailable_text_arm() {
474 let (rt, embed_calls) = counting_embedding_runtime();
475 let tok = NamespaceToken::local();
476 let entity = Entity::new("local", "concept", "vector candidate");
477 rt.entities(&tok)
478 .unwrap()
479 .upsert_entities(vec![entity.clone()])
480 .await
481 .unwrap();
482 let query_vector = vec![1.0; EmbeddingModel::AllMiniLmL6V2.dimensions()];
483 rt.vectors(&tok)
484 .unwrap()
485 .insert(
486 entity.id,
487 SubstrateKind::Entity,
488 "local",
489 "entity.body",
490 vec![query_vector.clone()],
491 )
492 .await
493 .unwrap();
494 rt.text(&tok).unwrap();
495 let mut writer = rt.sql().writer().await.unwrap();
496 writer
497 .execute_script(
498 "DROP TABLE fts_entities; CREATE TABLE fts_entities (id INTEGER PRIMARY KEY);"
499 .to_string(),
500 )
501 .await
502 .unwrap();
503 drop(writer);
504
505 let hits = rt
506 .hybrid_search_with_strategy(
507 &tok,
508 "fusionkeyword",
509 Some(query_vector),
510 FusionStrategy::VectorOnly,
511 10,
512 )
513 .await
514 .unwrap();
515 assert_eq!(hits.len(), 1);
516 assert_eq!(hits[0].entity_id, entity.id);
517 assert_eq!(hits[0].source, SearchSource::Vector);
518 assert_eq!(embed_calls.load(Ordering::SeqCst), 0);
519 }
520
521 #[tokio::test]
522 async fn fusion_evidence_labels_builtin_strategies_and_preserves_components() {
523 let rt = evidence_runtime();
524 let id = Uuid::from_u128(1);
525 let keyword = DeterministicScore::from_raw(1_i64 << 30);
526 let vector = DeterministicScore::from_raw(3_i64 << 30);
527 for (strategy, kind, raw_score, signals) in [
528 (
529 FusionStrategy::Rrf { k: 60 },
530 RankScoreKind::Rrf,
531 140_818_600,
532 SearchSignals {
533 vector_similarity: Some(vector),
534 keyword_score: Some(keyword),
535 },
536 ),
537 (
538 FusionStrategy::VectorOnly,
539 RankScoreKind::Vector,
540 vector.to_raw(),
541 SearchSignals {
542 vector_similarity: Some(vector),
543 keyword_score: None,
544 },
545 ),
546 (
547 FusionStrategy::KeywordOnly,
548 RankScoreKind::Keyword,
549 keyword.to_raw(),
550 SearchSignals {
551 vector_similarity: None,
552 keyword_score: Some(keyword),
553 },
554 ),
555 (
556 FusionStrategy::weighted(vec![0.5, 0.5]),
557 RankScoreKind::Weighted,
558 1_i64 << 32,
559 SearchSignals {
560 vector_similarity: Some(vector),
561 keyword_score: Some(keyword),
562 },
563 ),
564 (
565 FusionStrategy::Union,
566 RankScoreKind::Union,
567 vector.to_raw(),
568 SearchSignals {
569 vector_similarity: Some(vector),
570 keyword_score: Some(keyword),
571 },
572 ),
573 ] {
574 let hits = rt
575 .fuse_with_strategy(
576 vec![text_hit(id, 0.25, "candidate")],
577 vec![vector_hit(id, 0.75)],
578 &strategy,
579 10,
580 )
581 .await
582 .unwrap();
583 assert_eq!(hits.len(), 1);
584 assert_eq!(hits[0].entity_id, id);
585 assert_eq!(hits[0].score.to_raw(), raw_score);
586 assert_eq!(hits[0].rank_score_kind, kind);
587 assert_eq!(hits[0].signals, signals);
588 }
589 assert_eq!(RankScoreKind::Rrf.as_str(), "rrf");
590 assert_eq!(RankScoreKind::Vector.as_str(), "vector");
591 assert_eq!(RankScoreKind::Keyword.as_str(), "keyword");
592 assert_eq!(RankScoreKind::Weighted.as_str(), "weighted");
593 assert_eq!(RankScoreKind::Union.as_str(), "union");
594 }
595
596 #[tokio::test]
597 async fn fusion_evidence_distinguishes_absence_from_zero() {
598 let rt = evidence_runtime();
599 let id = Uuid::from_u128(1);
600 for (text, vector, signals) in [
601 (
602 vec![text_hit(id, 0.0, "zero keyword")],
603 vec![],
604 SearchSignals {
605 vector_similarity: None,
606 keyword_score: Some(DeterministicScore::ZERO),
607 },
608 ),
609 (
610 vec![],
611 vec![vector_hit(id, 0.0)],
612 SearchSignals {
613 vector_similarity: Some(DeterministicScore::ZERO),
614 keyword_score: None,
615 },
616 ),
617 ] {
618 let hits = rt
619 .fuse_with_strategy(text, vector, &FusionStrategy::rrf(), 10)
620 .await
621 .unwrap();
622 assert_eq!(hits.len(), 1);
623 assert_eq!(hits[0].signals, signals);
624 }
625 assert_eq!(
626 SearchSignals::default(),
627 SearchSignals {
628 vector_similarity: None,
629 keyword_score: None,
630 }
631 );
632 }
633
634 #[tokio::test]
635 async fn fusion_evidence_golden_preserves_true_ties_across_permutations() {
636 let rt = evidence_runtime();
637 let a = Uuid::from_u128(1);
638 let b = Uuid::from_u128(2);
639 let expected = vec![
640 (
641 a,
642 139_682_966,
643 RankScoreKind::Rrf,
644 SearchSignals {
645 vector_similarity: Some(DeterministicScore::from_raw(1_i64 << 31)),
646 keyword_score: Some(DeterministicScore::from_raw(1_i64 << 30)),
647 },
648 ),
649 (
650 b,
651 139_682_966,
652 RankScoreKind::Rrf,
653 SearchSignals {
654 vector_similarity: Some(DeterministicScore::from_raw(1_i64 << 32)),
655 keyword_score: Some(DeterministicScore::from_raw(3_i64 << 30)),
656 },
657 ),
658 ];
659 for (text_ids, vector_ids) in [([a, b], [b, a]), ([b, a], [a, b])] {
660 for _ in 0..4 {
661 let text = text_ids
662 .into_iter()
663 .map(|id| text_hit(id, if id == a { 0.25 } else { 0.75 }, "candidate"))
664 .collect();
665 let vector = vector_ids
666 .into_iter()
667 .map(|id| vector_hit(id, if id == a { 0.5 } else { 1.0 }))
668 .collect();
669 let hits = rt
670 .fuse_with_strategy(text, vector, &FusionStrategy::Rrf { k: 60 }, 10)
671 .await
672 .unwrap();
673 assert_eq!(hits.len(), 2);
674 assert_eq!(hits[0].score, hits[1].score);
675 assert!(hits.iter().all(|hit| hit.source == SearchSource::Both));
676 let snapshot: Vec<_> = hits
677 .iter()
678 .map(|hit| {
679 (
680 hit.entity_id,
681 hit.score.to_raw(),
682 hit.rank_score_kind,
683 hit.signals,
684 )
685 })
686 .collect();
687 assert_eq!(snapshot, expected);
688 }
689 }
690 }
691
692 #[tokio::test]
693 async fn fusion_evidence_duplicate_selection_follows_strategy() {
694 let rt = evidence_runtime();
695 let id = Uuid::from_u128(1);
696 for (strategy, keyword_raw) in [
697 (FusionStrategy::rrf(), 1_i64 << 30),
698 (FusionStrategy::Union, 3_i64 << 30),
699 (FusionStrategy::weighted(vec![0.5, 0.5]), 3_i64 << 30),
700 ] {
701 let hits = rt
702 .fuse_with_strategy(
703 vec![text_hit(id, 0.25, "first"), text_hit(id, 0.75, "second")],
704 vec![vector_hit(id, 0.5)],
705 &strategy,
706 10,
707 )
708 .await
709 .unwrap();
710 assert_eq!(hits.len(), 1);
711 assert_eq!(
712 hits[0].signals,
713 SearchSignals {
714 vector_similarity: Some(DeterministicScore::from_raw(1_i64 << 31)),
715 keyword_score: Some(DeterministicScore::from_raw(keyword_raw)),
716 }
717 );
718 assert_eq!(hits[0].title.as_deref(), Some("first"));
719 }
720 }
721
722 #[tokio::test]
723 async fn weighted_rrf_fusion_reports_the_rrf_kind() {
724 let rt = evidence_runtime();
725 let id = Uuid::from_u128(1);
726 let strategy = FusionStrategy::weighted_rrf(60, vec![1.0, 1.0]);
727 let hits = rt
728 .fuse_with_strategy(vec![text_hit(id, 0.75, "candidate")], vec![], &strategy, 10)
729 .await
730 .unwrap();
731 assert_eq!(hits.len(), 1);
732 assert_eq!(hits[0].rank_score_kind, RankScoreKind::Rrf);
733 }
734
735 #[tokio::test]
736 async fn custom_fusion_evidence_uses_declared_kind() {
737 let rt = evidence_runtime();
738 let id = Uuid::from_u128(1);
739 rt.register_fusion_strategy("invert", Arc::new(InvertScoreExecutor));
740 let strategy =
741 FusionStrategy::try_custom("invert".into(), serde_json::Value::Null).unwrap();
742 let hits = rt
743 .fuse_with_strategy(vec![text_hit(id, 0.75, "candidate")], vec![], &strategy, 10)
744 .await
745 .unwrap();
746 assert_eq!(hits.len(), 1);
747 assert_eq!(hits[0].score.to_raw(), 1_i64 << 30);
748 assert_eq!(hits[0].rank_score_kind, RankScoreKind::Weighted);
749 assert_eq!(
750 hits[0].signals,
751 SearchSignals {
752 vector_similarity: None,
753 keyword_score: Some(DeterministicScore::from_raw(3_i64 << 30)),
754 }
755 );
756 }
757
758 fn cosine_fixture_vector(dimensions: usize, x: f32, y: f32) -> Vec<f32> {
759 let mut vector = vec![0.0; dimensions];
760 vector[0] = x;
761 vector[1] = y;
762 vector
763 }
764
765 async fn stale_full_prefix_fixture() -> (
766 KhiveRuntime,
767 NamespaceToken,
768 &'static str,
769 Vec<f32>,
770 Vec<TextSearchHit>,
771 Vec<VectorSearchHit>,
772 HashSet<Uuid>,
773 ) {
774 let model = EmbeddingModel::AllMiniLmL6V2;
775 let dimensions = model.dimensions();
776 let rt = KhiveRuntime::new(RuntimeConfig {
777 db_path: None,
778 embedding_model: Some(model),
779 additional_embedding_models: vec![],
780 ..RuntimeConfig::default()
781 })
782 .unwrap();
783 let tok = NamespaceToken::local();
784 let query_text = "fusionrefillterm";
785 let query_vector = cosine_fixture_vector(dimensions, 1.0, 0.0);
786
787 let common_stale_a = Uuid::from_u128(1);
788 let common_stale_b = Uuid::from_u128(2);
789 let text_only_stale = Uuid::from_u128(3);
790 let vector_only_stale = Uuid::from_u128(4);
791
792 let live_text = Entity::new("local", "concept", "live text candidate");
793 let live_vector = Entity::new("local", "concept", "live vector candidate");
794 rt.entities(&tok)
795 .unwrap()
796 .upsert_entities(vec![live_text.clone(), live_vector.clone()])
797 .await
798 .unwrap();
799
800 let document = |subject_id, repetitions: usize| TextDocument {
801 subject_id,
802 kind: SubstrateKind::Entity,
803 record_kind: None,
804 namespace: "local".to_string(),
805 title: None,
806 body: std::iter::repeat_n(query_text, repetitions)
807 .collect::<Vec<_>>()
808 .join(" "),
809 tags: vec![],
810 metadata: None,
811 updated_at: Utc::now(),
812 };
813 rt.text(&tok)
814 .unwrap()
815 .upsert_documents(vec![
816 document(common_stale_a, 12),
817 document(common_stale_b, 8),
818 document(text_only_stale, 4),
819 document(live_text.id, 1),
820 ])
821 .await
822 .unwrap();
823
824 let vectors = rt.vectors(&tok).unwrap();
825 for (id, vector) in [
826 (common_stale_a, cosine_fixture_vector(dimensions, 1.0, 0.0)),
827 (common_stale_b, cosine_fixture_vector(dimensions, 0.8, 0.6)),
828 (
829 vector_only_stale,
830 cosine_fixture_vector(dimensions, 0.5, 0.866_025_4),
831 ),
832 (live_vector.id, cosine_fixture_vector(dimensions, -1.0, 0.0)),
833 ] {
834 vectors
835 .insert(
836 id,
837 SubstrateKind::Entity,
838 "local",
839 "entity.body",
840 vec![vector],
841 )
842 .await
843 .unwrap();
844 }
845
846 let text_hits = rt
847 .text(&tok)
848 .unwrap()
849 .search(TextSearchRequest {
850 query: query_text.to_string(),
851 mode: TextQueryMode::Plain,
852 filter: Some(TextFilter {
853 namespaces: vec!["local".to_string()],
854 ..TextFilter::default()
855 }),
856 top_k: CANDIDATE_MULTIPLIER,
857 snippet_chars: 0,
858 })
859 .await
860 .unwrap();
861 let vector_hits = vectors
862 .search(VectorSearchRequest {
863 query_vectors: vec![query_vector.clone()],
864 top_k: CANDIDATE_MULTIPLIER,
865 namespace: Some("local".to_string()),
866 kind: Some(SubstrateKind::Entity),
867 embedding_model: None,
868 filter: None,
869 backend_hints: None,
870 })
871 .await
872 .unwrap();
873
874 assert_eq!(text_hits.len(), CANDIDATE_MULTIPLIER as usize);
875 assert_eq!(vector_hits.len(), CANDIDATE_MULTIPLIER as usize);
876 let live = HashSet::from([live_text.id, live_vector.id]);
877 (
878 rt,
879 tok,
880 query_text,
881 query_vector,
882 text_hits,
883 vector_hits,
884 live,
885 )
886 }
887
888 #[tokio::test]
890 async fn rrf_custom_k_differs_from_k60() {
891 let rt = KhiveRuntime::memory().unwrap();
892 let a = Uuid::new_v4();
893 let b = Uuid::new_v4();
894 let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
898 let hits_k1 = rt
899 .fuse_with_strategy(text.clone(), vec![], &FusionStrategy::Rrf { k: 1 }, 10)
900 .await
901 .unwrap();
902 let hits_k60 = rt
903 .fuse_with_strategy(text, vec![], &FusionStrategy::Rrf { k: 60 }, 10)
904 .await
905 .unwrap();
906 assert_eq!(hits_k1[0].entity_id, a);
908 assert_eq!(hits_k60[0].entity_id, a);
909 assert!(hits_k1[0].score > hits_k60[0].score);
911 }
912
913 #[tokio::test]
915 async fn weighted_ordering_depends_on_weights() {
916 let rt = KhiveRuntime::memory().unwrap();
917 let a = Uuid::new_v4();
918 let b = Uuid::new_v4();
919 let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
921 let vec_hits = vec![vector_hit(b, 0.9), vector_hit(a, 0.1)];
922
923 let heavy_vector = rt
924 .fuse_with_strategy(
925 text.clone(),
926 vec_hits.clone(),
927 &FusionStrategy::Weighted {
928 weights: vec![0.7, 0.3],
929 },
930 10,
931 )
932 .await
933 .unwrap();
934 let heavy_keyword = rt
935 .fuse_with_strategy(
936 text,
937 vec_hits,
938 &FusionStrategy::Weighted {
939 weights: vec![0.3, 0.7],
940 },
941 10,
942 )
943 .await
944 .unwrap();
945
946 assert_eq!(heavy_vector[0].entity_id, b);
947 assert_eq!(heavy_keyword[0].entity_id, a);
948 }
949
950 #[tokio::test]
952 async fn weighted_scale_invariant() {
953 let rt = KhiveRuntime::memory().unwrap();
954 let a = Uuid::new_v4();
955 let b = Uuid::new_v4();
956 let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
957 let vec_hits = vec![vector_hit(b, 0.9), vector_hit(a, 0.1)];
958
959 let w1 = rt
960 .fuse_with_strategy(
961 text.clone(),
962 vec_hits.clone(),
963 &FusionStrategy::Weighted {
964 weights: vec![0.7, 0.3],
965 },
966 10,
967 )
968 .await
969 .unwrap();
970 let w2 = rt
971 .fuse_with_strategy(
972 text,
973 vec_hits,
974 &FusionStrategy::Weighted {
975 weights: vec![7.0, 3.0],
976 },
977 10,
978 )
979 .await
980 .unwrap();
981
982 assert_eq!(w1[0].entity_id, w2[0].entity_id);
983 assert_eq!(w1[1].entity_id, w2[1].entity_id);
984 let diff = (w1[0].score.to_f64() - w2[0].score.to_f64()).abs();
985 assert!(diff < 1e-9, "scores differ by {diff}");
986 }
987
988 #[tokio::test]
990 async fn weighted_zero_weights_equal_fallback() {
991 let rt = KhiveRuntime::memory().unwrap();
992 let a = Uuid::new_v4();
993 let b = Uuid::new_v4();
994 let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
996 let vec_hits = vec![vector_hit(a, 0.9), vector_hit(b, 0.1)];
997
998 let hits = rt
999 .fuse_with_strategy(
1000 text,
1001 vec_hits,
1002 &FusionStrategy::Weighted {
1003 weights: vec![0.0, 0.0],
1004 },
1005 10,
1006 )
1007 .await
1008 .unwrap();
1009 assert_eq!(hits[0].entity_id, a);
1010 }
1011
1012 #[tokio::test]
1014 async fn weighted_negative_weight_clamped() {
1015 let rt = KhiveRuntime::memory().unwrap();
1016 let a = Uuid::new_v4();
1017 let text = vec![text_hit(a, 0.9, "a")];
1018 let hits = rt
1020 .fuse_with_strategy(
1021 text,
1022 vec![],
1023 &FusionStrategy::Weighted {
1024 weights: vec![-0.5, 1.0],
1025 },
1026 10,
1027 )
1028 .await
1029 .unwrap();
1030 assert_eq!(hits.len(), 1);
1031 assert_eq!(hits[0].entity_id, a);
1032 }
1033
1034 #[tokio::test]
1035 async fn weighted_empty_arm_keeps_canonical_position() {
1036 let rt = KhiveRuntime::memory().unwrap();
1037 let text_only = Uuid::new_v4();
1038 let hits = rt
1039 .fuse_with_strategy(
1040 vec![text_hit(text_only, 0.9, "text")],
1041 vec![],
1042 &FusionStrategy::Weighted {
1043 weights: vec![1.0, 0.0],
1045 },
1046 10,
1047 )
1048 .await
1049 .unwrap();
1050 assert!(
1051 hits.is_empty(),
1052 "dropping the empty vector arm would incorrectly rebind text to its weight"
1053 );
1054 }
1055
1056 #[tokio::test]
1058 async fn union_max_score_per_entity() {
1059 let rt = KhiveRuntime::memory().unwrap();
1060 let a = Uuid::new_v4();
1061 let text = vec![text_hit(a, 0.3, "a")];
1062 let vec_hits = vec![vector_hit(a, 0.9)];
1063
1064 let hits = rt
1065 .fuse_with_strategy(text, vec_hits, &FusionStrategy::Union, 10)
1066 .await
1067 .unwrap();
1068 assert_eq!(hits.len(), 1);
1069 assert!((hits[0].score.to_f64() - 0.9).abs() < 1e-6);
1070 assert_eq!(hits[0].source, SearchSource::Both);
1071 }
1072
1073 #[tokio::test]
1075 async fn vector_only_drops_text() {
1076 let rt = KhiveRuntime::memory().unwrap();
1077 let a = Uuid::new_v4();
1078 let b = Uuid::new_v4();
1079 let text = vec![text_hit(b, 0.9, "b")];
1080 let vec_hits = vec![vector_hit(a, 0.8)];
1081
1082 let hits = rt
1083 .fuse_with_strategy(text, vec_hits, &FusionStrategy::VectorOnly, 10)
1084 .await
1085 .unwrap();
1086 assert_eq!(hits.len(), 1);
1087 assert_eq!(hits[0].entity_id, a);
1088 assert_eq!(hits[0].source, SearchSource::Vector);
1089 assert!(hits[0].title.is_none());
1090 }
1091
1092 #[tokio::test]
1093 async fn keyword_only_drops_vector() {
1094 let rt = KhiveRuntime::memory().unwrap();
1095 let text_id = Uuid::new_v4();
1096 let vector_id = Uuid::new_v4();
1097 let hits = rt
1098 .fuse_with_strategy(
1099 vec![text_hit(text_id, 0.8, "text")],
1100 vec![vector_hit(vector_id, 0.9)],
1101 &FusionStrategy::KeywordOnly,
1102 10,
1103 )
1104 .await
1105 .unwrap();
1106 assert_eq!(hits.len(), 1);
1107 assert_eq!(hits[0].entity_id, text_id);
1108 assert_eq!(hits[0].source, SearchSource::Text);
1109 }
1110
1111 struct ReverseOrderExecutor;
1114
1115 #[async_trait::async_trait]
1116 impl FusionExecutor for ReverseOrderExecutor {
1117 fn rank_score_kind(&self) -> RankScoreKind {
1118 RankScoreKind::Union
1119 }
1120
1121 async fn fuse(
1122 &self,
1123 streams: Vec<CandidateStream>,
1124 _params: &serde_json::Value,
1125 _limit: usize,
1126 ) -> RuntimeResult<Vec<RankedHit>> {
1127 let mut flat: Vec<_> = streams.into_iter().flatten().collect();
1128 flat.reverse();
1129 Ok(flat)
1130 }
1131 }
1132
1133 struct InvertScoreExecutor;
1139
1140 #[async_trait::async_trait]
1141 impl FusionExecutor for InvertScoreExecutor {
1142 fn rank_score_kind(&self) -> RankScoreKind {
1143 RankScoreKind::Weighted
1144 }
1145
1146 async fn fuse(
1147 &self,
1148 streams: Vec<CandidateStream>,
1149 _params: &serde_json::Value,
1150 _limit: usize,
1151 ) -> RuntimeResult<Vec<RankedHit>> {
1152 Ok(streams
1153 .into_iter()
1154 .flatten()
1155 .map(|(id, score)| (id, DeterministicScore::from_f64(1.0 - score.to_f64())))
1156 .collect())
1157 }
1158 }
1159
1160 struct EqualScoreExecutor;
1165
1166 #[async_trait::async_trait]
1167 impl FusionExecutor for EqualScoreExecutor {
1168 fn rank_score_kind(&self) -> RankScoreKind {
1169 RankScoreKind::Weighted
1170 }
1171
1172 async fn fuse(
1173 &self,
1174 streams: Vec<CandidateStream>,
1175 _params: &serde_json::Value,
1176 _limit: usize,
1177 ) -> RuntimeResult<Vec<RankedHit>> {
1178 Ok(streams
1179 .into_iter()
1180 .flatten()
1181 .map(|(id, _)| (id, DeterministicScore::from_f64(1.0)))
1182 .collect())
1183 }
1184 }
1185
1186 #[tokio::test]
1189 async fn custom_strategy_dispatches_through_executor_and_differs_from_rrf() {
1190 let rt = KhiveRuntime::memory().unwrap();
1191 let a = Uuid::new_v4();
1192 let b = Uuid::new_v4();
1193 let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.5, "b")];
1194
1195 rt.register_fusion_strategy("invert", Arc::new(InvertScoreExecutor));
1196 let strategy =
1197 FusionStrategy::try_custom("invert".to_string(), serde_json::Value::Null).unwrap();
1198
1199 let custom = rt
1200 .fuse_with_strategy(text.clone(), vec![], &strategy, 10)
1201 .await
1202 .unwrap();
1203 let rrf = rt
1204 .fuse_with_strategy(text, vec![], &FusionStrategy::rrf(), 10)
1205 .await
1206 .unwrap();
1207
1208 let custom_ids: Vec<_> = custom.iter().map(|h| h.entity_id).collect();
1209 let rrf_ids: Vec<_> = rrf.iter().map(|h| h.entity_id).collect();
1210 assert_ne!(
1211 custom_ids, rrf_ids,
1212 "custom and RRF must yield different orderings on this fixture"
1213 );
1214 }
1215
1216 #[tokio::test]
1218 async fn custom_strategy_unknown_name_fails_closed() {
1219 let rt = KhiveRuntime::memory().unwrap();
1220 let a = Uuid::new_v4();
1221 let text = vec![text_hit(a, 0.9, "a")];
1222 let strategy =
1223 FusionStrategy::try_custom("nonexistent".to_string(), serde_json::Value::Null).unwrap();
1224
1225 let result = rt.fuse_with_strategy(text, vec![], &strategy, 10).await;
1226 assert!(matches!(
1227 result,
1228 Err(RuntimeError::UnknownFusionStrategy(name)) if name == "nonexistent"
1229 ));
1230 }
1231
1232 #[tokio::test]
1235 async fn custom_strategy_unknown_name_fails_closed_even_on_empty_input() {
1236 let rt = KhiveRuntime::memory().unwrap();
1237 let strategy =
1238 FusionStrategy::try_custom("nonexistent".to_string(), serde_json::Value::Null).unwrap();
1239
1240 let result = rt.fuse_with_strategy(vec![], vec![], &strategy, 10).await;
1241 assert!(matches!(
1242 result,
1243 Err(RuntimeError::UnknownFusionStrategy(name)) if name == "nonexistent"
1244 ));
1245 }
1246
1247 #[tokio::test]
1250 async fn custom_strategy_registered_name_empty_input_returns_ok_empty() {
1251 let rt = KhiveRuntime::memory().unwrap();
1252 rt.register_fusion_strategy("reverse", Arc::new(ReverseOrderExecutor));
1253 let strategy =
1254 FusionStrategy::try_custom("reverse".to_string(), serde_json::Value::Null).unwrap();
1255
1256 let result = rt
1257 .fuse_with_strategy(vec![], vec![], &strategy, 10)
1258 .await
1259 .unwrap();
1260 assert!(result.is_empty());
1261 }
1262
1263 #[tokio::test]
1265 async fn registered_custom_strategy_leaves_default_path_unaffected() {
1266 let rt = KhiveRuntime::memory().unwrap();
1267 let a = Uuid::new_v4();
1268 let b = Uuid::new_v4();
1269 let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.5, "b")];
1270
1271 rt.register_fusion_strategy("reverse", Arc::new(ReverseOrderExecutor));
1272
1273 let via_rt_with_registration = rt
1274 .fuse_with_strategy(text.clone(), vec![], &FusionStrategy::rrf(), 10)
1275 .await
1276 .unwrap();
1277 let rt2 = KhiveRuntime::memory().unwrap();
1278 let via_rt_without_registration = rt2
1279 .fuse_with_strategy(text, vec![], &FusionStrategy::rrf(), 10)
1280 .await
1281 .unwrap();
1282
1283 let ids_with: Vec<_> = via_rt_with_registration
1284 .iter()
1285 .map(|h| h.entity_id)
1286 .collect();
1287 let ids_without: Vec<_> = via_rt_without_registration
1288 .iter()
1289 .map(|h| h.entity_id)
1290 .collect();
1291 assert_eq!(ids_with, ids_without);
1292 }
1293
1294 #[tokio::test]
1298 async fn custom_executor_output_is_sorted_by_canonical_comparator() {
1299 let rt = KhiveRuntime::memory().unwrap();
1300 let ids: Vec<Uuid> = vec![Uuid::from_u128(3), Uuid::from_u128(1), Uuid::from_u128(2)];
1302 let text: Vec<TextSearchHit> = ids.iter().map(|&id| text_hit(id, 0.5, "tied")).collect();
1303
1304 rt.register_fusion_strategy("equal_score", Arc::new(EqualScoreExecutor));
1305 let strategy =
1306 FusionStrategy::try_custom("equal_score".to_string(), serde_json::Value::Null).unwrap();
1307
1308 let hits = rt
1309 .fuse_with_strategy(text, vec![], &strategy, 10)
1310 .await
1311 .unwrap();
1312
1313 let mut expected = ids.clone();
1314 expected.sort();
1315 let actual: Vec<_> = hits.iter().map(|h| h.entity_id).collect();
1316 assert_eq!(
1317 actual, expected,
1318 "equal-score executor output must be tie-broken by ascending ID"
1319 );
1320 }
1321
1322 #[test]
1324 fn default_strategy_is_rrf_k60() {
1325 assert_eq!(FusionStrategy::default(), FusionStrategy::Rrf { k: 60 });
1326 }
1327
1328 #[tokio::test]
1329 async fn hybrid_union_alive_filter_refills_below_complete_four_x_prefix() {
1330 let (rt, tok, query_text, query_vector, text_hits, vector_hits, live) =
1331 stale_full_prefix_fixture().await;
1332 let truncated = rt
1333 .fuse_with_strategy(
1334 text_hits,
1335 vector_hits,
1336 &FusionStrategy::Union,
1337 CANDIDATE_MULTIPLIER as usize,
1338 )
1339 .await
1340 .unwrap();
1341 assert!(truncated.iter().all(|hit| !live.contains(&hit.entity_id)));
1342
1343 let hits = rt
1344 .hybrid_search_with_strategy(
1345 &tok,
1346 query_text,
1347 Some(query_vector),
1348 FusionStrategy::Union,
1349 1,
1350 )
1351 .await
1352 .unwrap();
1353
1354 assert_eq!(hits.len(), 1);
1355 assert!(live.contains(&hits[0].entity_id));
1356 }
1357
1358 #[tokio::test]
1359 async fn hybrid_rrf_alive_filter_refills_below_complete_four_x_prefix() {
1360 let (rt, tok, query_text, query_vector, text_hits, vector_hits, live) =
1361 stale_full_prefix_fixture().await;
1362 let strategy = FusionStrategy::Rrf { k: 60 };
1363 let truncated = rt
1364 .fuse_with_strategy(
1365 text_hits,
1366 vector_hits,
1367 &strategy,
1368 CANDIDATE_MULTIPLIER as usize,
1369 )
1370 .await
1371 .unwrap();
1372 assert!(truncated.iter().all(|hit| !live.contains(&hit.entity_id)));
1373
1374 let hits = rt
1375 .hybrid_search_with_strategy(&tok, query_text, Some(query_vector), strategy, 1)
1376 .await
1377 .unwrap();
1378
1379 assert_eq!(hits.len(), 1);
1380 assert!(live.contains(&hits[0].entity_id));
1381 }
1382
1383 #[tokio::test]
1384 async fn hybrid_default_rrf_alive_filter_refills_below_complete_four_x_prefix() {
1385 let (rt, tok, query_text, query_vector, _text_hits, _vector_hits, live) =
1386 stale_full_prefix_fixture().await;
1387
1388 let hits = rt
1389 .hybrid_search(
1390 &tok,
1391 query_text,
1392 Some(query_vector),
1393 1,
1394 None,
1395 None,
1396 &[],
1397 None,
1398 )
1399 .await
1400 .unwrap();
1401
1402 assert_eq!(hits.len(), 1);
1403 assert!(live.contains(&hits[0].entity_id));
1404 }
1405
1406 #[test]
1408 fn serde_roundtrip() {
1409 let cases = vec![
1410 FusionStrategy::Rrf { k: 60 },
1411 FusionStrategy::Rrf { k: 20 },
1412 FusionStrategy::Weighted {
1413 weights: vec![0.7, 0.3],
1414 },
1415 FusionStrategy::Union,
1416 FusionStrategy::VectorOnly,
1417 FusionStrategy::KeywordOnly,
1418 ];
1419 for strategy in cases {
1420 let json = serde_json::to_string(&strategy).expect("serialize");
1421 let back: FusionStrategy = serde_json::from_str(&json).expect("deserialize");
1422 assert_eq!(strategy, back, "roundtrip failed for {json}");
1423 }
1424 }
1425
1426 #[tokio::test]
1431 async fn hybrid_search_with_strategy_dollar_sign_query_does_not_error() {
1432 let rt = KhiveRuntime::memory().unwrap();
1433 let tok = NamespaceToken::local();
1434 rt.create_entity(
1435 &tok,
1436 "concept",
1437 None,
1438 "DSL docs",
1439 Some("use $prev.id to chain calls"),
1440 None,
1441 vec![],
1442 )
1443 .await
1444 .unwrap();
1445
1446 let result = rt
1447 .hybrid_search_with_strategy(&tok, "$prev.id", None, FusionStrategy::default(), 10)
1448 .await;
1449
1450 assert!(
1451 result.is_ok(),
1452 "#388 hybrid_search_with_strategy must not hard-fail on a '$'-bearing query, got: {:?}",
1453 result.err()
1454 );
1455 }
1456
1457 #[tokio::test]
1463 async fn hybrid_search_with_strategy_residual_fts5_char_now_sanitized() {
1464 let rt = KhiveRuntime::memory().unwrap();
1465 let tok = NamespaceToken::local();
1466 rt.create_entity(
1467 &tok,
1468 "concept",
1469 None,
1470 "DSL docs",
1471 Some("use foo@bar to chain calls"),
1472 None,
1473 vec![],
1474 )
1475 .await
1476 .unwrap();
1477
1478 let result = rt
1479 .hybrid_search_with_strategy(&tok, "foo@bar", None, FusionStrategy::default(), 10)
1480 .await;
1481
1482 let hits = result.unwrap_or_else(|e| {
1483 panic!(
1484 "#916 hybrid_search_with_strategy must not fail on an '@'-bearing query, got: {e:?}"
1485 )
1486 });
1487 assert!(
1488 !hits.is_empty(),
1489 "#916 '@'-bearing query must still find the seeded 'foo@bar' content via the \
1490 quoted-phrase alternative"
1491 );
1492 }
1493}