Skip to main content

khive_runtime/
fusion.rs

1//! Fusion strategies for combining ranked result lists.
2
3use std::collections::{hash_map::Entry, HashMap, HashSet};
4
5use uuid::Uuid;
6
7use khive_score::DeterministicScore;
8use khive_storage::types::{
9    PageRequest, TextFilter, TextQueryMode, TextSearchHit, TextSearchRequest, VectorSearchHit,
10};
11use khive_storage::EntityFilter;
12use khive_types::SubstrateKind;
13
14use crate::error::{RuntimeError, RuntimeResult};
15use crate::retrieval::{SearchHit, SearchSource};
16use crate::runtime::{KhiveRuntime, NamespaceToken};
17
18pub use khive_fusion::FusionStrategy;
19
20const CANDIDATE_MULTIPLIER: u32 = 4;
21
22/// Fuse text and vector hits using the given strategy, returning at most `limit` results.
23/// Positional weighted strategies use `[vector, keyword]` order.
24pub fn fuse_with_strategy(
25    text_hits: Vec<TextSearchHit>,
26    vector_hits: Vec<VectorSearchHit>,
27    strategy: &FusionStrategy,
28    limit: usize,
29) -> RuntimeResult<Vec<SearchHit>> {
30    match strategy {
31        FusionStrategy::VectorOnly => fuse_sources(Vec::new(), vector_hits, strategy, limit),
32        FusionStrategy::KeywordOnly => fuse_sources(text_hits, Vec::new(), strategy, limit),
33        FusionStrategy::Rrf { .. } | FusionStrategy::Weighted { .. } | FusionStrategy::Union => {
34            fuse_sources(text_hits, vector_hits, strategy, limit)
35        }
36        FusionStrategy::Custom { ref name, .. } => {
37            Err(khive_fusion::FuseError::CustomRequiresRuntime(name.clone()).into())
38        }
39    }
40}
41
42/// RRF convenience wrapper used by operations.rs (k=60 note search path).
43pub(crate) fn rrf_fuse_k(
44    text_hits: Vec<TextSearchHit>,
45    vector_hits: Vec<VectorSearchHit>,
46    k: usize,
47    limit: usize,
48) -> RuntimeResult<Vec<SearchHit>> {
49    fuse_with_strategy(text_hits, vector_hits, &FusionStrategy::Rrf { k }, limit)
50}
51
52fn fuse_sources(
53    text_hits: Vec<TextSearchHit>,
54    vector_hits: Vec<VectorSearchHit>,
55    strategy: &FusionStrategy,
56    limit: usize,
57) -> RuntimeResult<Vec<SearchHit>> {
58    let mut metadata: HashMap<Uuid, SearchHit> =
59        HashMap::with_capacity(text_hits.len() + vector_hits.len());
60
61    let text_source: Vec<(Uuid, DeterministicScore)> = text_hits
62        .into_iter()
63        .map(|h| {
64            let hit = SearchHit {
65                entity_id: h.subject_id,
66                score: h.score,
67                source: SearchSource::Text,
68                title: h.title,
69                snippet: h.snippet,
70            };
71            let id = hit.entity_id;
72            let score = hit.score;
73            merge_metadata(&mut metadata, hit);
74            (id, score)
75        })
76        .collect();
77
78    let vector_source: Vec<(Uuid, DeterministicScore)> = vector_hits
79        .into_iter()
80        .map(|h| {
81            let hit = SearchHit {
82                entity_id: h.subject_id,
83                score: h.score,
84                source: SearchSource::Vector,
85                title: None,
86                snippet: None,
87            };
88            let id = hit.entity_id;
89            let score = hit.score;
90            merge_metadata(&mut metadata, hit);
91            (id, score)
92        })
93        .collect();
94
95    // Canonical positional order is [vector, keyword]. Empty arms remain in
96    // place: removing one would shift the surviving arm onto the wrong weight.
97    let sources: Vec<Vec<(Uuid, DeterministicScore)>> = vec![vector_source, text_source];
98
99    Ok(khive_fusion::fuse(sources, strategy, limit)?
100        .into_iter()
101        .filter_map(|(id, score)| {
102            let mut hit = metadata.remove(&id)?;
103            hit.score = score;
104            Some(hit)
105        })
106        .collect())
107}
108
109fn merge_metadata(metadata: &mut HashMap<Uuid, SearchHit>, hit: SearchHit) {
110    match metadata.entry(hit.entity_id) {
111        Entry::Occupied(mut entry) => {
112            let existing = entry.get_mut();
113            existing.source = merge_sources(existing.source, hit.source);
114            if existing.title.is_none() {
115                existing.title = hit.title;
116            }
117            if existing.snippet.is_none() {
118                existing.snippet = hit.snippet;
119            }
120        }
121        Entry::Vacant(entry) => {
122            entry.insert(hit);
123        }
124    }
125}
126
127fn merge_sources(left: SearchSource, right: SearchSource) -> SearchSource {
128    match (left, right) {
129        (SearchSource::Both, _) | (_, SearchSource::Both) => SearchSource::Both,
130        (SearchSource::Text, SearchSource::Vector) | (SearchSource::Vector, SearchSource::Text) => {
131            SearchSource::Both
132        }
133        (SearchSource::Text, SearchSource::Text) => SearchSource::Text,
134        (SearchSource::Vector, SearchSource::Vector) => SearchSource::Vector,
135    }
136}
137
138impl KhiveRuntime {
139    async fn retain_alive_search_hits(
140        &self,
141        token: &NamespaceToken,
142        mut fused: Vec<SearchHit>,
143        limit: usize,
144    ) -> RuntimeResult<Vec<SearchHit>> {
145        // Filter out soft-deleted entities. A single query fetches all alive IDs from the
146        // fused candidate pool; any ID absent from the result has been soft-deleted.
147        if !fused.is_empty() {
148            let candidate_ids: Vec<Uuid> = fused.iter().map(|h| h.entity_id).collect();
149            let alive_page = self
150                .entities(token)?
151                .query_entities(
152                    token.namespace().as_str(),
153                    EntityFilter {
154                        ids: candidate_ids,
155                        ..EntityFilter::default()
156                    },
157                    PageRequest {
158                        offset: 0,
159                        limit: u32::try_from(fused.len()).unwrap_or(u32::MAX),
160                    },
161                )
162                .await?;
163            let alive: HashSet<Uuid> = alive_page.items.into_iter().map(|e| e.id).collect();
164            fused.retain(|h| alive.contains(&h.entity_id));
165        }
166
167        fused.truncate(limit);
168        Ok(fused)
169    }
170
171    /// Hybrid search with a caller-supplied fusion strategy.
172    pub async fn hybrid_search_with_strategy(
173        &self,
174        token: &NamespaceToken,
175        query_text: &str,
176        query_vector: Option<Vec<f32>>,
177        strategy: FusionStrategy,
178        limit: u32,
179    ) -> RuntimeResult<Vec<SearchHit>> {
180        let candidates = limit.saturating_mul(CANDIDATE_MULTIPLIER).max(limit);
181
182        let ns = token.namespace().as_str().to_owned();
183        // sanitize_fts5_query strips known-unsafe metacharacters, but residual
184        // punctuation can still trip the FTS5 parser at runtime; that error must
185        // fail loud rather than silently degrade to vector-only fusion. Errors
186        // from other legs (vector search) still propagate normally.
187        let text_search_result = self
188            .text(token)?
189            .search(TextSearchRequest {
190                query: query_text.to_string(),
191                mode: TextQueryMode::Plain,
192                filter: Some(TextFilter {
193                    namespaces: vec![ns.clone()],
194                    ..TextFilter::default()
195                }),
196                top_k: candidates,
197                snippet_chars: 200,
198            })
199            .await;
200        let text_hits = crate::error::fts_text_leg_or_err(
201            text_search_result.map_err(RuntimeError::from),
202            "hybrid_search_with_strategy",
203            query_text,
204        )?;
205
206        let vector_hits = if query_vector.is_some() || self.config().embedding_model.is_some() {
207            self.vector_search(
208                token,
209                query_vector,
210                Some(query_text),
211                candidates,
212                Some(SubstrateKind::Entity),
213            )
214            .await?
215        } else {
216            Vec::new()
217        };
218
219        // Each arm fetched `candidates` independently, so their union can contain
220        // twice that many distinct IDs. Keep the complete fetched pool through
221        // ranking and the alive check; truncating it first lets stale hits hide
222        // live candidates from the other arm.
223        let fusion_limit = text_hits.len().saturating_add(vector_hits.len());
224        let fused = fuse_with_strategy(text_hits, vector_hits, &strategy, fusion_limit)?;
225        self.retain_alive_search_hits(token, fused, limit as usize)
226            .await
227    }
228}
229
230#[cfg(test)]
231mod tests {
232    use super::*;
233    use chrono::Utc;
234    use khive_storage::types::{TextDocument, TextSearchHit, VectorSearchHit, VectorSearchRequest};
235    use khive_storage::Entity;
236    use lattice_embed::EmbeddingModel;
237
238    use crate::RuntimeConfig;
239
240    fn text_hit(id: Uuid, score: f64, title: &str) -> TextSearchHit {
241        TextSearchHit {
242            subject_id: id,
243            score: DeterministicScore::from_f64(score),
244            rank: 1,
245            title: Some(title.to_string()),
246            snippet: Some("...".to_string()),
247        }
248    }
249
250    fn vector_hit(id: Uuid, score: f64) -> VectorSearchHit {
251        VectorSearchHit {
252            subject_id: id,
253            score: DeterministicScore::from_f64(score),
254            rank: 1,
255        }
256    }
257
258    fn cosine_fixture_vector(dimensions: usize, x: f32, y: f32) -> Vec<f32> {
259        let mut vector = vec![0.0; dimensions];
260        vector[0] = x;
261        vector[1] = y;
262        vector
263    }
264
265    async fn stale_full_prefix_fixture() -> (
266        KhiveRuntime,
267        NamespaceToken,
268        &'static str,
269        Vec<f32>,
270        Vec<TextSearchHit>,
271        Vec<VectorSearchHit>,
272        HashSet<Uuid>,
273    ) {
274        let model = EmbeddingModel::AllMiniLmL6V2;
275        let dimensions = model.dimensions();
276        let rt = KhiveRuntime::new(RuntimeConfig {
277            db_path: None,
278            embedding_model: Some(model),
279            additional_embedding_models: vec![],
280            ..RuntimeConfig::default()
281        })
282        .unwrap();
283        let tok = NamespaceToken::local();
284        let query_text = "fusionrefillterm";
285        let query_vector = cosine_fixture_vector(dimensions, 1.0, 0.0);
286
287        let common_stale_a = Uuid::from_u128(1);
288        let common_stale_b = Uuid::from_u128(2);
289        let text_only_stale = Uuid::from_u128(3);
290        let vector_only_stale = Uuid::from_u128(4);
291
292        let live_text = Entity::new("local", "concept", "live text candidate");
293        let live_vector = Entity::new("local", "concept", "live vector candidate");
294        rt.entities(&tok)
295            .unwrap()
296            .upsert_entities(vec![live_text.clone(), live_vector.clone()])
297            .await
298            .unwrap();
299
300        let document = |subject_id, repetitions: usize| TextDocument {
301            subject_id,
302            kind: SubstrateKind::Entity,
303            namespace: "local".to_string(),
304            title: None,
305            body: std::iter::repeat_n(query_text, repetitions)
306                .collect::<Vec<_>>()
307                .join(" "),
308            tags: vec![],
309            metadata: None,
310            updated_at: Utc::now(),
311        };
312        rt.text(&tok)
313            .unwrap()
314            .upsert_documents(vec![
315                document(common_stale_a, 12),
316                document(common_stale_b, 8),
317                document(text_only_stale, 4),
318                document(live_text.id, 1),
319            ])
320            .await
321            .unwrap();
322
323        let vectors = rt.vectors(&tok).unwrap();
324        for (id, vector) in [
325            (common_stale_a, cosine_fixture_vector(dimensions, 1.0, 0.0)),
326            (common_stale_b, cosine_fixture_vector(dimensions, 0.8, 0.6)),
327            (
328                vector_only_stale,
329                cosine_fixture_vector(dimensions, 0.5, 0.866_025_4),
330            ),
331            (live_vector.id, cosine_fixture_vector(dimensions, -1.0, 0.0)),
332        ] {
333            vectors
334                .insert(
335                    id,
336                    SubstrateKind::Entity,
337                    "local",
338                    "entity.body",
339                    vec![vector],
340                )
341                .await
342                .unwrap();
343        }
344
345        let text_hits = rt
346            .text(&tok)
347            .unwrap()
348            .search(TextSearchRequest {
349                query: query_text.to_string(),
350                mode: TextQueryMode::Plain,
351                filter: Some(TextFilter {
352                    namespaces: vec!["local".to_string()],
353                    ..TextFilter::default()
354                }),
355                top_k: CANDIDATE_MULTIPLIER,
356                snippet_chars: 0,
357            })
358            .await
359            .unwrap();
360        let vector_hits = vectors
361            .search(VectorSearchRequest {
362                query_vectors: vec![query_vector.clone()],
363                top_k: CANDIDATE_MULTIPLIER,
364                namespace: Some("local".to_string()),
365                kind: Some(SubstrateKind::Entity),
366                embedding_model: None,
367                filter: None,
368                backend_hints: None,
369            })
370            .await
371            .unwrap();
372
373        assert_eq!(text_hits.len(), CANDIDATE_MULTIPLIER as usize);
374        assert_eq!(vector_hits.len(), CANDIDATE_MULTIPLIER as usize);
375        let live = HashSet::from([live_text.id, live_vector.id]);
376        (
377            rt,
378            tok,
379            query_text,
380            query_vector,
381            text_hits,
382            vector_hits,
383            live,
384        )
385    }
386
387    // 1. RRF with custom k produces different ordering than k=60
388    #[test]
389    fn rrf_custom_k_differs_from_k60() {
390        let a = Uuid::new_v4();
391        let b = Uuid::new_v4();
392        // Single-source input makes a and b tie in relative order at both k values,
393        // so assert on raw score magnitude (smaller k widens the rank-1-vs-rank-2 gap)
394        // rather than ordering.
395        let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
396        let hits_k1 =
397            fuse_with_strategy(text.clone(), vec![], &FusionStrategy::Rrf { k: 1 }, 10).unwrap();
398        let hits_k60 =
399            fuse_with_strategy(text, vec![], &FusionStrategy::Rrf { k: 60 }, 10).unwrap();
400        // Both should have a first (rank 1 always wins in single-source)
401        assert_eq!(hits_k1[0].entity_id, a);
402        assert_eq!(hits_k60[0].entity_id, a);
403        // k=1 produces higher raw score for rank 1 than k=60
404        assert!(hits_k1[0].score > hits_k60[0].score);
405    }
406
407    // 2. Canonical [vector, keyword] weights change ordering as documented.
408    #[test]
409    fn weighted_ordering_depends_on_weights() {
410        let a = Uuid::new_v4();
411        let b = Uuid::new_v4();
412        // a scores high in text, b scores high in vector
413        let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
414        let vec_hits = vec![vector_hit(b, 0.9), vector_hit(a, 0.1)];
415
416        let heavy_vector = fuse_with_strategy(
417            text.clone(),
418            vec_hits.clone(),
419            &FusionStrategy::Weighted {
420                weights: vec![0.7, 0.3],
421            },
422            10,
423        )
424        .unwrap();
425        let heavy_keyword = fuse_with_strategy(
426            text,
427            vec_hits,
428            &FusionStrategy::Weighted {
429                weights: vec![0.3, 0.7],
430            },
431            10,
432        )
433        .unwrap();
434
435        assert_eq!(heavy_vector[0].entity_id, b);
436        assert_eq!(heavy_keyword[0].entity_id, a);
437    }
438
439    // 3. Weighted [7.0, 3.0] = Weighted [0.7, 0.3] (normalization)
440    #[test]
441    fn weighted_scale_invariant() {
442        let a = Uuid::new_v4();
443        let b = Uuid::new_v4();
444        let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
445        let vec_hits = vec![vector_hit(b, 0.9), vector_hit(a, 0.1)];
446
447        let w1 = fuse_with_strategy(
448            text.clone(),
449            vec_hits.clone(),
450            &FusionStrategy::Weighted {
451                weights: vec![0.7, 0.3],
452            },
453            10,
454        )
455        .unwrap();
456        let w2 = fuse_with_strategy(
457            text,
458            vec_hits,
459            &FusionStrategy::Weighted {
460                weights: vec![7.0, 3.0],
461            },
462            10,
463        )
464        .unwrap();
465
466        assert_eq!(w1[0].entity_id, w2[0].entity_id);
467        assert_eq!(w1[1].entity_id, w2[1].entity_id);
468        let diff = (w1[0].score.to_f64() - w2[0].score.to_f64()).abs();
469        assert!(diff < 1e-9, "scores differ by {diff}");
470    }
471
472    // 4. Weighted [0.0, 0.0] falls back to equal weights
473    #[test]
474    fn weighted_zero_weights_equal_fallback() {
475        let a = Uuid::new_v4();
476        let b = Uuid::new_v4();
477        // Both sources agree: a > b
478        let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
479        let vec_hits = vec![vector_hit(a, 0.9), vector_hit(b, 0.1)];
480
481        let hits = fuse_with_strategy(
482            text,
483            vec_hits,
484            &FusionStrategy::Weighted {
485                weights: vec![0.0, 0.0],
486            },
487            10,
488        )
489        .unwrap();
490        assert_eq!(hits[0].entity_id, a);
491    }
492
493    // 5. Weighted with negative weight clamps to 0
494    #[test]
495    fn weighted_negative_weight_clamped() {
496        let a = Uuid::new_v4();
497        let text = vec![text_hit(a, 0.9, "a")];
498        // Negative vector weight → only keyword/text contributes.
499        let hits = fuse_with_strategy(
500            text,
501            vec![],
502            &FusionStrategy::Weighted {
503                weights: vec![-0.5, 1.0],
504            },
505            10,
506        )
507        .unwrap();
508        assert_eq!(hits.len(), 1);
509        assert_eq!(hits[0].entity_id, a);
510    }
511
512    #[test]
513    fn weighted_empty_arm_keeps_canonical_position() {
514        let text_only = Uuid::new_v4();
515        let hits = fuse_with_strategy(
516            vec![text_hit(text_only, 0.9, "text")],
517            vec![],
518            &FusionStrategy::Weighted {
519                // Canonical [vector, keyword]: the only non-empty arm has zero weight.
520                weights: vec![1.0, 0.0],
521            },
522            10,
523        )
524        .unwrap();
525        assert!(
526            hits.is_empty(),
527            "dropping the empty vector arm would incorrectly rebind text to its weight"
528        );
529    }
530
531    // 6. Union returns max score per entity when same id appears in both lists
532    #[test]
533    fn union_max_score_per_entity() {
534        let a = Uuid::new_v4();
535        let text = vec![text_hit(a, 0.3, "a")];
536        let vec_hits = vec![vector_hit(a, 0.9)];
537
538        let hits = fuse_with_strategy(text, vec_hits, &FusionStrategy::Union, 10).unwrap();
539        assert_eq!(hits.len(), 1);
540        assert!((hits[0].score.to_f64() - 0.9).abs() < 1e-6);
541        assert_eq!(hits[0].source, SearchSource::Both);
542    }
543
544    // 7. VectorOnly returns vector hits only (text hits dropped)
545    #[test]
546    fn vector_only_drops_text() {
547        let a = Uuid::new_v4();
548        let b = Uuid::new_v4();
549        let text = vec![text_hit(b, 0.9, "b")];
550        let vec_hits = vec![vector_hit(a, 0.8)];
551
552        let hits = fuse_with_strategy(text, vec_hits, &FusionStrategy::VectorOnly, 10).unwrap();
553        assert_eq!(hits.len(), 1);
554        assert_eq!(hits[0].entity_id, a);
555        assert_eq!(hits[0].source, SearchSource::Vector);
556        assert!(hits[0].title.is_none());
557    }
558
559    #[test]
560    fn keyword_only_drops_vector() {
561        let text_id = Uuid::new_v4();
562        let vector_id = Uuid::new_v4();
563        let hits = fuse_with_strategy(
564            vec![text_hit(text_id, 0.8, "text")],
565            vec![vector_hit(vector_id, 0.9)],
566            &FusionStrategy::KeywordOnly,
567            10,
568        )
569        .unwrap();
570        assert_eq!(hits.len(), 1);
571        assert_eq!(hits[0].entity_id, text_id);
572        assert_eq!(hits[0].source, SearchSource::Text);
573    }
574
575    // 8. Default strategy is Rrf{k:60}
576    #[test]
577    fn default_strategy_is_rrf_k60() {
578        assert_eq!(FusionStrategy::default(), FusionStrategy::Rrf { k: 60 });
579    }
580
581    #[tokio::test]
582    async fn hybrid_union_alive_filter_refills_below_complete_four_x_prefix() {
583        let (rt, tok, query_text, query_vector, text_hits, vector_hits, live) =
584            stale_full_prefix_fixture().await;
585        let truncated = fuse_with_strategy(
586            text_hits,
587            vector_hits,
588            &FusionStrategy::Union,
589            CANDIDATE_MULTIPLIER as usize,
590        )
591        .unwrap();
592        assert!(truncated.iter().all(|hit| !live.contains(&hit.entity_id)));
593
594        let hits = rt
595            .hybrid_search_with_strategy(
596                &tok,
597                query_text,
598                Some(query_vector),
599                FusionStrategy::Union,
600                1,
601            )
602            .await
603            .unwrap();
604
605        assert_eq!(hits.len(), 1);
606        assert!(live.contains(&hits[0].entity_id));
607    }
608
609    #[tokio::test]
610    async fn hybrid_rrf_alive_filter_refills_below_complete_four_x_prefix() {
611        let (rt, tok, query_text, query_vector, text_hits, vector_hits, live) =
612            stale_full_prefix_fixture().await;
613        let strategy = FusionStrategy::Rrf { k: 60 };
614        let truncated = fuse_with_strategy(
615            text_hits,
616            vector_hits,
617            &strategy,
618            CANDIDATE_MULTIPLIER as usize,
619        )
620        .unwrap();
621        assert!(truncated.iter().all(|hit| !live.contains(&hit.entity_id)));
622
623        let hits = rt
624            .hybrid_search_with_strategy(&tok, query_text, Some(query_vector), strategy, 1)
625            .await
626            .unwrap();
627
628        assert_eq!(hits.len(), 1);
629        assert!(live.contains(&hits[0].entity_id));
630    }
631
632    #[tokio::test]
633    async fn hybrid_default_rrf_alive_filter_refills_below_complete_four_x_prefix() {
634        let (rt, tok, query_text, query_vector, _text_hits, _vector_hits, live) =
635            stale_full_prefix_fixture().await;
636
637        let hits = rt
638            .hybrid_search(
639                &tok,
640                query_text,
641                Some(query_vector),
642                1,
643                None,
644                None,
645                &[],
646                None,
647            )
648            .await
649            .unwrap();
650
651        assert_eq!(hits.len(), 1);
652        assert!(live.contains(&hits[0].entity_id));
653    }
654
655    // 9. Roundtrip serde preserves variant
656    #[test]
657    fn serde_roundtrip() {
658        let cases = vec![
659            FusionStrategy::Rrf { k: 60 },
660            FusionStrategy::Rrf { k: 20 },
661            FusionStrategy::Weighted {
662                weights: vec![0.7, 0.3],
663            },
664            FusionStrategy::Union,
665            FusionStrategy::VectorOnly,
666            FusionStrategy::KeywordOnly,
667        ];
668        for strategy in cases {
669            let json = serde_json::to_string(&strategy).expect("serialize");
670            let back: FusionStrategy = serde_json::from_str(&json).expect("deserialize");
671            assert_eq!(strategy, back, "roundtrip failed for {json}");
672        }
673    }
674
675    // 10. hybrid_search_with_strategy must not hard-fail on a query containing FTS5
676    // metacharacters like `$`, since sanitize_fts5_query strips them before the query
677    // reaches SQLite. This covers the sanitizer path; test 11 covers the fail-loud
678    // path for characters the sanitizer does not strip.
679    #[tokio::test]
680    async fn hybrid_search_with_strategy_dollar_sign_query_does_not_error() {
681        let rt = KhiveRuntime::memory().unwrap();
682        let tok = NamespaceToken::local();
683        rt.create_entity(
684            &tok,
685            "concept",
686            None,
687            "DSL docs",
688            Some("use $prev.id to chain calls"),
689            None,
690            vec![],
691        )
692        .await
693        .unwrap();
694
695        let result = rt
696            .hybrid_search_with_strategy(&tok, "$prev.id", None, FusionStrategy::default(), 10)
697            .await;
698
699        assert!(
700            result.is_ok(),
701            "#388 hybrid_search_with_strategy must not hard-fail on a '$'-bearing query, got: {:?}",
702            result.err()
703        );
704    }
705
706    // 11. #916: `@` used to reach SQLite FTS5's bareword parser raw and error,
707    // surfacing as RuntimeError::InvalidInput per #569's fail-loud policy.
708    // sanitize_fts5_token_group's bareword-safety gate now routes it through the
709    // quoted-phrase alternative instead, so the query succeeds and the fail-loud
710    // arm is no longer reached for ordinary punctuation.
711    #[tokio::test]
712    async fn hybrid_search_with_strategy_residual_fts5_char_now_sanitized() {
713        let rt = KhiveRuntime::memory().unwrap();
714        let tok = NamespaceToken::local();
715        rt.create_entity(
716            &tok,
717            "concept",
718            None,
719            "DSL docs",
720            Some("use foo@bar to chain calls"),
721            None,
722            vec![],
723        )
724        .await
725        .unwrap();
726
727        let result = rt
728            .hybrid_search_with_strategy(&tok, "foo@bar", None, FusionStrategy::default(), 10)
729            .await;
730
731        let hits = result.unwrap_or_else(|e| {
732            panic!(
733                "#916 hybrid_search_with_strategy must not fail on an '@'-bearing query, got: {e:?}"
734            )
735        });
736        assert!(
737            !hits.is_empty(),
738            "#916 '@'-bearing query must still find the seeded 'foo@bar' content via the \
739             quoted-phrase alternative"
740        );
741    }
742}