Skip to main content

khive_runtime/
note_search_ann.rs

1//! Pack-owned ANN candidate source for the note-substrate search vector leg.
2//!
3//! The runtime owns this neutral seam so its note search does not depend on a
4//! higher-layer pack. The memory pack installs the provider for its backend.
5
6use std::sync::atomic::{AtomicU64, Ordering};
7
8use async_trait::async_trait;
9use khive_db::pool::NoteSearchFallbackCause;
10use khive_db::ConnectionPool;
11use khive_storage::types::VectorSearchHit;
12
13use crate::{KhiveRuntime, NamespaceToken, RuntimeResult};
14
15static ANN_ROUTE_TOTAL: AtomicU64 = AtomicU64::new(0);
16static FALLBACK_ROUTE_TOTAL: AtomicU64 = AtomicU64::new(0);
17
18/// An installed graph candidate source for one database backend.
19///
20/// `None` means this model has no graph this consumer may serve and licenses the
21/// existing exact sqlite-vec fallback. Errors propagate rather than silently
22/// changing route. Implementations merge the registered consumer's fresh tail
23/// before returning candidates.
24#[async_trait]
25pub trait NoteSearchAnnProvider: Send + Sync {
26    /// Backend identity whose note vectors the graph indexes.
27    fn backend_id(&self) -> &str;
28
29    /// Match the actual opened backend, not only its logical name. Two
30    /// independently opened databases may both have the default `main` ID.
31    fn serves_backend(&self, runtime: &KhiveRuntime) -> bool;
32
33    /// Return ANN plus fresh-tail candidates in the same score and ordering
34    /// contract as `VectorStore::search`.
35    async fn search(
36        &self,
37        token: &NamespaceToken,
38        model: &str,
39        query_embedding: &[f32],
40        top_k: u32,
41    ) -> RuntimeResult<Option<Vec<VectorSearchHit>>>;
42}
43
44fn increment(counter: &AtomicU64) {
45    let _ = counter.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |value| {
46        Some(value.saturating_add(1))
47    });
48}
49
50pub(crate) fn record_ann_route(pool: &ConnectionPool) {
51    pool.record_note_search_ann_route();
52    increment(&ANN_ROUTE_TOTAL);
53}
54
55pub(crate) fn record_fallback_route(pool: &ConnectionPool, cause: NoteSearchFallbackCause) {
56    pool.record_note_search_fallback_route(cause);
57    increment(&FALLBACK_ROUTE_TOTAL);
58}
59
60/// Process-lifetime note-search vector route counts. The pair does not reset
61/// when a database pool is reopened or diagnostics is collected.
62pub fn route_totals() -> (u64, u64) {
63    (
64        ANN_ROUTE_TOTAL.load(Ordering::Relaxed),
65        FALLBACK_ROUTE_TOTAL.load(Ordering::Relaxed),
66    )
67}