Skip to main content

khive_runtime/operations/
note_search.rs

1//! Note hybrid search stages and candidate hydration.
2
3use super::*;
4
5impl KhiveRuntime {
6    /// Search with an explicit top-level note status and strict vector errors.
7    ///
8    /// The count records distinct candidates whose status mismatches the selector after
9    /// namespace, mailbox, kind, tag and property checks. It precedes superseded
10    /// filtering and ranking, so it is not a count of missing eligible matches.
11    /// The existing bounded four-times-per-arm window is unchanged. A supplied
12    /// mailbox view adds a gate; it does not replace the default actor gate.
13    #[allow(clippy::too_many_arguments)]
14    pub async fn search_notes_with_text_mode_and_status(
15        &self,
16        token: &NamespaceToken,
17        query_text: &str,
18        query_vector: Option<Vec<f32>>,
19        limit: u32,
20        note_kind: Option<&str>,
21        include_superseded: bool,
22        tags_any: &[String],
23        properties_filter: Option<&serde_json::Value>,
24        text_mode: TextQueryMode,
25        note_status: khive_storage::note::NoteStatusSelector,
26        additional_mailbox_view: Option<&crate::MailboxView>,
27    ) -> RuntimeResult<(Vec<NoteSearchHit>, u64)> {
28        let (hits, _vector_error, note_status_dropped) = self
29            .search_notes_inner(
30                token,
31                query_text,
32                query_vector,
33                limit,
34                note_kind,
35                include_superseded,
36                tags_any,
37                properties_filter,
38                text_mode,
39                false,
40                note_status,
41                additional_mailbox_view,
42            )
43            .await?;
44        Ok((hits, note_status_dropped))
45    }
46
47    /// Note-search outcome with explicit status and bounded status-drop evidence.
48    ///
49    /// A successful text leg survives a vector error, which remains in the
50    /// existing outcome. Count semantics match the strict selector entrypoint.
51    #[allow(clippy::too_many_arguments)]
52    pub async fn search_notes_outcome_with_text_mode_and_status(
53        &self,
54        token: &NamespaceToken,
55        query_text: &str,
56        limit: u32,
57        note_kind: Option<&str>,
58        include_superseded: bool,
59        tags_any: &[String],
60        properties_filter: Option<&serde_json::Value>,
61        text_mode: TextQueryMode,
62        note_status: khive_storage::note::NoteStatusSelector,
63        additional_mailbox_view: Option<&crate::MailboxView>,
64    ) -> RuntimeResult<(NoteSearchOutcome, u64)> {
65        let (hits, vector_error, note_status_dropped) = self
66            .search_notes_inner(
67                token,
68                query_text,
69                None,
70                limit,
71                note_kind,
72                include_superseded,
73                tags_any,
74                properties_filter,
75                text_mode,
76                true,
77                note_status,
78                additional_mailbox_view,
79            )
80            .await?;
81        Ok((
82            NoteSearchOutcome { hits, vector_error },
83            note_status_dropped,
84        ))
85    }
86
87    #[allow(clippy::too_many_arguments)]
88    pub(super) async fn search_notes_inner(
89        &self,
90        token: &NamespaceToken,
91        query_text: &str,
92        query_vector: Option<Vec<f32>>,
93        limit: u32,
94        note_kind: Option<&str>,
95        include_superseded: bool,
96        tags_any: &[String],
97        properties_filter: Option<&serde_json::Value>,
98        text_mode: TextQueryMode,
99        tolerate_vector_error: bool,
100        note_status: khive_storage::note::NoteStatusSelector,
101        additional_mailbox_view: Option<&crate::MailboxView>,
102    ) -> RuntimeResult<(Vec<NoteSearchHit>, Option<String>, u64)> {
103        const RRF_K: usize = 60;
104        let candidates = limit.saturating_mul(4).max(limit);
105        let visible_ns: Vec<String> = token
106            .visible_namespaces()
107            .iter()
108            .map(|ns| ns.as_str().to_owned())
109            .collect();
110
111        // FTS5 over the notes index — search all visible namespaces.
112        //
113        // `sanitize_fts5_query` strips known-unsafe FTS5 metacharacters, but
114        // residual punctuation the sanitizer does not strip can still reach
115        // the FTS5 parser and error. This fails loud instead of degrading to
116        // vector-only fusion, so callers see the bad query instead of
117        // silently losing the lexical leg. Errors from any other leg (vector
118        // search, note hydration) still propagate normally.
119        //
120        // Injection: check FTS_SEARCH_FAIL_NS (armed by `arm_fts_search_fail(ns)`),
121        // exercising the propagate branch above. Fires only when the armed
122        // namespace is among this call's visible namespaces, then clears (one-shot).
123        #[cfg(any(test, feature = "fault-injection"))]
124        let fts_search_inject = {
125            let mut g = FTS_SEARCH_FAIL_NS.lock().unwrap();
126            match g.as_deref() {
127                Some(armed) if visible_ns.iter().any(|ns| ns == armed) => {
128                    *g = None;
129                    true
130                }
131                _ => false,
132            }
133        };
134        #[cfg(not(any(test, feature = "fault-injection")))]
135        let fts_search_inject = false;
136
137        let text_store = self.text_for_notes(token)?;
138        let text_fut = async {
139            let _phase = khive_storage::request_context::enter_search_phase(
140                khive_storage::request_context::SearchPhase::TextSearch,
141            );
142            if fts_search_inject {
143                return Err(khive_storage::StorageError::Timeout {
144                    operation: "fts_search".into(),
145                });
146            }
147            text_store
148                .search(TextSearchRequest {
149                    query: query_text.to_string(),
150                    mode: text_mode,
151                    filter: Some(TextFilter {
152                        namespaces: visible_ns.clone(),
153                        // Push the note-kind filter into the FTS query. Without it the
154                        // text arm returns the top `candidates` rows across EVERY note
155                        // kind in the namespace and the kind is applied post-fetch, so a
156                        // store where short message/session rows outrank task
157                        // descriptions under BM25 hands the caller one or two task hits
158                        // while the store holds many more carrying the literal.
159                        record_kinds: note_kind
160                            .map(|kind| vec![kind.to_string()])
161                            .unwrap_or_default(),
162                        ..TextFilter::default()
163                    }),
164                    top_k: candidates,
165                    snippet_chars: 200,
166                })
167                .await
168        };
169        let text_fut = crate::stage_seam::text_stage(text_fut);
170
171        // Vector search filtered to notes; it runs with the text stage, and a text error wins.
172        let vector_fut = async {
173            let _phase = khive_storage::request_context::enter_search_phase(
174                khive_storage::request_context::SearchPhase::VectorSearch,
175            );
176            if query_vector.is_some() || !self.default_embedder_name().is_empty() {
177                crate::search_audit::record(crate::search_audit::SearchArm::Vector);
178                self.note_search_vector_search(token, query_vector, query_text, candidates)
179                    .await
180            } else {
181                Ok(vec![])
182            }
183        };
184        let (text_search_result, vector_result) = tokio::join!(text_fut, vector_fut);
185
186        // FtsPasses is counted inside the store's `search()` (khive-db
187        // stores/text.rs), only once a real FTS5 statement is prepared —
188        // an empty/fully-sanitized query short-circuits there before any
189        // statement exists and must not count (nor does the injected-failure
190        // branch above, which never reaches the store at all).
191        let text_hits = crate::error::fts_text_leg_or_err(
192            text_search_result.map_err(RuntimeError::from),
193            "search_notes",
194            query_text,
195        )?;
196
197        let mut vector_error: Option<String> = None;
198        let vector_hits = match vector_result {
199            Ok(hits) => hits,
200            Err(e) if tolerate_vector_error => {
201                vector_error = Some(e.to_string());
202                Vec::new()
203            }
204            Err(e) => return Err(e),
205        };
206
207        // Keep the full text∪vector union through RRF — salience weighting and
208        // soft-delete/kind filtering happen *after* this, and the final
209        // `hits.truncate(limit)` is the only result-limiting cut. Truncating to
210        // `candidates` here would drop a high-salience note ranked just outside
211        // the raw RRF cutoff before salience ever applied.
212        let fuse_k = text_hits.len() + vector_hits.len();
213        let fused = {
214            let _phase = khive_storage::request_context::enter_search_phase(
215                khive_storage::request_context::SearchPhase::Fusion,
216            );
217            self.fuse_with_strategy(
218                text_hits,
219                vector_hits,
220                &crate::fusion::FusionStrategy::Rrf { k: RRF_K },
221                fuse_k,
222            )
223            .await?
224        };
225
226        let candidate_ids: Vec<Uuid> = fused.iter().map(|hit| hit.entity_id).collect();
227        if candidate_ids.is_empty() {
228            return Ok((vec![], vector_error, 0));
229        }
230
231        // Hydrate every candidate note with one batched read to get salience and
232        // apply soft-delete + (optional) kind filtering. The store chunks the read
233        // below its bound-parameter ceiling, so the read costs `ceil(candidates / 900)`
234        // statements instead of one per candidate. Notes whose `kind` doesn't
235        // match `note_kind` are dropped post-fetch — they're a small set
236        // bounded by the text∪vector union (≤ 2×candidates), so the read is cheap.
237        let note_store = self.notes(token)?;
238        let search_pool = self.backend().pool_arc();
239        let mailbox_view = crate::MailboxView {
240            actor_id: token.actor().id.clone(),
241            delegated: false,
242        };
243        let mut alive_notes: HashMap<Uuid, Note> = HashMap::new();
244        // Fused candidate IDs and the batched identity read each contain one row per note.
245        let mut note_status_dropped = 0_u64;
246        let fetched_notes = {
247            let _phase = khive_storage::request_context::enter_search_phase(
248                khive_storage::request_context::SearchPhase::NoteHydration,
249            );
250            note_store.get_notes_batch(&candidate_ids).await?
251        };
252        let _authorization_phase = khive_storage::request_context::enter_search_phase(
253            khive_storage::request_context::SearchPhase::MailboxAuthorization,
254        );
255        for note in fetched_notes {
256            search_pool.record_note_candidate_hydration_row();
257            // Identity batch reads are neutral. Revalidate the full row even
258            // when an index candidate claimed a visible namespace.
259            if !visible_ns
260                .iter()
261                .any(|namespace| namespace == &note.namespace)
262            {
263                continue;
264            }
265            if note.deleted_at.is_some() {
266                continue;
267            }
268            if !mailbox_view.permits_message_note(token, &note) {
269                continue;
270            }
271            if additional_mailbox_view.is_some_and(|view| !view.permits_message_note(token, &note))
272            {
273                continue;
274            }
275            if let Some(want_kind) = note_kind {
276                if note.kind != want_kind {
277                    continue;
278                }
279            }
280            // Apply tag predicate before adding to alive set: tags on notes live
281            // inside `properties["tags"]` (a JSON array). This pushes the filter
282            // before truncation so matching notes ranked beyond `limit` in the raw
283            // fusion are not silently dropped.
284            if !tags_any.is_empty() {
285                let note_tags: Vec<String> = note
286                    .properties
287                    .as_ref()
288                    .and_then(|p| p.get("tags"))
289                    .and_then(serde_json::Value::as_array)
290                    .map(|arr| {
291                        arr.iter()
292                            .filter_map(serde_json::Value::as_str)
293                            .map(str::to_owned)
294                            .collect()
295                    })
296                    .unwrap_or_default();
297                if !note_tags
298                    .iter()
299                    .any(|t| tags_any.iter().any(|w| t.eq_ignore_ascii_case(w)))
300                {
301                    continue;
302                }
303            }
304            // Apply properties predicate before truncation, same reasoning as tags above.
305            if let Some(pf) = properties_filter {
306                if !crate::retrieval::properties_match(note.properties.as_ref(), pf) {
307                    continue;
308                }
309            }
310            if !note_status.matches(&note.status) {
311                note_status_dropped = note_status_dropped.checked_add(1).ok_or_else(|| {
312                    RuntimeError::Internal("note status drop count exceeds u64".into())
313                })?;
314                continue;
315            }
316            alive_notes.insert(note.id, note);
317        }
318        drop(_authorization_phase);
319
320        // Drop superseded notes unless include_superseded is true: any note targeted
321        // by a `supersedes` edge is obsolete and excluded from default search.
322        if !include_superseded && !alive_notes.is_empty() {
323            let graph = self.graph(token)?;
324            let note_ids: Vec<Uuid> = alive_notes.keys().copied().collect();
325            let superseded: std::collections::HashSet<Uuid> = {
326                let _phase = khive_storage::request_context::enter_search_phase(
327                    khive_storage::request_context::SearchPhase::SupersededFilter,
328                );
329                graph
330                    .batch_neighbors(
331                        &note_ids,
332                        NeighborQuery {
333                            direction: Direction::In,
334                            relations: Some(vec![EdgeRelation::Supersedes]),
335                            limit: Some(1),
336                            min_weight: None,
337                        },
338                    )
339                    .await?
340                    .into_iter()
341                    .map(|(note_id, _)| note_id)
342                    .collect()
343            };
344            alive_notes.retain(|id, _| !superseded.contains(id));
345        }
346
347        // Apply salience weighting and collect final hits.
348        let mut hits: Vec<NoteSearchHit> = fused
349            .into_iter()
350            .filter_map(|hit| {
351                let note = alive_notes.get(&hit.entity_id)?;
352                let weighted = salience_weighted_rank(hit.score, note.salience);
353                Some(NoteSearchHit {
354                    note_id: hit.entity_id,
355                    score: weighted,
356                    rank_score_kind: hit.rank_score_kind,
357                    signals: hit.signals,
358                    source: hit.source,
359                    title: hit.title.or_else(|| note_title(note)),
360                    snippet: hit.snippet.or_else(|| note_snippet(note)),
361                })
362            })
363            .collect();
364
365        hits.sort_by(|a, b| b.score.cmp(&a.score).then(a.note_id.cmp(&b.note_id)));
366        hits.truncate(limit as usize);
367        Ok((hits, vector_error, note_status_dropped))
368    }
369}
370
371#[cfg(test)]
372mod status_tests {
373    use super::*;
374    use crate::embedder_registry::EmbedderProvider;
375    use async_trait::async_trait;
376    use khive_storage::note::{NoteStatusSelector, NoteStore};
377    use khive_storage::types::TextDocument;
378    use lattice_embed::{EmbedError, EmbeddingModel, EmbeddingService};
379    use std::collections::HashSet;
380    use std::future::Future;
381    use std::sync::Arc;
382    use std::time::Duration;
383
384    const QUERY: &str = "archivestatusfixture";
385
386    // Every async setup/search/assertion in these tests is inside this budget.
387    // Tokio timeouts bound cooperative async waits, not synchronous native code.
388    async fn bounded(future: impl Future<Output = ()>) {
389        tokio::time::timeout(Duration::from_secs(20), future)
390            .await
391            .expect("status fixture exceeded its async budget");
392    }
393
394    fn note(namespace: &str, kind: &str, status: &str) -> Note {
395        let mut note = Note::new(namespace, kind, QUERY);
396        note.status = status.into();
397        note
398    }
399
400    async fn seed(
401        runtime: &KhiveRuntime,
402        token: &NamespaceToken,
403        note: Note,
404        indexed_namespace: &str,
405        indexed_kind: &str,
406    ) -> Uuid {
407        let id = note.id;
408        // Isolated fixture only: actual backend NoteStore bypasses the live
409        // message-forgery guard so private/stale records can be represented.
410        runtime.backend().upsert_note(note).await.unwrap();
411        runtime
412            .text_for_notes(token)
413            .unwrap()
414            .upsert_document(TextDocument {
415                subject_id: id,
416                kind: khive_types::SubstrateKind::Note,
417                record_kind: Some(indexed_kind.into()),
418                namespace: indexed_namespace.into(),
419                title: None,
420                body: QUERY.into(),
421                tags: vec![],
422                metadata: None,
423                updated_at: chrono::Utc::now(),
424            })
425            .await
426            .unwrap();
427        id
428    }
429
430    async fn raw_candidates(
431        runtime: &KhiveRuntime,
432        token: &NamespaceToken,
433        top_k: u32,
434    ) -> HashSet<Uuid> {
435        runtime
436            .text_for_notes(token)
437            .unwrap()
438            .search(TextSearchRequest {
439                query: QUERY.into(),
440                mode: TextQueryMode::Plain,
441                filter: Some(TextFilter {
442                    namespaces: vec![token.namespace().as_str().into()],
443                    ..Default::default()
444                }),
445                top_k,
446                snippet_chars: 100,
447            })
448            .await
449            .unwrap()
450            .into_iter()
451            .map(|hit| hit.subject_id)
452            .collect()
453    }
454
455    async fn select(
456        runtime: &KhiveRuntime,
457        token: &NamespaceToken,
458        status: NoteStatusSelector,
459        limit: u32,
460    ) -> (Vec<NoteSearchHit>, u64) {
461        runtime
462            .search_notes_with_text_mode_and_status(
463                token,
464                QUERY,
465                None,
466                limit,
467                None,
468                true,
469                &[],
470                None,
471                TextQueryMode::Plain,
472                status,
473                None,
474            )
475            .await
476            .unwrap()
477    }
478
479    fn ids(hits: &[NoteSearchHit]) -> HashSet<Uuid> {
480        hits.iter().map(|hit| hit.note_id).collect()
481    }
482
483    #[tokio::test]
484    async fn legacy_wrappers_default_active_and_explicit_selectors_differ() {
485        bounded(async {
486            let runtime = KhiveRuntime::memory().unwrap();
487            let token = NamespaceToken::local();
488            let ns = token.namespace().as_str();
489            let mut active = note(ns, "observation", "active");
490            active.properties = Some(serde_json::json!({"status": "archived"}));
491            let active_id = seed(&runtime, &token, active, ns, "observation").await;
492            let active_second = seed(
493                &runtime,
494                &token,
495                note(ns, "observation", "active"),
496                ns,
497                "observation",
498            )
499            .await;
500            let mut archived = note(ns, "observation", "archived");
501            archived.properties = Some(serde_json::json!({"status": "active"}));
502            let archived_id = seed(&runtime, &token, archived, ns, "observation").await;
503            let archived_second = seed(
504                &runtime,
505                &token,
506                note(ns, "observation", "archived"),
507                ns,
508                "observation",
509            )
510            .await;
511            let custom_id = seed(
512                &runtime,
513                &token,
514                note(ns, "observation", "custom"),
515                ns,
516                "observation",
517            )
518            .await;
519            let active_ids = HashSet::from([active_id, active_second]);
520            let archived_ids = HashSet::from([archived_id, archived_second]);
521            let all_ids = HashSet::from([
522                active_id,
523                active_second,
524                archived_id,
525                archived_second,
526                custom_id,
527            ]);
528            assert_eq!(raw_candidates(&runtime, &token, 40).await, all_ids);
529            let plain = runtime
530                .search_notes(&token, QUERY, None, 10, None, true, &[], None)
531                .await
532                .unwrap();
533            assert_eq!(ids(&plain), active_ids);
534            let mode = runtime
535                .search_notes_with_text_mode(
536                    &token,
537                    QUERY,
538                    None,
539                    10,
540                    None,
541                    true,
542                    &[],
543                    None,
544                    TextQueryMode::Plain,
545                )
546                .await
547                .unwrap();
548            assert_eq!(ids(&mode), active_ids);
549            let outcome = runtime
550                .search_notes_outcome(&token, QUERY, 10, None, true, &[], None)
551                .await
552                .unwrap();
553            assert_eq!(ids(&outcome.hits), active_ids);
554            assert!(outcome.vector_error.is_none());
555            let mode_outcome = runtime
556                .search_notes_outcome_with_text_mode(
557                    &token,
558                    QUERY,
559                    10,
560                    None,
561                    true,
562                    &[],
563                    None,
564                    TextQueryMode::Plain,
565                )
566                .await
567                .unwrap();
568            assert_eq!(ids(&mode_outcome.hits), active_ids);
569            assert!(mode_outcome.vector_error.is_none());
570            for (selector, expected_ids, expected_count) in [
571                (NoteStatusSelector::Active, active_ids, 3),
572                (NoteStatusSelector::Archived, archived_ids, 3),
573                (NoteStatusSelector::Any, all_ids, 0),
574            ] {
575                let (hits, count) = select(&runtime, &token, selector, 10).await;
576                assert_eq!(ids(&hits), expected_ids);
577                assert_eq!(
578                    count, expected_count,
579                    "all lifecycle mismatches count, including custom"
580                );
581                let (outcome, count) = runtime
582                    .search_notes_outcome_with_text_mode_and_status(
583                        &token,
584                        QUERY,
585                        10,
586                        None,
587                        true,
588                        &[],
589                        None,
590                        TextQueryMode::Plain,
591                        selector,
592                        None,
593                    )
594                    .await
595                    .unwrap();
596                assert_eq!(ids(&outcome.hits), expected_ids);
597                assert_eq!(count, expected_count);
598                assert!(outcome.vector_error.is_none());
599            }
600            let raw = runtime
601                .notes(&token)
602                .unwrap()
603                .get_notes_batch(&[archived_id, custom_id])
604                .await
605                .unwrap();
606            assert_eq!(raw.len(), 2, "identity hydration remains status neutral");
607        })
608        .await;
609    }
610
611    #[tokio::test]
612    async fn invisible_hydrated_candidate_never_becomes_hit_or_status_count() {
613        bounded(async {
614            let runtime = KhiveRuntime::memory().unwrap();
615            let token = NamespaceToken::local();
616            let ns = token.namespace().as_str();
617            let foreign_id = seed(
618                &runtime,
619                &token,
620                note("foreign-status-fixture", "observation", "archived"),
621                ns,
622                "observation",
623            )
624            .await;
625            // Prove the seeded mismatch reaches the genuine candidate and raw
626            // hydration seams; a retrieval-only refusal cannot pass this test.
627            assert!(raw_candidates(&runtime, &token, 40)
628                .await
629                .contains(&foreign_id));
630            let raw = runtime
631                .notes(&token)
632                .unwrap()
633                .get_notes_batch(&[foreign_id])
634                .await
635                .unwrap();
636            assert_eq!(raw.len(), 1);
637            assert_eq!(raw[0].namespace, "foreign-status-fixture");
638            assert!(!token
639                .visible_namespaces()
640                .iter()
641                .any(|ns| ns.as_str() == raw[0].namespace.as_str()));
642            for status in [
643                NoteStatusSelector::Active,
644                NoteStatusSelector::Archived,
645                NoteStatusSelector::Any,
646            ] {
647                let (hits, dropped) = select(&runtime, &token, status, 10).await;
648                assert!(
649                    hits.is_empty(),
650                    "invisible hydrated candidate must not be a hit"
651                );
652                assert_eq!(
653                    dropped, 0,
654                    "invisible archived candidate must not be counted"
655                );
656            }
657            let visible_id = seed(
658                &runtime,
659                &token,
660                note(ns, "observation", "archived"),
661                ns,
662                "observation",
663            )
664            .await;
665            let (hits, dropped) = select(&runtime, &token, NoteStatusSelector::Active, 10).await;
666            assert!(hits.is_empty());
667            assert_eq!(
668                dropped, 1,
669                "positive control: only visible archive contributes"
670            );
671            let (hits, dropped) = select(&runtime, &token, NoteStatusSelector::Any, 10).await;
672            assert_eq!(ids(&hits), HashSet::from([visible_id]));
673            assert_eq!(dropped, 0);
674        })
675        .await;
676    }
677
678    #[tokio::test]
679    async fn hydration_predicates_run_before_status_accounting() {
680        bounded(async {
681            let runtime = KhiveRuntime::memory().unwrap();
682            let token = NamespaceToken::local();
683            let ns = token.namespace().as_str();
684            let matched = serde_json::json!({"tags": ["wanted"], "project": "keep"});
685            let mut kept_archive = note(ns, "observation", "archived");
686            kept_archive.properties = Some(matched.clone());
687            let archived_id = seed(&runtime, &token, kept_archive, ns, "observation").await;
688            let mut kept_active = note(ns, "observation", "active");
689            kept_active.properties = Some(matched.clone());
690            let active_id = seed(&runtime, &token, kept_active, ns, "observation").await;
691            let mut wrong_kind = note(ns, "question", "archived");
692            wrong_kind.properties = Some(matched.clone());
693            // Stale indexed kind ensures the full-note kind check is exercised.
694            let wrong_kind_id = seed(&runtime, &token, wrong_kind, ns, "observation").await;
695            let mut wrong_tag = note(ns, "observation", "archived");
696            wrong_tag.properties = Some(serde_json::json!({"tags": ["other"], "project": "keep"}));
697            let wrong_tag_id = seed(&runtime, &token, wrong_tag, ns, "observation").await;
698            let mut wrong_property = note(ns, "observation", "archived");
699            wrong_property.properties =
700                Some(serde_json::json!({"tags": ["wanted"], "project": "other"}));
701            let wrong_property_id = seed(&runtime, &token, wrong_property, ns, "observation").await;
702            let mut deleted = note(ns, "observation", "archived");
703            deleted.properties = Some(matched);
704            deleted.deleted_at = Some(deleted.updated_at);
705            let deleted_id = seed(&runtime, &token, deleted, ns, "observation").await;
706            assert_eq!(
707                raw_candidates(&runtime, &token, 40).await,
708                HashSet::from([
709                    archived_id,
710                    active_id,
711                    wrong_kind_id,
712                    wrong_tag_id,
713                    wrong_property_id,
714                    deleted_id
715                ])
716            );
717            let tags = vec!["wanted".into()];
718            let properties = serde_json::json!({"project": "keep"});
719            let (hits, dropped) = runtime
720                .search_notes_with_text_mode_and_status(
721                    &token,
722                    QUERY,
723                    None,
724                    10,
725                    Some("observation"),
726                    true,
727                    &tags,
728                    Some(&properties),
729                    TextQueryMode::Plain,
730                    NoteStatusSelector::Active,
731                    None,
732                )
733                .await
734                .unwrap();
735            assert_eq!(ids(&hits), HashSet::from([active_id]));
736            assert_eq!(
737                dropped, 1,
738                "only the otherwise matching live archive counts"
739            );
740        })
741        .await;
742    }
743
744    #[tokio::test]
745    async fn default_mailbox_rejection_precedes_status_count() {
746        bounded(async {
747            let runtime = KhiveRuntime::memory().unwrap();
748            let token = NamespaceToken::local();
749            let ns = token.namespace().as_str();
750            let mut private = note(ns, "message", "archived");
751            private.properties = Some(serde_json::json!({
752                "direction": "inbound", "from_actor": "status-fixture-sender",
753                "to_actor": "status-fixture-other"
754            }));
755            let private_id = seed(&runtime, &token, private, ns, "message").await;
756            assert_eq!(
757                raw_candidates(&runtime, &token, 40).await,
758                HashSet::from([private_id])
759            );
760            for selector in [
761                NoteStatusSelector::Active,
762                NoteStatusSelector::Archived,
763                NoteStatusSelector::Any,
764            ] {
765                // The real search constructs its own caller view; no test MailboxView literal.
766                let (hits, dropped) = select(&runtime, &token, selector, 10).await;
767                assert!(hits.is_empty());
768                assert_eq!(
769                    dropped, 0,
770                    "another actor's inbound message contributes no count"
771                );
772            }
773            let archive_id = seed(
774                &runtime,
775                &token,
776                note(ns, "observation", "archived"),
777                ns,
778                "observation",
779            )
780            .await;
781            let (hits, count) = select(&runtime, &token, NoteStatusSelector::Active, 10).await;
782            assert!(hits.is_empty());
783            assert_eq!(
784                count, 1,
785                "positive control: visible non-message archive is counted"
786            );
787            let (hits, count) = select(&runtime, &token, NoteStatusSelector::Any, 10).await;
788            assert_eq!(ids(&hits), HashSet::from([archive_id]));
789            assert_eq!(count, 0);
790        })
791        .await;
792    }
793
794    #[tokio::test]
795    async fn actual_authorized_additional_view_intersects_default_mailbox() {
796        bounded(async {
797            // Use the same real policy/authorization constructors as mailbox_view/tests.rs.
798            let gate = crate::MailboxReadGate::new(
799                Arc::new(crate::AllowAllGate),
800                crate::ActorRef::new("actor", "lambda:owner"),
801                vec![crate::ActorRef::new("actor", "lambda:reader")],
802            )
803            .unwrap();
804            let runtime = KhiveRuntime::new(crate::RuntimeConfig {
805                db_path: None,
806                gate: Arc::new(gate),
807                actor_id: Some("lambda:owner".into()),
808                ..crate::RuntimeConfig::no_embeddings()
809            })
810            .unwrap();
811            let token = NamespaceToken::mint_authorized(
812                crate::Namespace::local(),
813                crate::ActorRef::new("actor", "lambda:reader"),
814            );
815            let ns = token.namespace().as_str();
816            let own_view = runtime
817                .authorize_mailbox_view(
818                    &token,
819                    "search",
820                    None,
821                    &serde_json::json!({"query": QUERY, "kind": "note"}),
822                )
823                .unwrap();
824            // This is a genuine separately authorized mailbox view, used only to
825            // exercise the API's intersection invariant. Generic search itself
826            // does not grant cross-actor mailbox selection.
827            let owner_view = runtime
828                .authorize_mailbox_view(
829                    &token,
830                    "comm.inbox",
831                    Some("lambda:owner"),
832                    &serde_json::json!({"mailbox_actor": "lambda:owner"}),
833                )
834                .unwrap();
835            let mut own = note(ns, "message", "archived");
836            own.properties =
837                Some(serde_json::json!({"direction": "inbound", "to_actor": "lambda:reader"}));
838            let mut other = note(ns, "message", "archived");
839            other.properties =
840                Some(serde_json::json!({"direction": "inbound", "to_actor": "lambda:owner"}));
841            assert!(own_view.permits_message_note(&token, &own));
842            assert!(!own_view.permits_message_note(&token, &other));
843            assert!(!owner_view.permits_message_note(&token, &own));
844            assert!(owner_view.permits_message_note(&token, &other));
845            let own_id = seed(&runtime, &token, own, ns, "message").await;
846            let other_id = seed(&runtime, &token, other, ns, "message").await;
847            assert_eq!(
848                raw_candidates(&runtime, &token, 40).await,
849                HashSet::from([own_id, other_id])
850            );
851            let (hits, count) = runtime
852                .search_notes_with_text_mode_and_status(
853                    &token,
854                    QUERY,
855                    None,
856                    10,
857                    None,
858                    true,
859                    &[],
860                    None,
861                    TextQueryMode::Plain,
862                    NoteStatusSelector::Active,
863                    Some(&own_view),
864                )
865                .await
866                .unwrap();
867            assert!(hits.is_empty());
868            assert_eq!(
869                count, 1,
870                "own authorized view preserves one otherwise-eligible archive"
871            );
872            for selector in [
873                NoteStatusSelector::Active,
874                NoteStatusSelector::Archived,
875                NoteStatusSelector::Any,
876            ] {
877                let (hits, count) = runtime
878                    .search_notes_with_text_mode_and_status(
879                        &token,
880                        QUERY,
881                        None,
882                        10,
883                        None,
884                        true,
885                        &[],
886                        None,
887                        TextQueryMode::Plain,
888                        selector,
889                        Some(&owner_view),
890                    )
891                    .await
892                    .unwrap();
893                assert!(hits.is_empty(), "both independent mailbox gates apply");
894                assert_eq!(
895                    count, 0,
896                    "neither mailbox intersection row may be disclosed by count"
897                );
898                let (outcome, count) = runtime
899                    .search_notes_outcome_with_text_mode_and_status(
900                        &token,
901                        QUERY,
902                        10,
903                        None,
904                        true,
905                        &[],
906                        None,
907                        TextQueryMode::Plain,
908                        selector,
909                        Some(&owner_view),
910                    )
911                    .await
912                    .unwrap();
913                assert!(outcome.hits.is_empty());
914                assert!(outcome.vector_error.is_none());
915                assert_eq!(count, 0, "tolerant API preserves the additional view too");
916            }
917        })
918        .await;
919    }
920
921    #[tokio::test]
922    async fn runtime_count_survives_both_underfilled_and_full_pages() {
923        bounded(async {
924            let runtime = KhiveRuntime::memory().unwrap();
925            let token = NamespaceToken::local();
926            let ns = token.namespace().as_str();
927            let active = seed(
928                &runtime,
929                &token,
930                note(ns, "observation", "active"),
931                ns,
932                "observation",
933            )
934            .await;
935            seed(
936                &runtime,
937                &token,
938                note(ns, "observation", "archived"),
939                ns,
940                "observation",
941            )
942            .await;
943            for limit in [1, 4] {
944                let (hits, dropped) =
945                    select(&runtime, &token, NoteStatusSelector::Active, limit).await;
946                assert_eq!(ids(&hits), HashSet::from([active]));
947                assert_eq!(
948                    dropped, 1,
949                    "count is independent of full versus underfilled presentation"
950                );
951                assert_eq!(hits.len() < limit as usize, limit == 4);
952            }
953        })
954        .await;
955    }
956
957    #[tokio::test]
958    async fn archive_heavy_search_keeps_existing_four_times_window() {
959        bounded(async {
960            let runtime = KhiveRuntime::memory().unwrap();
961            let token = NamespaceToken::local();
962            let ns = token.namespace().as_str();
963            let mut all = HashSet::new();
964            for _ in 0..5 {
965                all.insert(
966                    seed(
967                        &runtime,
968                        &token,
969                        note(ns, "observation", "active"),
970                        ns,
971                        "observation",
972                    )
973                    .await,
974                );
975            }
976            // Choose the archive set from actual backend ordering rather than
977            // assuming UUID/rowid tie-breaking. Status updates do not reindex.
978            let gathered = raw_candidates(&runtime, &token, 4).await;
979            assert_eq!(gathered.len(), 4);
980            let outside: HashSet<_> = all.difference(&gathered).copied().collect();
981            assert_eq!(outside.len(), 1);
982            for id in &gathered {
983                let mut row = runtime
984                    .notes(&token)
985                    .unwrap()
986                    .get_note(*id)
987                    .await
988                    .unwrap()
989                    .unwrap();
990                row.status = "archived".into();
991                runtime.backend().upsert_note(row).await.unwrap();
992            }
993            assert_eq!(raw_candidates(&runtime, &token, 4).await, gathered);
994            let (hits, dropped) = select(&runtime, &token, NoteStatusSelector::Active, 1).await;
995            assert!(
996                hits.is_empty(),
997                "bounded search must not silently refill outside its four candidates"
998            );
999            assert_eq!(dropped, 4);
1000            let outside_id = *outside.iter().next().unwrap();
1001            let outside_note = runtime
1002                .notes(&token)
1003                .unwrap()
1004                .get_note(outside_id)
1005                .await
1006                .unwrap()
1007                .unwrap();
1008            assert_eq!(
1009                outside_note.status, "active",
1010                "the bounded result is not eligible-top-k complete"
1011            );
1012        })
1013        .await;
1014    }
1015
1016    #[tokio::test]
1017    async fn healthy_empty_and_all_matching_searches_return_zero_count() {
1018        bounded(async {
1019            let runtime = KhiveRuntime::memory().unwrap();
1020            let token = NamespaceToken::local();
1021            for selector in [
1022                NoteStatusSelector::Active,
1023                NoteStatusSelector::Archived,
1024                NoteStatusSelector::Any,
1025            ] {
1026                let (hits, count) = select(&runtime, &token, selector, 10).await;
1027                assert!(hits.is_empty());
1028                assert_eq!(count, 0);
1029                let (outcome, count) = runtime
1030                    .search_notes_outcome_with_text_mode_and_status(
1031                        &token,
1032                        QUERY,
1033                        10,
1034                        None,
1035                        true,
1036                        &[],
1037                        None,
1038                        TextQueryMode::Plain,
1039                        selector,
1040                        None,
1041                    )
1042                    .await
1043                    .unwrap();
1044                assert!(outcome.hits.is_empty());
1045                assert!(outcome.vector_error.is_none());
1046                assert_eq!(count, 0);
1047            }
1048            let ns = token.namespace().as_str();
1049            let id = seed(
1050                &runtime,
1051                &token,
1052                note(ns, "observation", "active"),
1053                ns,
1054                "observation",
1055            )
1056            .await;
1057            let (hits, count) = select(&runtime, &token, NoteStatusSelector::Active, 10).await;
1058            assert_eq!(ids(&hits), HashSet::from([id]));
1059            assert_eq!(count, 0);
1060        })
1061        .await;
1062    }
1063
1064    #[tokio::test]
1065    async fn later_superseded_filter_does_not_revise_status_count() {
1066        bounded(async {
1067            let runtime = KhiveRuntime::memory().unwrap();
1068            let token = NamespaceToken::local();
1069            let mut old = runtime
1070                .create_note(&token, "observation", None, QUERY, None, None, vec![])
1071                .await
1072                .unwrap();
1073            let new = runtime
1074                .create_note(&token, "observation", None, QUERY, None, None, vec![])
1075                .await
1076                .unwrap();
1077            runtime
1078                .link(&token, new.id, old.id, EdgeRelation::Supersedes, 1.0, None)
1079                .await
1080                .unwrap();
1081            old.status = "archived".into();
1082            runtime.backend().upsert_note(old.clone()).await.unwrap();
1083            assert_eq!(
1084                raw_candidates(&runtime, &token, 40).await,
1085                HashSet::from([old.id, new.id])
1086            );
1087            let (all, count) = select(&runtime, &token, NoteStatusSelector::Any, 10).await;
1088            assert_eq!(ids(&all), HashSet::from([old.id, new.id]));
1089            assert_eq!(count, 0);
1090            for (selector, expected, count) in [
1091                (NoteStatusSelector::Active, HashSet::from([new.id]), 1),
1092                (NoteStatusSelector::Archived, HashSet::new(), 1),
1093                (NoteStatusSelector::Any, HashSet::from([new.id]), 0),
1094            ] {
1095                let (hits, dropped) = runtime
1096                    .search_notes_with_text_mode_and_status(
1097                        &token,
1098                        QUERY,
1099                        None,
1100                        10,
1101                        None,
1102                        false,
1103                        &[],
1104                        None,
1105                        TextQueryMode::Plain,
1106                        selector,
1107                        None,
1108                    )
1109                    .await
1110                    .unwrap();
1111                assert_eq!(ids(&hits), expected);
1112                assert_eq!(
1113                    dropped, count,
1114                    "superseded filtering is later than status accounting"
1115                );
1116            }
1117        })
1118        .await;
1119    }
1120
1121    struct FixtureEmbedder {
1122        name: String,
1123        dimensions: usize,
1124        fail: bool,
1125    }
1126    struct FixtureService {
1127        dimensions: usize,
1128        fail: bool,
1129    }
1130
1131    #[async_trait]
1132    impl EmbedderProvider for FixtureEmbedder {
1133        fn name(&self) -> &str {
1134            &self.name
1135        }
1136        fn dimensions(&self) -> usize {
1137            self.dimensions
1138        }
1139        async fn build(&self) -> crate::error::RuntimeResult<Arc<dyn EmbeddingService>> {
1140            Ok(Arc::new(FixtureService {
1141                dimensions: self.dimensions,
1142                fail: self.fail,
1143            }))
1144        }
1145    }
1146
1147    #[async_trait]
1148    impl EmbeddingService for FixtureService {
1149        async fn embed(
1150            &self,
1151            texts: &[String],
1152            _model: EmbeddingModel,
1153        ) -> Result<Vec<Vec<f32>>, EmbedError> {
1154            if self.fail {
1155                Err(EmbedError::InferenceFailed(
1156                    "search status fixture vector failure".into(),
1157                ))
1158            } else {
1159                Ok(texts
1160                    .iter()
1161                    .map(|_| vec![1.0_f32; self.dimensions])
1162                    .collect())
1163            }
1164        }
1165        fn supports_model(&self, _model: EmbeddingModel) -> bool {
1166            true
1167        }
1168        fn name(&self) -> &'static str {
1169            "search-status-fixture"
1170        }
1171    }
1172
1173    #[tokio::test]
1174    async fn same_archived_note_from_both_arms_counts_once() {
1175        bounded(async {
1176            let model = EmbeddingModel::AllMiniLmL6V2;
1177            let runtime = KhiveRuntime::new(crate::RuntimeConfig {
1178                db_path: None,
1179                embedding_model: Some(model),
1180                ..crate::RuntimeConfig::no_embeddings()
1181            })
1182            .unwrap();
1183            let token = NamespaceToken::local();
1184            runtime.register_embedder(FixtureEmbedder {
1185                name: model.to_string(),
1186                dimensions: model.dimensions(),
1187                fail: false,
1188            });
1189            let mut row = runtime
1190                .create_note(&token, "observation", None, QUERY, None, None, vec![])
1191                .await
1192                .unwrap();
1193            let id = row.id;
1194            row.status = "archived".into();
1195            runtime.backend().upsert_note(row).await.unwrap();
1196            let (any, count) = select(&runtime, &token, NoteStatusSelector::Any, 10).await;
1197            assert_eq!(ids(&any), HashSet::from([id]));
1198            assert_eq!(any.len(), 1);
1199            assert_eq!(
1200                any[0].source,
1201                crate::SearchSource::Both,
1202                "fixture must actually exercise both arms"
1203            );
1204            assert_eq!(count, 0);
1205            let (explicit_vector, count) = runtime
1206                .search_notes_with_text_mode_and_status(
1207                    &token,
1208                    QUERY,
1209                    Some(vec![1.0_f32; model.dimensions()]),
1210                    10,
1211                    None,
1212                    true,
1213                    &[],
1214                    None,
1215                    TextQueryMode::Plain,
1216                    NoteStatusSelector::Any,
1217                    None,
1218                )
1219                .await
1220                .unwrap();
1221            assert_eq!(ids(&explicit_vector), HashSet::from([id]));
1222            assert_eq!(explicit_vector[0].source, crate::SearchSource::Both);
1223            assert_eq!(count, 0);
1224            let (active, count) = select(&runtime, &token, NoteStatusSelector::Active, 10).await;
1225            assert!(active.is_empty());
1226            assert_eq!(count, 1);
1227        })
1228        .await;
1229    }
1230
1231    #[tokio::test]
1232    async fn tolerant_selector_keeps_text_and_count_when_strict_vector_fails() {
1233        bounded(async {
1234            let model = EmbeddingModel::AllMiniLmL6V2;
1235            let runtime = KhiveRuntime::new(crate::RuntimeConfig {
1236                db_path: None,
1237                embedding_model: Some(model),
1238                ..crate::RuntimeConfig::no_embeddings()
1239            })
1240            .unwrap();
1241            let token = NamespaceToken::local();
1242            let ns = token.namespace().as_str();
1243            let active = seed(
1244                &runtime,
1245                &token,
1246                note(ns, "observation", "active"),
1247                ns,
1248                "observation",
1249            )
1250            .await;
1251            seed(
1252                &runtime,
1253                &token,
1254                note(ns, "observation", "archived"),
1255                ns,
1256                "observation",
1257            )
1258            .await;
1259            runtime.register_embedder(FixtureEmbedder {
1260                name: model.to_string(),
1261                dimensions: model.dimensions(),
1262                fail: true,
1263            });
1264            let error = runtime
1265                .search_notes_with_text_mode_and_status(
1266                    &token,
1267                    QUERY,
1268                    None,
1269                    10,
1270                    None,
1271                    true,
1272                    &[],
1273                    None,
1274                    TextQueryMode::Plain,
1275                    NoteStatusSelector::Active,
1276                    None,
1277                )
1278                .await
1279                .unwrap_err();
1280            assert!(error
1281                .to_string()
1282                .contains("search status fixture vector failure"));
1283            let (outcome, count) = runtime
1284                .search_notes_outcome_with_text_mode_and_status(
1285                    &token,
1286                    QUERY,
1287                    10,
1288                    None,
1289                    true,
1290                    &[],
1291                    None,
1292                    TextQueryMode::Plain,
1293                    NoteStatusSelector::Active,
1294                    None,
1295                )
1296                .await
1297                .unwrap();
1298            assert_eq!(ids(&outcome.hits), HashSet::from([active]));
1299            assert_eq!(count, 1);
1300            assert!(outcome
1301                .vector_error
1302                .as_deref()
1303                .unwrap()
1304                .contains("search status fixture vector failure"));
1305        })
1306        .await;
1307    }
1308}