Skip to main content

khive_runtime/
fusion.rs

1//! Fusion strategies for combining ranked result lists.
2
3use 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
22/// A single ranked candidate stream fed into a [`FusionExecutor`] โ€” the
23/// entity/note ID keyed shape used throughout hybrid search (ADR-012
24/// `FusionStrategy::Custom` ยง"strategy executor").
25pub type CandidateStream = Vec<(Uuid, DeterministicScore)>;
26
27/// One fused, ranked `(id, score)` pair returned by a [`FusionExecutor`].
28pub type RankedHit = (Uuid, DeterministicScore);
29
30/// Runtime-registered custom fusion strategy (ADR-012).
31///
32/// Packs implement this to plug a strategy into `FusionStrategy::Custom { name,
33/// .. }` via [`KhiveRuntime::register_fusion_strategy`] โ€” the seam a
34/// learned-sparse (SPLADE) retrieval leg plugs into. Async so an executor can
35/// perform I/O (e.g. a decay/posterior lookup) while fusing, and fallible so
36/// it can reject malformed `params` instead of degrading silently.
37#[async_trait::async_trait]
38pub trait FusionExecutor: Send + Sync + 'static {
39    /// Declare the strategy represented by the executor's ordering score.
40    fn rank_score_kind(&self) -> RankScoreKind;
41
42    /// Combine `streams` into a single ranked list, honoring `limit` as a
43    /// hint (the dispatch boundary re-sorts and truncates the result with the
44    /// crate's canonical comparator regardless, so an executor need not sort
45    /// or truncate defensively itself).
46    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    /// Fuse text and vector hits using the given strategy, returning at most
56    /// `limit` results. Positional weighted strategies use `[vector, keyword]`
57    /// order.
58    ///
59    /// `FusionStrategy::Custom { name, .. }` is resolved against this
60    /// runtime's registered executors (see
61    /// [`register_fusion_strategy`](KhiveRuntime::register_fusion_strategy)).
62    /// An unregistered name fails closed with
63    /// `RuntimeError::UnknownFusionStrategy` rather than silently falling
64    /// back to RRF.
65    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        // Canonical positional order is [vector, keyword]. Empty arms remain in
155        // place: removing one would shift the surviving arm onto the wrong weight.
156        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    /// Resolve `strategy` against either the built-in `khive-fusion`
172    /// dispatcher or a registered [`FusionExecutor`], applying the crate's
173    /// canonical score-desc/id-asc ordering at the boundary either way.
174    ///
175    /// `Custom` names are resolved *before* the empty-input/zero-limit short
176    /// circuit, so a misconfigured name errors on every call -- including
177    /// zero-result ones -- rather than being indistinguishable from a valid
178    /// empty result.
179    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        // Filter out soft-deleted entities. A single query fetches all alive IDs from the
214        // fused candidate pool; any ID absent from the result has been soft-deleted.
215        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    /// Hybrid search with a caller-supplied fusion strategy.
240    ///
241    /// `FusionStrategy::Custom { name, .. }` is resolved against this
242    /// runtime's registered executors (see
243    /// [`register_fusion_strategy`](KhiveRuntime::register_fusion_strategy));
244    /// an unregistered name fails closed with
245    /// `RuntimeError::UnknownFusionStrategy`.
246    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            // sanitize_fts5_query strips known-unsafe metacharacters, but residual
261            // punctuation can still trip the FTS5 parser at runtime; that error must
262            // fail loud rather than silently degrade to vector-only fusion. Errors
263            // from other legs (vector search) still propagate normally.
264            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        // Each arm fetched `candidates` independently, so their union can contain
300        // twice that many distinct IDs. Keep the complete fetched pool through
301        // ranking and the alive check; truncating it first lets stale hits hide
302        // live candidates from the other arm.
303        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    // 1. RRF with custom k produces different ordering than k=60
889    #[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        // Single-source input makes a and b tie in relative order at both k values,
895        // so assert on raw score magnitude (smaller k widens the rank-1-vs-rank-2 gap)
896        // rather than ordering.
897        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        // Both should have a first (rank 1 always wins in single-source)
907        assert_eq!(hits_k1[0].entity_id, a);
908        assert_eq!(hits_k60[0].entity_id, a);
909        // k=1 produces higher raw score for rank 1 than k=60
910        assert!(hits_k1[0].score > hits_k60[0].score);
911    }
912
913    // 2. Canonical [vector, keyword] weights change ordering as documented.
914    #[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        // a scores high in text, b scores high in vector
920        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    // 3. Weighted [7.0, 3.0] = Weighted [0.7, 0.3] (normalization)
951    #[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    // 4. Weighted [0.0, 0.0] falls back to equal weights
989    #[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        // Both sources agree: a > b
995        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    // 5. Weighted with negative weight clamps to 0
1013    #[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        // Negative vector weight โ†’ only keyword/text contributes.
1019        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                    // Canonical [vector, keyword]: the only non-empty arm has zero weight.
1044                    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    // 6. Union returns max score per entity when same id appears in both lists
1057    #[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    // 7. VectorOnly returns vector hits only (text hits dropped)
1074    #[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    /// Test-only executor: flattens all streams and reverses their order,
1112    /// keeping each candidate's original score.
1113    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    /// Test-only executor: inverts each candidate's score (`1.0 - score`) so
1134    /// the fused ranking is the reverse of what score-descending built-ins
1135    /// (RRF, Union, Weighted) would produce on the same fixture -- unlike a
1136    /// mere insertion-order reversal, this survives the dispatch boundary's
1137    /// canonical re-sort, since the *scores* (not just the order) differ.
1138    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    /// Test-only executor: returns every candidate at an identical score, in
1161    /// the arbitrary order the input streams happened to flatten to -- used
1162    /// to prove the dispatch boundary re-sorts by the canonical comparator
1163    /// rather than trusting executor output order.
1164    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    // 7b. A registered custom executor dispatches and yields a different
1187    // ranking than RRF on the same fixture.
1188    #[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    // 7c. An unregistered Custom name fails closed rather than falling back to RRF.
1217    #[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    // 7d. Unknown name errors even with empty sources -- it must not be
1233    // indistinguishable from a valid empty result.
1234    #[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    // 7e. Empty sources with a *registered* name is a valid empty result, not
1248    // an error -- distinguishing "misconfigured" from "genuinely nothing".
1249    #[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    // 7f. Registering a custom strategy never perturbs the default (non-Custom) path.
1264    #[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    // 7g. A custom executor returning equal-score IDs in arbitrary/reversed
1295    // order still yields the crate's canonical score-desc/id-asc order --
1296    // the dispatch boundary re-sorts rather than trusting executor output.
1297    #[tokio::test]
1298    async fn custom_executor_output_is_sorted_by_canonical_comparator() {
1299        let rt = KhiveRuntime::memory().unwrap();
1300        // Deliberately not in ID order, so a passthrough bug would be visible.
1301        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    // 8. Default strategy is Rrf{k:60}
1323    #[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    // 9. Roundtrip serde preserves variant
1407    #[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    // 10. hybrid_search_with_strategy must not hard-fail on a query containing FTS5
1427    // metacharacters like `$`, since sanitize_fts5_query strips them before the query
1428    // reaches SQLite. This covers the sanitizer path; test 11 covers the fail-loud
1429    // path for characters the sanitizer does not strip.
1430    #[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    // 11. #916: `@` used to reach SQLite FTS5's bareword parser raw and error,
1458    // surfacing as RuntimeError::InvalidInput per #569's fail-loud policy.
1459    // sanitize_fts5_token_group's bareword-safety gate now routes it through the
1460    // quoted-phrase alternative instead, so the query succeeds and the fail-loud
1461    // arm is no longer reached for ordinary punctuation.
1462    #[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}