use std::collections::{HashMap, HashSet};
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use serde_json::{json, Value};
use uuid::Uuid;
use khive_runtime::{
hex_prefix_to_uuid_pattern, KhiveRuntime, Namespace, NamespaceToken, RuntimeError,
};
use khive_score::DeterministicScore;
use khive_storage::types::{PageRequest, SqlStatement, SqlValue};
use khive_storage::EntityFilter;
use super::lexical_timeout::{
LexicalBound, LexicalPass, LexicalPhase, LexicalStage, LexicalTimeout,
};
use super::matching;
use super::schema::{Atom, ComposeParams, Domain, SearchParams, SuggestParams};
use super::scoring::{
compute_idf, exact_name_bonus, expand_terms, load_candidates_from_atoms, score_candidate,
Candidate, Weights,
};
use super::sections::to_slug;
use super::util::{
atom_embed_text, atom_from_row, deser, domain_from_row, estimate_compose_item_tokens,
explicitly_requested_status, is_stop, row_bool, row_i64, row_str, sql_err, status_multiplier,
status_sql_clause, status_values, CANDIDATE_POOL, CHARS_PER_TOKEN, D_SUGGEST_RERANK_ALPHA,
MIN_TERM_LEN,
};
use super::vamana;
use super::KnowledgeHandlers;
#[derive(Clone)]
struct ScoredHit {
id: String,
slug: String,
name: String,
content: Option<String>,
tags: Option<String>,
finalized: bool,
is_domain: bool,
status: Option<String>,
score: f32,
provenance: ScoreProvenance,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
struct ScoreProvenance {
lexical: bool,
ann: bool,
embedding_rerank: bool,
}
impl ScoreProvenance {
const fn lexical() -> Self {
Self {
lexical: true,
ann: false,
embedding_rerank: false,
}
}
const fn ann() -> Self {
Self {
lexical: false,
ann: true,
embedding_rerank: false,
}
}
fn merge_sources(&mut self, other: Self) {
self.lexical |= other.lexical;
self.ann |= other.ann;
self.embedding_rerank |= other.embedding_rerank;
}
fn to_json(self) -> Value {
let mut sources = Vec::with_capacity(2);
if self.lexical {
sources.push("lexical");
}
if self.ann {
sources.push("ann");
}
json!({
"sources": sources,
"embedding_rerank": self.embedding_rerank,
"normalization": "s_over_s_plus_1",
"calibrated": false,
})
}
}
fn candidate_fallback(hits: &[ScoredHit]) -> &'static str {
if hits.iter().any(|hit| hit.provenance.ann) && !hits.iter().any(|hit| hit.provenance.lexical) {
"ann"
} else {
"none"
}
}
enum AnnAvailability {
Ready,
WarmingTimedOut { corpus_non_empty: bool },
Absent,
}
struct AnnSearchState {
hits: Vec<(Uuid, f32)>,
availability: AnnAvailability,
source_exhausted: bool,
}
struct FreshTailSearchState {
hits: Vec<(Uuid, f32)>,
source_exhausted: bool,
}
async fn merge_fresh_tail_for_search(
runtime: &KhiveRuntime,
ann: &vamana::SharedAnn,
key: &vamana::AnnKey,
query_embedding: &[f32],
k: usize,
loaded: Option<(Vec<(Uuid, f32)>, u64)>,
) -> FreshTailSearchState {
let (candidates, watermark, source_exhausted) = match loaded {
Some((candidates, watermark)) => {
let source_exhausted = candidates.len() < k;
(candidates, Some(watermark), source_exhausted)
}
None => (Vec::new(), None, true),
};
match vamana::fresh_tail_leg(runtime, ann, key, query_embedding, k, watermark).await {
vamana::FreshTailOutcome::Ops(ops) => FreshTailSearchState {
hits: vamana::merge_fresh_tail_off_thread(candidates, query_embedding, ops).await,
source_exhausted,
},
vamana::FreshTailOutcome::Replace {
candidates,
source_exhausted,
} => FreshTailSearchState {
hits: candidates,
source_exhausted,
},
vamana::FreshTailOutcome::Skipped => FreshTailSearchState {
hits: candidates,
source_exhausted,
},
}
}
async fn search_ann_with_warm_wait(
runtime: &KhiveRuntime,
token: &NamespaceToken,
ann: &vamana::SharedAnn,
key: &vamana::AnnKey,
query_embedding: &[f32],
k: usize,
) -> AnnSearchState {
if let Some(loaded) = vamana::search_loaded_with_seq(ann, key, query_embedding, k).await {
let tail =
merge_fresh_tail_for_search(runtime, ann, key, query_embedding, k, Some(loaded)).await;
return AnnSearchState {
hits: tail.hits,
availability: AnnAvailability::Ready,
source_exhausted: tail.source_exhausted,
};
}
if !vamana::is_warming_not_loaded(ann, key) {
let tail = merge_fresh_tail_for_search(runtime, ann, key, query_embedding, k, None).await;
return AnnSearchState {
hits: tail.hits,
availability: AnnAvailability::Absent,
source_exhausted: tail.source_exhausted,
};
}
if vamana::wait_ready(
ann,
key,
vamana::warm_wait_timeout_ms(),
vamana::ANN_WARM_WAIT_POLL_MS,
)
.await
{
let loaded = vamana::search_loaded_with_seq(ann, key, query_embedding, k).await;
let availability = if loaded.is_some() {
AnnAvailability::Ready
} else {
AnnAvailability::Absent
};
let tail = merge_fresh_tail_for_search(runtime, ann, key, query_embedding, k, loaded).await;
return AnnSearchState {
hits: tail.hits,
availability,
source_exhausted: tail.source_exhausted,
};
}
let corpus_non_empty =
vamana::compute_fingerprint(runtime, token, runtime.default_embedder_name())
.await
.map(|fingerprint| fingerprint.vector_count > 0)
.unwrap_or(false);
let tail = merge_fresh_tail_for_search(runtime, ann, key, query_embedding, k, None).await;
AnnSearchState {
hits: tail.hits,
availability: AnnAvailability::WarmingTimedOut { corpus_non_empty },
source_exhausted: tail.source_exhausted,
}
}
const RRF_K: usize = 60;
fn normalize_rrf_score(raw: f32, source_count: usize, k: usize) -> f32 {
if source_count == 0 {
return 0.0;
}
let theoretical_max = source_count as f32 / (k as f32 + 1.0);
(raw / theoretical_max).clamp(0.0, 1.0)
}
fn fuse_ann_hits(fts_hits: &mut Vec<ScoredHit>, ann_hits: &[ScoredHit], min_score: f32) {
let drained: Vec<ScoredHit> = std::mem::take(fts_hits);
let fts_source: Vec<(String, DeterministicScore)> = drained
.iter()
.map(|hit| (hit.id.clone(), DeterministicScore::from_f32(hit.score)))
.collect();
let mut by_id: HashMap<String, ScoredHit> = drained
.into_iter()
.map(|hit| (hit.id.clone(), hit))
.collect();
let ann_source: Vec<(String, DeterministicScore)> = ann_hits
.iter()
.map(|hit| (hit.id.clone(), DeterministicScore::from_f32(hit.score)))
.collect();
for hit in ann_hits {
by_id
.entry(hit.id.clone())
.and_modify(|existing| existing.provenance.merge_sources(hit.provenance))
.or_insert_with(|| hit.clone());
}
let source_count = usize::from(!fts_source.is_empty()) + usize::from(!ann_source.is_empty());
let fused = khive_fusion::reciprocal_rank_fusion(vec![fts_source, ann_source], RRF_K);
for (id, fused_score) in fused {
let raw_score = fused_score.to_f64() as f32;
let score = normalize_rrf_score(raw_score, source_count, RRF_K);
if score < min_score {
continue;
}
if let Some(mut hit) = by_id.remove(&id) {
hit.score = score;
fts_hits.push(hit);
}
}
}
fn filter_by_excluded_statuses(hits: &mut Vec<ScoredHit>, exclude_statuses: &[&str]) {
if exclude_statuses.is_empty() {
return;
}
hits.retain(|hit| {
let status = hit.status.as_deref().unwrap_or("");
!exclude_statuses.contains(&status)
});
}
fn filter_hits_by_status(
hits: &mut Vec<ScoredHit>,
statuses: &[String],
exclude_statuses: &[&str],
) {
if statuses.is_empty() {
filter_by_excluded_statuses(hits, exclude_statuses);
return;
}
hits.retain(|hit| {
hit.status
.as_deref()
.is_some_and(|status| statuses.iter().any(|allowed| allowed == status))
});
}
fn deprecated_allowed_by_status_policy(statuses: &[String], exclude_statuses: &[&str]) -> bool {
if statuses.is_empty() {
!exclude_statuses.contains(&"deprecated")
} else {
explicitly_requested_status(statuses, "deprecated")
}
}
fn filter_hits_by_type(hits: &mut Vec<ScoredHit>, type_filter: Option<&str>) {
let filt = match type_filter {
Some(f) if !f.is_empty() => f,
_ => return,
};
let want_domain = filt == "domain";
hits.retain(|hit| {
if want_domain {
hit.is_domain
} else {
!hit.is_domain
}
});
}
fn apply_status_multipliers(hits: &mut Vec<ScoredHit>, include_deprecated: bool) {
hits.retain_mut(|hit| {
let multiplier = status_multiplier(hit.status.as_deref());
hit.score = (hit.score / (hit.score + 1.0) * multiplier).clamp(0.0, 1.0);
include_deprecated || multiplier > 0.0
});
hits.sort_by(|a, b| {
b.score
.partial_cmp(&a.score)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| a.slug.cmp(&b.slug))
});
}
fn enforce_min_score_floor(hits: &mut Vec<ScoredHit>, min_score: f32) {
hits.retain(|hit| hit.score >= min_score);
}
fn quote_fts5_phrase(raw_query: &str) -> String {
let escaped = raw_query.replace('"', "\"\"");
format!("\"{escaped}\"")
}
fn fts5_candidate_terms(raw_query: &str) -> Vec<String> {
let mut seen = HashSet::new();
let mut terms: Vec<String> = matching::tokenize_field(raw_query)
.into_iter()
.filter(|term| term.len() >= MIN_TERM_LEN && !is_stop(term))
.filter(|term| seen.insert(term.clone()))
.collect();
if terms.is_empty() {
vec![quote_fts5_phrase(raw_query)]
} else {
let _ = expand_terms(&mut terms);
terms.iter().map(|term| quote_fts5_phrase(term)).collect()
}
}
fn type_eligibility_sql(type_filter: Option<&str>, atom_alias: &str) -> String {
match type_filter {
Some("domain") => format!(" AND {atom_alias}.tags LIKE '%\"type:domain\"%'"),
Some(filter) if !filter.is_empty() => {
format!(" AND {atom_alias}.tags NOT LIKE '%\"type:domain\"%'")
}
_ => String::new(),
}
}
const FTS_TERM_LIMIT: usize = 500;
const FTS_TERM_COUNT_LIMIT: usize = 32;
struct FtsTermBudget {
remaining: AtomicUsize,
truncated: AtomicBool,
}
impl FtsTermBudget {
fn new() -> Self {
Self {
remaining: AtomicUsize::new(FTS_TERM_COUNT_LIMIT),
truncated: AtomicBool::new(false),
}
}
fn admit(&self, mut terms: Vec<String>) -> Vec<String> {
let remaining = self
.remaining
.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |remaining| {
Some(remaining.saturating_sub(terms.len()))
})
.expect("term reservation always succeeds");
if terms.len() > remaining {
self.truncated.store(true, Ordering::Relaxed);
terms.truncate(remaining);
}
terms
}
fn truncated(&self) -> bool {
self.truncated.load(Ordering::Relaxed)
}
fn available_for(&self, raw_query: &str) -> usize {
fts5_candidate_terms(raw_query)
.len()
.min(self.remaining.load(Ordering::Relaxed))
}
}
fn phase_a_rowids_statement(term: &str, limit: usize) -> SqlStatement {
SqlStatement {
sql: "SELECT rowid FROM fts_knowledge WHERE fts_knowledge MATCH ?1 \
ORDER BY rowid LIMIT ?2"
.into(),
params: vec![SqlValue::Text(term.into()), SqlValue::Integer(limit as i64)],
label: Some("knowledge.fts_rowids".into()),
}
}
fn term_frequency_statement(term: &str) -> SqlStatement {
SqlStatement {
sql: "SELECT count(*) AS frequency FROM ( \
SELECT rowid FROM fts_knowledge WHERE fts_knowledge MATCH ?1 \
ORDER BY rowid LIMIT ?2 \
)"
.into(),
params: vec![
SqlValue::Text(term.into()),
SqlValue::Integer((FTS_TERM_LIMIT + 1) as i64),
],
label: Some("knowledge.fts_term_frequency".into()),
}
}
async fn rarest_fts_terms_first(
reader: &mut dyn khive_storage::SqlReader,
terms: Vec<String>,
stage: &mut LexicalStage,
) -> Result<Vec<String>, khive_storage::StorageError> {
let mut frequencies = Vec::with_capacity(terms.len());
#[cfg_attr(not(test), allow(clippy::unused_enumerate_index))]
for (_probe_index, term) in terms.into_iter().enumerate() {
let rows = stage
.read_bounded(
LexicalPhase::TermFrequency,
LexicalBound::OrderingProbe,
rarity_probe_budget(),
reader.query_all(term_frequency_statement(&term)),
)
.await?;
let frequency = rows
.first()
.and_then(|row| row_i64(row, "frequency"))
.ok_or_else(|| khive_storage::StorageError::Serialization {
capability: khive_storage::StorageCapability::Sql,
message: "term frequency probe returned no integer count".into(),
})?;
if frequency > 0 {
frequencies.push((term, frequency));
}
#[cfg(test)]
advance_fts_test_probe_deadline_after_term(_probe_index + 1).await;
}
frequencies
.sort_unstable_by(|(a, a_count), (b, b_count)| a_count.cmp(b_count).then_with(|| a.cmp(b)));
Ok(frequencies.into_iter().map(|(term, _)| term).collect())
}
const PHASE_A_OVERFETCH_FACTOR: usize = 4;
const PHASE_A_WIDEN_CEILING: usize = 8000;
pub(crate) const LEXICAL_STAGE_BUDGET_MS: u64 = 2_000;
const LEXICAL_STAGE_EXTRA_TERM_QUARTERS: usize = 12;
fn lexical_stage_budget_for_terms(
base: std::time::Duration,
admitted_terms: usize,
) -> std::time::Duration {
let quarters = 4 + admitted_terms
.saturating_sub(1)
.min(LEXICAL_STAGE_EXTRA_TERM_QUARTERS);
base.saturating_mul(quarters as u32) / 4
}
const RARITY_PROBE_BUDGET_NUMERATOR: u32 = 1;
const RARITY_PROBE_BUDGET_DENOMINATOR: u32 = 4;
fn rarity_probe_budget() -> std::time::Duration {
lexical_stage_budget() / RARITY_PROBE_BUDGET_DENOMINATOR * RARITY_PROBE_BUDGET_NUMERATOR
}
tokio::task_local! {
static LEXICAL_STAGE_BUDGET_OVERRIDE_MS: u64;
static PHASE_A_WIDEN_CEILING_OVERRIDE: usize;
}
#[cfg(test)]
tokio::task_local! {
static MEMBER_SIZING_READ_TIMEOUT: ();
}
#[cfg(test)]
pub(crate) async fn with_member_sizing_read_timeout<F: std::future::Future>(
future: F,
) -> F::Output {
MEMBER_SIZING_READ_TIMEOUT.scope((), future).await
}
fn lexical_stage_budget() -> std::time::Duration {
let ms = LEXICAL_STAGE_BUDGET_OVERRIDE_MS
.try_with(|ms| *ms)
.unwrap_or(LEXICAL_STAGE_BUDGET_MS);
std::time::Duration::from_millis(ms)
}
fn phase_a_widen_ceiling() -> usize {
PHASE_A_WIDEN_CEILING_OVERRIDE
.try_with(|ceiling| *ceiling)
.unwrap_or(PHASE_A_WIDEN_CEILING)
}
#[cfg(test)]
pub(crate) async fn with_lexical_stage_budget_override_ms<F>(ms: u64, future: F) -> F::Output
where
F: std::future::Future,
{
LEXICAL_STAGE_BUDGET_OVERRIDE_MS.scope(ms, future).await
}
#[cfg(test)]
pub(crate) async fn with_phase_a_widen_ceiling_override<F>(ceiling: usize, future: F) -> F::Output
where
F: std::future::Future,
{
PHASE_A_WIDEN_CEILING_OVERRIDE.scope(ceiling, future).await
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum LexicalCandidateState {
Matched,
ExactName,
NoMatch,
Filtered,
PartialTimeout,
TimedOut,
}
impl LexicalCandidateState {
fn as_str(self) -> &'static str {
match self {
Self::Matched => "matched",
Self::ExactName => "exact_name",
Self::NoMatch => "no_match",
Self::Filtered => "filtered",
Self::PartialTimeout => "partial_timeout",
Self::TimedOut => "timed_out",
}
}
fn merge(states: &[Self]) -> Self {
let timed_out = states
.iter()
.filter(|&&state| state == Self::TimedOut)
.count();
if !states.is_empty() && timed_out == states.len() {
Self::TimedOut
} else if timed_out > 0 || states.contains(&Self::PartialTimeout) {
Self::PartialTimeout
} else if states.contains(&Self::Matched) {
Self::Matched
} else if states.contains(&Self::ExactName) {
Self::ExactName
} else if states.contains(&Self::Filtered) {
Self::Filtered
} else {
Self::NoMatch
}
}
}
struct FtsFetchOutcome {
atoms: Vec<Atom>,
timeout: Option<LexicalTimeout>,
state: LexicalCandidateState,
}
#[cfg(test)]
#[derive(Clone, Copy)]
struct FtsTestDeadlineAdvance {
after_completed_terms: usize,
by: std::time::Duration,
}
#[cfg(test)]
tokio::task_local! {
static FTS_TEST_DEADLINE_ADVANCE: FtsTestDeadlineAdvance;
}
#[cfg(test)]
async fn advance_fts_test_deadline_after_term(completed_terms: usize) {
let advance_by = FTS_TEST_DEADLINE_ADVANCE
.try_with(|control| {
(completed_terms == control.after_completed_terms).then_some(control.by)
})
.ok()
.flatten();
if let Some(advance_by) = advance_by {
tokio::time::advance(advance_by).await;
}
}
#[cfg(test)]
tokio::task_local! {
static FTS_TEST_PROBE_DEADLINE_ADVANCE: FtsTestDeadlineAdvance;
}
#[cfg(test)]
async fn advance_fts_test_probe_deadline_after_term(completed_terms: usize) {
let advance_by = FTS_TEST_PROBE_DEADLINE_ADVANCE
.try_with(|control| {
(completed_terms == control.after_completed_terms).then_some(control.by)
})
.ok()
.flatten();
if let Some(advance_by) = advance_by {
tokio::time::advance(advance_by).await;
}
}
#[cfg(test)]
pub(crate) async fn with_fts_probe_deadline_advance_after_term<F>(
after_completed_terms: usize,
by: std::time::Duration,
future: F,
) -> F::Output
where
F: std::future::Future,
{
FTS_TEST_PROBE_DEADLINE_ADVANCE
.scope(
FtsTestDeadlineAdvance {
after_completed_terms,
by,
},
future,
)
.await
}
#[cfg(test)]
pub(crate) async fn with_fts_deadline_advance_after_term<F>(
after_completed_terms: usize,
by: std::time::Duration,
future: F,
) -> F::Output
where
F: std::future::Future,
{
FTS_TEST_DEADLINE_ADVANCE
.scope(
FtsTestDeadlineAdvance {
after_completed_terms,
by,
},
future,
)
.await
}
fn is_timeout(e: &khive_storage::StorageError) -> bool {
matches!(e, khive_storage::StorageError::Timeout { .. })
}
fn is_read_timeout(e: &RuntimeError) -> bool {
matches!(
e,
RuntimeError::Storage(khive_storage::StorageError::Timeout { .. })
)
}
#[allow(clippy::too_many_arguments)]
async fn fetch_fts_candidates(
runtime: &KhiveRuntime,
ns: &str,
raw_query: &str,
type_filter: Option<&str>,
statuses: &[String],
exclude_statuses: &[&str],
fetch_limit: usize,
term_budget: &FtsTermBudget,
mut stage: LexicalStage,
) -> Result<FtsFetchOutcome, RuntimeError> {
let mut terms = term_budget.admit(fts5_candidate_terms(raw_query));
if terms.is_empty() {
return Ok(FtsFetchOutcome {
atoms: Vec::new(),
timeout: None,
state: LexicalCandidateState::NoMatch,
});
}
let sql = runtime.sql();
let reader = match stage.read(LexicalPhase::ReaderOpen, sql.reader()).await {
Ok(reader) => reader,
Err(e) if is_timeout(&e) => {
return Ok(FtsFetchOutcome {
atoms: Vec::new(),
timeout: stage.timeout,
state: LexicalCandidateState::TimedOut,
});
}
Err(e) => return Err(sql_err("search fts reader", e)),
};
#[cfg(test)]
let reader = tests::record_term_probes(reader);
let mut reader = reader;
let type_clause = type_eligibility_sql(type_filter, "a");
let per_term_limit = if terms.len() == 1 {
fetch_limit
} else {
fetch_limit.clamp(1, FTS_TERM_LIMIT)
};
let has_eligibility_clause = !status_sql_clause(statuses, exclude_statuses, 1)
.0
.is_empty()
|| !type_clause.is_empty();
let widen_ceiling = phase_a_widen_ceiling();
let base_probe_limit = if has_eligibility_clause {
per_term_limit
.saturating_mul(PHASE_A_OVERFETCH_FACTOR)
.min(widen_ceiling)
} else {
per_term_limit
};
let mut rarity_probe_timed_out = false;
if terms.len() > 1 {
let arrival_order = terms.clone();
let probe_budget = rarity_probe_budget();
let probed = khive_storage::scope_request_read_deadline(probe_budget, async {
rarest_fts_terms_first(reader.as_mut(), terms, &mut stage).await
})
.await;
terms = match probed {
Ok(terms) => terms,
Err(e) if is_timeout(&e) => {
rarity_probe_timed_out = true;
arrival_order
}
Err(e) => return Err(sql_err("search fts term frequency probe", e)),
};
}
let mut per_term_rows: Vec<Vec<Atom>> = Vec::with_capacity(terms.len());
let mut term_probe_rowids: Vec<Vec<i64>> = Vec::with_capacity(terms.len());
let mut unexhausted_terms = Vec::new();
let mut term_query_timed_out = false;
'terms: for term in &terms {
let mut probe_limit = base_probe_limit;
let (mut eligible, probed_rowids, exhausted): (Vec<Atom>, Vec<i64>, bool) = loop {
let phase_a_rows = match stage
.read(
LexicalPhase::PhaseARowids,
reader.query_all(phase_a_rowids_statement(term, probe_limit)),
)
.await
{
Ok(rows) => rows,
Err(e) if is_timeout(&e) => {
term_query_timed_out = true;
break 'terms;
}
Err(e) => return Err(sql_err("search fts phase-a query", e)),
};
let rowids: Vec<i64> = phase_a_rows
.iter()
.filter_map(|r| row_i64(r, "rowid"))
.collect();
let phase_a_full = rowids.len() >= probe_limit;
if rowids.is_empty() {
break (Vec::new(), rowids, true);
}
let mut atoms_by_rowid: HashMap<i64, Atom> = HashMap::with_capacity(rowids.len());
for chunk in rowids.chunks(HYDRATION_ID_CHUNK) {
let statement = phase_b_hydration_statement(
ns,
chunk,
statuses,
exclude_statuses,
type_clause.as_str(),
);
let rows = match stage
.read(LexicalPhase::PhaseBHydration, reader.query_all(statement))
.await
{
Ok(rows) => rows,
Err(e) if is_timeout(&e) => {
term_query_timed_out = true;
break 'terms;
}
Err(e) => return Err(sql_err("search fts phase-b hydration", e)),
};
for row in &rows {
if let (Some(atom), Some(rowid)) = (atom_from_row(row), row_i64(row, "rowid")) {
atoms_by_rowid.insert(rowid, atom);
}
}
}
let eligible_now: Vec<Atom> = rowids
.iter()
.filter_map(|rowid| atoms_by_rowid.get(rowid).cloned())
.collect();
if has_eligibility_clause && eligible_now.len() < per_term_limit && phase_a_full {
if probe_limit < widen_ceiling {
probe_limit = probe_limit
.saturating_mul(PHASE_A_OVERFETCH_FACTOR)
.min(widen_ceiling);
continue;
}
let (scoped_status_clause, scoped_status_params) =
status_sql_clause(statuses, exclude_statuses, 4);
let scoped_sql = format!(
"SELECT a.* FROM fts_knowledge \
CROSS JOIN knowledge_atoms AS a ON a.rowid = fts_knowledge.rowid \
WHERE fts_knowledge MATCH ?1 \
AND +a.namespace = ?2 \
AND a.deleted_at IS NULL{scoped_status_clause}{type_clause} \
ORDER BY fts_knowledge.rowid \
LIMIT ?3"
);
let mut scoped_params = vec![
SqlValue::Text(term.clone()),
SqlValue::Text(ns.to_owned()),
SqlValue::Integer(per_term_limit as i64),
];
scoped_params.extend(scoped_status_params);
let scoped_rows = match stage
.read(
LexicalPhase::EligibilityFallback,
reader.query_all(SqlStatement {
sql: scoped_sql,
params: scoped_params,
label: None,
}),
)
.await
{
Ok(rows) => rows,
Err(e) if is_timeout(&e) => {
term_query_timed_out = true;
break 'terms;
}
Err(e) => {
return Err(sql_err("search fts eligibility-scoped ceiling fallback", e));
}
};
break (
scoped_rows.iter().filter_map(atom_from_row).collect(),
rowids,
false,
);
}
break (eligible_now, rowids, !phase_a_full);
};
eligible.truncate(per_term_limit);
per_term_rows.push(eligible);
term_probe_rowids.push(probed_rowids);
if !exhausted {
unexhausted_terms.push(term.clone());
}
#[cfg(test)]
advance_fts_test_deadline_after_term(per_term_rows.len()).await;
}
let mut seen_ids: HashSet<Uuid> = HashSet::new();
let mut combined: Vec<Atom> = Vec::new();
let max_term_rows = per_term_rows.iter().map(Vec::len).max().unwrap_or(0);
'merge: for i in 0..max_term_rows {
for term_rows in &per_term_rows {
if combined.len() >= fetch_limit {
break 'merge;
}
if let Some(atom) = term_rows.get(i) {
if seen_ids.insert(atom.id) {
combined.push(atom.clone());
}
}
}
}
if term_query_timed_out || rarity_probe_timed_out {
return Ok(FtsFetchOutcome {
state: if combined.is_empty() {
LexicalCandidateState::TimedOut
} else {
LexicalCandidateState::PartialTimeout
},
atoms: combined,
timeout: stage.timeout,
});
}
if !combined.is_empty() {
return Ok(FtsFetchOutcome {
atoms: combined,
timeout: None,
state: LexicalCandidateState::Matched,
});
}
let mut probe_rowids: Vec<i64> = term_probe_rowids.into_iter().flatten().collect();
probe_rowids.sort_unstable();
probe_rowids.dedup();
let mut namespace_has_match = false;
for chunk in probe_rowids.chunks(HYDRATION_ID_CHUNK) {
let placeholders = chunk
.iter()
.enumerate()
.map(|(i, _)| format!("?{}", i + 2))
.collect::<Vec<_>>()
.join(",");
let mut params = vec![SqlValue::Text(ns.to_owned())];
params.extend(chunk.iter().map(|rowid| SqlValue::Integer(*rowid)));
let membership_sql = format!(
"SELECT 1 AS present FROM knowledge_atoms \
WHERE rowid IN ({placeholders}) AND namespace = ?1 LIMIT 1"
);
let row = match stage
.read(
LexicalPhase::NamespaceMembership,
reader.query_row(SqlStatement {
sql: membership_sql,
params,
label: None,
}),
)
.await
{
Ok(row) => row,
Err(e) if is_timeout(&e) => {
return Ok(FtsFetchOutcome {
atoms: Vec::new(),
timeout: stage.timeout,
state: LexicalCandidateState::TimedOut,
});
}
Err(e) => return Err(sql_err("search fts namespace membership probe", e)),
};
if row.is_some() {
namespace_has_match = true;
break;
}
}
if !namespace_has_match {
for term in unexhausted_terms {
let row = match stage
.read(
LexicalPhase::NamespaceExistence,
reader.query_row(SqlStatement {
sql: "SELECT 1 AS present FROM fts_knowledge \
CROSS JOIN knowledge_atoms AS a ON a.rowid = fts_knowledge.rowid \
WHERE fts_knowledge MATCH ?1 AND +a.namespace = ?2 LIMIT 1"
.into(),
params: vec![SqlValue::Text(term), SqlValue::Text(ns.to_owned())],
label: None,
}),
)
.await
{
Ok(row) => row,
Err(e) if is_timeout(&e) => {
return Ok(FtsFetchOutcome {
atoms: Vec::new(),
timeout: stage.timeout,
state: LexicalCandidateState::TimedOut,
});
}
Err(e) => return Err(sql_err("search fts scoped namespace existence", e)),
};
if row.is_some() {
namespace_has_match = true;
break;
}
}
}
if namespace_has_match {
return Ok(FtsFetchOutcome {
atoms: Vec::new(),
timeout: None,
state: LexicalCandidateState::Filtered,
});
}
let no_scoreable_terms = !matching::tokenize_field(raw_query)
.iter()
.any(|term| term.len() >= MIN_TERM_LEN && !is_stop(term));
if no_scoreable_terms {
match fetch_exact_name_candidate(
reader.as_mut(),
ns,
raw_query,
type_filter,
statuses,
exclude_statuses,
&mut stage,
)
.await?
{
ExactNameProbe::Hit(atom) => {
return Ok(FtsFetchOutcome {
atoms: vec![*atom],
timeout: None,
state: LexicalCandidateState::ExactName,
})
}
ExactNameProbe::Filtered => {
return Ok(FtsFetchOutcome {
atoms: Vec::new(),
timeout: None,
state: LexicalCandidateState::Filtered,
})
}
ExactNameProbe::TimedOut => {
return Ok(FtsFetchOutcome {
atoms: Vec::new(),
timeout: stage.timeout,
state: LexicalCandidateState::TimedOut,
})
}
ExactNameProbe::Miss => {}
}
}
Ok(FtsFetchOutcome {
atoms: Vec::new(),
timeout: None,
state: LexicalCandidateState::NoMatch,
})
}
fn exact_name_statement(
ns: &str,
slug: &str,
type_filter: Option<&str>,
statuses: &[String],
exclude_statuses: &[&str],
) -> SqlStatement {
let (status_clause, status_params) = status_sql_clause(statuses, exclude_statuses, 3);
let type_clause = type_eligibility_sql(type_filter, "knowledge_atoms");
let mut params = vec![
SqlValue::Text(ns.to_owned()),
SqlValue::Text(slug.to_owned()),
];
params.extend(status_params);
SqlStatement {
sql: format!(
"SELECT *, CASE WHEN 1{status_clause}{type_clause} THEN 1 ELSE 0 END AS exact_name_eligible \
FROM knowledge_atoms \
WHERE namespace = ?1 AND slug = ?2 AND deleted_at IS NULL LIMIT 1"
),
params,
label: Some("knowledge.exact_name".into()),
}
}
async fn fetch_exact_name_candidate(
reader: &mut dyn khive_storage::SqlReader,
ns: &str,
raw_query: &str,
type_filter: Option<&str>,
statuses: &[String],
exclude_statuses: &[&str],
stage: &mut LexicalStage,
) -> Result<ExactNameProbe, RuntimeError> {
let slug = to_slug(raw_query);
if slug.is_empty() {
return Ok(ExactNameProbe::Miss);
}
let row = stage
.read(
LexicalPhase::ExactNameProbe,
reader.query_row(exact_name_statement(
ns,
&slug,
type_filter,
statuses,
exclude_statuses,
)),
)
.await;
match row {
Ok(Some(row)) if row_i64(&row, "exact_name_eligible") != Some(1) => {
Ok(ExactNameProbe::Filtered)
}
Ok(Some(row)) => Ok(atom_from_row(&row).map_or(ExactNameProbe::Miss, |atom| {
ExactNameProbe::Hit(Box::new(atom))
})),
Ok(None) => Ok(ExactNameProbe::Miss),
Err(e) if is_timeout(&e) => Ok(ExactNameProbe::TimedOut),
Err(e) => Err(sql_err("search exact-name query", e)),
}
}
#[derive(Debug)]
enum ExactNameProbe {
Hit(Box<Atom>),
Miss,
Filtered,
TimedOut,
}
struct SearchCtx<'a> {
runtime: &'a KhiveRuntime,
ns: &'a str,
role: Option<&'a str>,
type_filter: Option<&'a str>,
min_score: f32,
w: &'a Weights,
fetch_limit: usize,
statuses: &'a [String],
exclude_statuses: &'a [&'a str],
term_budget: &'a FtsTermBudget,
}
struct SearchCoreOutcome {
hits: Vec<ScoredHit>,
lexical_timeouts: Vec<LexicalTimeout>,
lexical_state: LexicalCandidateState,
}
async fn search_core(
ctx: &SearchCtx<'_>,
query: &str,
pass: LexicalPass,
) -> Result<SearchCoreOutcome, RuntimeError> {
let runtime = ctx.runtime;
let ns = ctx.ns;
let role = ctx.role;
let type_filter = ctx.type_filter;
let min_score = ctx.min_score;
let w = ctx.w;
let fetch_limit = ctx.fetch_limit;
let raw_query = query.trim().to_string();
if raw_query.is_empty() {
return Ok(SearchCoreOutcome {
hits: Vec::new(),
lexical_timeouts: Vec::new(),
lexical_state: LexicalCandidateState::NoMatch,
});
}
let scored_query = match role {
Some(r) if !r.trim().is_empty() => format!("{} {}", r.trim(), raw_query),
_ => raw_query.clone(),
};
let (terms, original_terms, query_order, expanded) = {
let raw_tokens: Vec<String> = matching::tokenize_field(&scored_query)
.into_iter()
.filter(|w| w.len() >= MIN_TERM_LEN && !is_stop(w))
.collect();
let mut seen = HashSet::new();
let qo: Vec<String> = raw_tokens
.iter()
.filter(|w| seen.insert(w.as_str()))
.cloned()
.collect();
let mut t = raw_tokens;
t.sort();
t.dedup();
let originals = t.clone();
let exp = expand_terms(&mut t);
(t, originals, qo, exp)
};
let terms_only_exact = terms.is_empty();
let configured_budget = lexical_stage_budget_for_terms(
lexical_stage_budget(),
ctx.term_budget.available_for(&raw_query),
);
let stage_started = tokio::time::Instant::now();
let FtsFetchOutcome {
atoms,
timeout,
state: lexical_state,
} = khive_storage::scope_request_read_deadline(configured_budget, async {
let stage = LexicalStage::new(pass, stage_started, configured_budget);
fetch_fts_candidates(
runtime,
ns,
&raw_query,
type_filter,
ctx.statuses,
ctx.exclude_statuses,
CANDIDATE_POOL,
ctx.term_budget,
stage,
)
.await
})
.await?;
let lexical_timeouts: Vec<_> = timeout.into_iter().collect();
if atoms.is_empty() {
return Ok(SearchCoreOutcome {
hits: Vec::new(),
lexical_timeouts,
lexical_state,
});
}
let candidates = load_candidates_from_atoms(&atoms, type_filter);
if candidates.is_empty() {
return Ok(SearchCoreOutcome {
hits: Vec::new(),
lexical_timeouts,
lexical_state: if lexical_state == LexicalCandidateState::PartialTimeout {
lexical_state
} else {
LexicalCandidateState::Filtered
},
});
}
let idf = compute_idf(&candidates, &terms, &expanded, w.expand_discount);
let mut scored: Vec<(f32, &Candidate)> = candidates
.iter()
.filter_map(|cand| {
let base = if lexical_state == LexicalCandidateState::ExactName {
w.w_exact_name
} else if terms_only_exact {
exact_name_bonus(&cand.name_raw, &raw_query, w.w_exact_name)
} else {
score_candidate(
cand,
&terms,
&original_terms,
&query_order,
&idf,
&raw_query,
w,
)
};
if base >= min_score {
Some((base, cand))
} else {
None
}
})
.collect();
scored.sort_by(|a, b| {
b.0.partial_cmp(&a.0)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| a.1.slug.cmp(&b.1.slug))
});
scored.truncate(fetch_limit);
Ok(SearchCoreOutcome {
hits: scored
.into_iter()
.map(|(score, cand)| ScoredHit {
id: cand.id.clone(),
slug: cand.slug.clone(),
name: cand.name_raw.clone(),
content: cand.content_raw.clone(),
tags: cand.tags_raw.clone(),
status: cand.status_raw.clone(),
finalized: cand.finalized,
is_domain: cand.is_domain,
score,
provenance: ScoreProvenance::lexical(),
})
.collect(),
lexical_timeouts,
lexical_state,
})
}
async fn search_decomposed(
ctx: &SearchCtx<'_>,
query: &str,
intersection_bonus: f32,
) -> Result<SearchCoreOutcome, RuntimeError> {
let non_stop: Vec<&str> = query
.split_whitespace()
.filter(|w| w.len() >= MIN_TERM_LEN && !is_stop(&w.to_lowercase()))
.collect();
let mid = non_stop.len() / 2;
let sub_q1: String = non_stop[..mid].join(" ");
let sub_q2: String = non_stop[mid..].join(" ");
let sub_limit = ctx.fetch_limit.min(50);
let SearchCoreOutcome {
hits: full,
mut lexical_timeouts,
lexical_state: full_state,
} = search_core(ctx, query, LexicalPass::Full).await?;
let sub_ctx1 = SearchCtx {
runtime: ctx.runtime,
ns: ctx.ns,
role: None,
type_filter: ctx.type_filter,
min_score: 0.0,
w: ctx.w,
fetch_limit: sub_limit,
statuses: ctx.statuses,
exclude_statuses: ctx.exclude_statuses,
term_budget: ctx.term_budget,
};
let SearchCoreOutcome {
hits: s1,
lexical_timeouts: s1_timeouts,
lexical_state: s1_state,
} = search_core(&sub_ctx1, &sub_q1, LexicalPass::Subquery1).await?;
let SearchCoreOutcome {
hits: s2,
lexical_timeouts: s2_timeouts,
lexical_state: s2_state,
} = search_core(&sub_ctx1, &sub_q2, LexicalPass::Subquery2).await?;
lexical_timeouts.extend(s1_timeouts);
lexical_timeouts.extend(s2_timeouts);
Ok(SearchCoreOutcome {
hits: merge_decomposed_hits(full, [s1, s2], intersection_bonus, ctx.fetch_limit),
lexical_timeouts,
lexical_state: LexicalCandidateState::merge(&[full_state, s1_state, s2_state]),
})
}
fn merge_decomposed_hits(
full: Vec<ScoredHit>,
subqueries: [Vec<ScoredHit>; 2],
intersection_bonus: f32,
fetch_limit: usize,
) -> Vec<ScoredHit> {
let mut scores: HashMap<String, f32> = HashMap::new();
let mut data: HashMap<String, ScoredHit> = HashMap::new();
for mut hit in full {
scores.insert(hit.id.clone(), hit.score);
if let Some(existing) = data.get(&hit.id) {
hit.provenance.merge_sources(existing.provenance);
}
data.insert(hit.id.clone(), hit);
}
let mut sub_counts: HashMap<String, u32> = HashMap::new();
for hits in subqueries {
let mut seen: HashSet<String> = HashSet::new();
for hit in hits {
if let Some(existing) = data.get_mut(&hit.id) {
existing.provenance.merge_sources(hit.provenance);
}
if !seen.insert(hit.id.clone()) {
continue;
}
*sub_counts.entry(hit.id.clone()).or_default() += 1;
if !data.contains_key(&hit.id) {
scores.insert(hit.id.clone(), hit.score * 0.3);
data.insert(hit.id.clone(), hit);
}
}
}
for (id, count) in &sub_counts {
if *count >= 2 {
if let Some(s) = scores.get_mut(id) {
*s *= 1.0 + intersection_bonus * (*count as f32 - 1.0);
}
}
}
let mut ranked: Vec<ScoredHit> = data
.into_values()
.map(|mut h| {
if let Some(&s) = scores.get(&h.id) {
h.score = s;
}
h
})
.collect();
ranked.sort_by(|a, b| {
b.score
.partial_cmp(&a.score)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| a.slug.cmp(&b.slug))
});
ranked.truncate(fetch_limit);
ranked
}
#[derive(Debug, Default, Clone)]
struct QueryEmbeddingCache {
role_specific: RoleSpecificEmbedding,
generic: Option<Vec<f32>>,
}
#[derive(Debug, Clone, Default, PartialEq)]
enum RoleSpecificEmbedding {
#[default]
NotAttempted,
Failed,
Vector(Vec<f32>),
}
impl RoleSpecificEmbedding {
fn as_deref(&self) -> Option<&[f32]> {
match self {
Self::Vector(v) => Some(v.as_slice()),
Self::NotAttempted | Self::Failed => None,
}
}
fn is_not_attempted(&self) -> bool {
matches!(self, Self::NotAttempted)
}
}
impl QueryEmbeddingCache {
fn any(&self) -> Option<&[f32]> {
self.role_specific.as_deref().or(self.generic.as_deref())
}
}
async fn embed_cosine_scores(
runtime: &KhiveRuntime,
query: &str,
query_embedding: &mut QueryEmbeddingCache,
candidate_texts: &[String],
) -> Result<Option<Vec<f32>>, RuntimeError> {
if runtime.default_embedder_name().is_empty() || candidate_texts.is_empty() {
return Ok(None);
}
let query_was_cached = query_embedding.any().is_some();
let texts = if query_was_cached {
candidate_texts.to_vec()
} else {
let mut texts = Vec::with_capacity(candidate_texts.len() + 1);
texts.push(query.to_string());
texts.extend_from_slice(candidate_texts);
texts
};
let embeddings = match khive_storage::await_request_read_phase(
"knowledge.embedding_rerank",
runtime.embed_batch(&texts),
)
.await
{
Ok(Ok(embeddings)) => embeddings,
Ok(Err(_)) => return Ok(None),
Err(e) if is_timeout(&e) => return Ok(None),
Err(e) => return Err(e.into()),
};
if embeddings.len() != texts.len() {
return Ok(None);
}
let candidate_embeddings = if query_was_cached {
embeddings.as_slice()
} else {
query_embedding.generic = Some(embeddings[0].clone());
&embeddings[1..]
};
let query_emb = query_embedding
.any()
.expect("query embedding was cached or populated from non-empty batch");
Ok(Some(
candidate_embeddings
.iter()
.map(|emb| cosine_similarity(query_emb, emb))
.collect(),
))
}
async fn rerank_with_embeddings(
runtime: &KhiveRuntime,
query: &str,
query_embedding: &mut QueryEmbeddingCache,
hits: &mut [ScoredHit],
alpha: f32,
) -> Result<bool, RuntimeError> {
if hits.is_empty() {
return Ok(false);
}
let texts: Vec<String> = hits
.iter()
.map(|h| format!("{} {}", h.name, h.content.as_deref().unwrap_or("")))
.collect();
if let Some(cosines) = embed_cosine_scores(runtime, query, query_embedding, &texts).await? {
let max_tfidf = hits
.iter()
.map(|h| h.score)
.fold(0.0f32, f32::max)
.max(1e-6);
for (hit, cos) in hits.iter_mut().zip(cosines.iter()) {
let norm_tfidf = hit.score / max_tfidf;
hit.score = alpha * norm_tfidf + (1.0 - alpha) * cos.max(0.0);
hit.provenance.embedding_rerank = true;
}
hits.sort_by(|a, b| {
b.score
.partial_cmp(&a.score)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| a.slug.cmp(&b.slug))
});
return Ok(true);
}
Ok(false)
}
fn cosine_similarity(a: &[f32], b: &[f32]) -> f32 {
if a.len() != b.len() || a.is_empty() {
return 0.0;
}
let mut dot = 0.0f32;
let mut norm_a = 0.0f32;
let mut norm_b = 0.0f32;
for i in 0..a.len() {
dot += a[i] * b[i];
norm_a += a[i] * a[i];
norm_b += b[i] * b[i];
}
let denom = norm_a.sqrt() * norm_b.sqrt();
if denom < 1e-8 {
0.0
} else {
dot / denom
}
}
const HYDRATION_ID_CHUNK: usize = 900;
fn hydrate_atoms_statement(ns: &str, ids: &[String]) -> SqlStatement {
let placeholders = ids
.iter()
.enumerate()
.map(|(i, _)| format!("?{}", i + 2))
.collect::<Vec<_>>()
.join(",");
let mut params = vec![SqlValue::Text(ns.to_owned())];
params.extend(ids.iter().cloned().map(SqlValue::Text));
SqlStatement {
sql: format!(
"SELECT id, slug, name, content, tags, finalized, status FROM knowledge_atoms \
WHERE id IN ({placeholders}) AND +namespace = ?1 AND deleted_at IS NULL"
),
params,
label: None,
}
}
fn hydrate_domains_statement(ns: &str, ids: &[String]) -> SqlStatement {
let placeholders = ids
.iter()
.enumerate()
.map(|(i, _)| format!("?{}", i + 2))
.collect::<Vec<_>>()
.join(",");
let mut params = vec![SqlValue::Text(ns.to_owned())];
params.extend(ids.iter().cloned().map(SqlValue::Text));
SqlStatement {
sql: format!(
"SELECT id, slug, name, description, tags, status FROM knowledge_domains \
WHERE id IN ({placeholders}) AND +namespace = ?1 AND deleted_at IS NULL"
),
params,
label: None,
}
}
fn phase_b_hydration_statement(
ns: &str,
rowids: &[i64],
statuses: &[String],
exclude_statuses: &[&str],
type_clause: &str,
) -> SqlStatement {
let rowid_placeholders = rowids
.iter()
.enumerate()
.map(|(i, _)| format!("?{}", i + 2))
.collect::<Vec<_>>()
.join(",");
let (status_clause, status_params) =
status_sql_clause(statuses, exclude_statuses, 2 + rowids.len());
let mut params = vec![SqlValue::Text(ns.to_owned())];
params.extend(rowids.iter().map(|rowid| SqlValue::Integer(*rowid)));
params.extend(status_params);
SqlStatement {
sql: format!(
"SELECT a.*, a.rowid AS rowid FROM knowledge_atoms AS a \
WHERE a.rowid IN ({rowid_placeholders}) \
AND +a.namespace = ?1 \
AND a.deleted_at IS NULL{status_clause}{type_clause}"
),
params,
label: None,
}
}
async fn hydrate_empty_hits(runtime: &KhiveRuntime, ns: &str, hits: &mut Vec<ScoredHit>) -> usize {
let ids: Vec<String> = hits
.iter()
.filter(|hit| hit.slug.is_empty())
.map(|hit| hit.id.clone())
.collect();
if ids.is_empty() {
return 0;
}
let sql = runtime.sql();
let mut reader = match sql.reader().await {
Ok(r) => r,
Err(error) => {
tracing::warn!(
namespace = ns,
requested = ids.len(),
error = %error,
"knowledge candidate hydration could not acquire a reader"
);
hits.retain(|hit| !hit.slug.is_empty());
return ids.len();
}
};
let mut atom_rows = Vec::new();
for chunk in ids.chunks(HYDRATION_ID_CHUNK) {
match reader.query_all(hydrate_atoms_statement(ns, chunk)).await {
Ok(rows) => atom_rows.extend(rows),
Err(error) => {
tracing::warn!(
namespace = ns,
requested = chunk.len(),
error = %error,
"knowledge atom candidate hydration chunk degraded"
);
}
}
}
let mut atom_rows_by_id: HashMap<String, khive_storage::types::SqlRow> = HashMap::new();
for row in atom_rows {
if let Some(id) = row_str(&row, "id") {
atom_rows_by_id.insert(id, row);
}
}
for hit in hits.iter_mut().filter(|hit| hit.slug.is_empty()) {
if let Some(row) = atom_rows_by_id.get(&hit.id) {
hit.slug = row_str(row, "slug").unwrap_or_default();
hit.name = row_str(row, "name").unwrap_or_default();
hit.content = row_str(row, "content");
hit.tags = row_str(row, "tags");
hit.finalized = row_bool(row, "finalized");
hit.status = row_str(row, "status");
let tags_arr: Vec<String> = hit
.tags
.as_deref()
.and_then(|tags| serde_json::from_str(tags).ok())
.unwrap_or_default();
hit.is_domain = tags_arr.iter().any(|t| t == "type:domain");
}
}
let missing_ids: Vec<String> = hits
.iter()
.filter(|hit| hit.slug.is_empty())
.map(|hit| hit.id.clone())
.collect();
if missing_ids.is_empty() {
return 0;
}
let mut domain_rows = Vec::new();
for chunk in missing_ids.chunks(HYDRATION_ID_CHUNK) {
match reader.query_all(hydrate_domains_statement(ns, chunk)).await {
Ok(rows) => domain_rows.extend(rows),
Err(error) => {
tracing::warn!(
namespace = ns,
requested = chunk.len(),
error = %error,
"knowledge domain candidate hydration chunk degraded"
);
}
}
}
let mut domain_rows_by_id: HashMap<String, khive_storage::types::SqlRow> = HashMap::new();
for row in domain_rows {
if let Some(id) = row_str(&row, "id") {
domain_rows_by_id.insert(id, row);
}
}
for hit in hits.iter_mut().filter(|hit| hit.slug.is_empty()) {
if let Some(row) = domain_rows_by_id.get(&hit.id) {
hit.slug = row_str(row, "slug").unwrap_or_default();
hit.name = row_str(row, "name").unwrap_or_default();
hit.content = row_str(row, "description");
hit.tags = row_str(row, "tags");
hit.finalized = false;
hit.is_domain = true;
hit.status = row_str(row, "status");
}
}
let failed = hits.iter().filter(|hit| hit.slug.is_empty()).count();
hits.retain(|hit| !hit.slug.is_empty());
if failed > 0 {
tracing::warn!(
namespace = ns,
requested = ids.len(),
failed,
"knowledge candidate hydration returned a degraded pool"
);
}
failed
}
fn attach_hydration_degradation(out: &mut Value, hydration_failures: usize) {
if hydration_failures == 0 {
return;
}
if !out
.get("degraded")
.is_some_and(serde_json::Value::is_object)
{
out["degraded"] = json!({});
}
out["degraded"]["hydration_failures"] = json!(hydration_failures);
}
fn attach_lexical_timeout_degradation(out: &mut Value, timeouts: &[LexicalTimeout]) {
if timeouts.is_empty() {
return;
}
if !out
.get("degraded")
.is_some_and(serde_json::Value::is_object)
{
out["degraded"] = json!({});
}
out["degraded"]["lexical_timeout"] = json!(true);
out["degraded"]["lexical_timeout_instrumented"] = json!(true);
if timeouts
.iter()
.any(|detail| detail.bound == LexicalBound::OrderingProbe)
{
out["degraded"]["lexical_ordering_probe_timeout"] = json!(true);
}
let details: Vec<_> = timeouts
.iter()
.filter(|detail| detail.phase.public())
.take(3)
.collect();
if !details.is_empty() {
out["degraded"]["lexical_timeout_details"] = json!(details);
}
}
fn attach_body_lines_timeout_degradation(out: &mut Value) {
if !out
.get("degraded")
.is_some_and(serde_json::Value::is_object)
{
out["degraded"] = json!({});
}
out["degraded"]["body_lines_timeout"] = json!(true);
}
fn attach_member_sizing_timeout_degradation(out: &mut Value, excluded: &[Value]) {
if excluded.is_empty() {
return;
}
if !out
.get("degraded")
.is_some_and(serde_json::Value::is_object)
{
out["degraded"] = json!({});
}
out["degraded"]["member_sizing_timeout"] = json!({
"excluded": excluded,
"note": "no measurement was produced (timeout or missing canonical domain), so these domains \
were withheld from `results` — their cost is unknown and a \
budgeted knowledge.fold selection cannot safely admit an unpriced \
item. Each entry keeps its id/name/rank/score for reference; \
measure size separately before folding one of these in.",
});
}
struct EligibleAnnSearchState {
hits: Vec<ScoredHit>,
availability: AnnAvailability,
hydration_failures: usize,
}
async fn search_eligible_ann_with_refill(
ctx: &SearchCtx<'_>,
token: &NamespaceToken,
ann: &vamana::SharedAnn,
key: &vamana::AnnKey,
query_embedding: &[f32],
target_eligible: usize,
initial_k: usize,
) -> Result<EligibleAnnSearchState, RuntimeError> {
let runtime = ctx.runtime;
let target_eligible = target_eligible.max(1);
let mut request_k = initial_k.max(target_eligible).max(1);
loop {
khive_storage::ensure_request_read_active("knowledge.search")?;
let AnnSearchState {
hits: raw_hits,
availability,
source_exhausted,
} = search_ann_with_warm_wait(runtime, token, ann, key, query_embedding, request_k).await;
let mut seen = HashSet::with_capacity(raw_hits.len());
let mut hits: Vec<ScoredHit> = raw_hits
.into_iter()
.filter(|(id, _)| seen.insert(*id))
.map(|(id, score)| ScoredHit {
id: id.to_string(),
slug: String::new(),
name: String::new(),
content: None,
tags: None,
finalized: false,
is_domain: false,
status: None,
score,
provenance: ScoreProvenance::ann(),
})
.collect();
let hydration_failures = hydrate_empty_hits(runtime, ctx.ns, &mut hits).await;
khive_storage::ensure_request_read_active("knowledge.search")?;
filter_hits_by_status(&mut hits, ctx.statuses, ctx.exclude_statuses);
filter_hits_by_type(&mut hits, ctx.type_filter);
if hits.len() >= target_eligible || source_exhausted {
hits.truncate(target_eligible);
return Ok(EligibleAnnSearchState {
hits,
availability,
hydration_failures,
});
}
let next_k = request_k.saturating_mul(2);
if next_k == request_k {
hits.truncate(target_eligible);
return Ok(EligibleAnnSearchState {
hits,
availability,
hydration_failures,
});
}
request_k = next_k;
}
}
struct CandidateStageOutcome {
ann_hits: Vec<ScoredHit>,
ann_availability: Option<AnnAvailability>,
hydration_failures: usize,
query_embedding: QueryEmbeddingCache,
}
struct CandidateStageOptions {
query_embedding: QueryEmbeddingCache,
ann_target: usize,
ann_initial_k: usize,
operation: &'static str,
}
async fn run_candidate_stages<F>(
ctx: &SearchCtx<'_>,
token: &NamespaceToken,
ann: &vamana::SharedAnn,
raw_query: &str,
options: CandidateStageOptions,
lexical: F,
) -> Result<(SearchCoreOutcome, CandidateStageOutcome), RuntimeError>
where
F: std::future::Future<Output = Result<SearchCoreOutcome, RuntimeError>>,
{
vamana::ensure_ann_background(ctx.runtime, token, ann);
let ann_stage = async {
let mut query_embedding = options.query_embedding;
let mut ann_hits = Vec::new();
let mut ann_availability = None;
let mut hydration_failures = 0;
if query_embedding.role_specific.is_not_attempted() {
query_embedding.role_specific = match khive_storage::await_request_read_phase(
options.operation,
ctx.runtime.embed_query(raw_query),
)
.await
{
Ok(Ok(vector)) => RoleSpecificEmbedding::Vector(vector),
Ok(Err(_)) => RoleSpecificEmbedding::Failed,
Err(error) if is_timeout(&error) => RoleSpecificEmbedding::Failed,
Err(error) => return Err(error.into()),
};
}
if let Some(vector) = query_embedding.role_specific.as_deref() {
let key = vamana::AnnKey::new(ctx.ns, ctx.runtime.default_embedder_name());
match khive_storage::await_request_read_phase(
options.operation,
search_eligible_ann_with_refill(
ctx,
token,
ann,
&key,
vector,
options.ann_target,
options.ann_initial_k,
),
)
.await
{
Ok(Ok(state)) => {
ann_hits = state.hits;
ann_availability = Some(state.availability);
hydration_failures = state.hydration_failures;
}
Ok(Err(error)) if is_read_timeout(&error) => {}
Ok(Err(error)) => return Err(error),
Err(error) if is_timeout(&error) => {}
Err(error) => return Err(error.into()),
}
}
Ok(CandidateStageOutcome {
ann_hits,
ann_availability,
hydration_failures,
query_embedding,
})
};
let (ann_result, lexical_result) = tokio::join!(ann_stage, lexical);
let ann_result = ann_result?;
Ok((lexical_result?, ann_result))
}
struct ScoredTextItem {
id: String,
slug: String,
name: String,
text: String,
score: f32,
}
async fn load_domain_by_id_or_slug(
runtime: &KhiveRuntime,
ns: &str,
id_or_slug: &str,
) -> Result<Domain, RuntimeError> {
let sql = runtime.sql();
let mut reader = sql
.reader()
.await
.map_err(|e| sql_err("compose domain reader", e))?;
let id = id_or_slug.trim().to_string();
let row = if id.parse::<Uuid>().is_ok() {
reader
.query_row(SqlStatement {
sql: "SELECT * FROM knowledge_domains WHERE id = ?1 AND namespace = ?2 AND deleted_at IS NULL LIMIT 1".into(),
params: vec![SqlValue::Text(id.clone()), SqlValue::Text(ns.to_owned())],
label: None,
})
.await
.map_err(|e| sql_err("compose domain by id", e))?
} else {
let by_slug = reader
.query_row(SqlStatement {
sql: "SELECT * FROM knowledge_domains WHERE slug = ?1 AND namespace = ?2 AND deleted_at IS NULL LIMIT 1".into(),
params: vec![SqlValue::Text(id.clone()), SqlValue::Text(ns.to_owned())],
label: None,
})
.await
.map_err(|e| sql_err("compose domain by slug", e))?;
if by_slug.is_some() {
by_slug
} else {
let is_hex = id.len() >= 8
&& id.len() <= 36
&& id.chars().all(|c| c.is_ascii_hexdigit() || c == '-');
if is_hex {
let pattern = format!("{}%", hex_prefix_to_uuid_pattern(&id));
let rows = reader
.query_all(SqlStatement {
sql: "SELECT * FROM knowledge_domains WHERE id LIKE ?1 AND namespace = ?2 AND deleted_at IS NULL LIMIT 2".into(),
params: vec![
SqlValue::Text(pattern),
SqlValue::Text(ns.to_owned()),
],
label: None,
})
.await
.map_err(|e| sql_err("compose domain by prefix", e))?;
if rows.len() > 1 {
return Err(RuntimeError::InvalidInput(format!(
"ambiguous domain prefix {id:?} matches multiple domains"
)));
}
rows.into_iter().next()
} else {
None
}
}
};
row.and_then(|r| domain_from_row(&r))
.ok_or_else(|| RuntimeError::NotFound(format!("domain not found: {id:?}")))
}
async fn load_atom_by_id_or_slug(
runtime: &KhiveRuntime,
ns: &str,
id_or_slug: &str,
) -> Result<Atom, RuntimeError> {
let sql = runtime.sql();
let mut reader = sql
.reader()
.await
.map_err(|e| sql_err("compose atom reader", e))?;
let id = id_or_slug.trim().to_string();
let row = if id.parse::<Uuid>().is_ok() {
reader
.query_row(SqlStatement {
sql: "SELECT * FROM knowledge_atoms WHERE id = ?1 AND namespace = ?2 AND deleted_at IS NULL LIMIT 1".into(),
params: vec![SqlValue::Text(id.clone()), SqlValue::Text(ns.to_owned())],
label: None,
})
.await
.map_err(|e| sql_err("compose atom by id", e))?
} else {
let by_slug = reader
.query_row(SqlStatement {
sql: "SELECT * FROM knowledge_atoms WHERE slug = ?1 AND namespace = ?2 AND deleted_at IS NULL LIMIT 1".into(),
params: vec![SqlValue::Text(id.clone()), SqlValue::Text(ns.to_owned())],
label: None,
})
.await
.map_err(|e| sql_err("compose atom by slug", e))?;
if by_slug.is_some() {
by_slug
} else {
let is_hex = id.len() >= 8
&& id.len() <= 36
&& id.chars().all(|c| c.is_ascii_hexdigit() || c == '-');
if is_hex {
let pattern = format!("{}%", hex_prefix_to_uuid_pattern(&id));
let rows = reader
.query_all(SqlStatement {
sql: "SELECT * FROM knowledge_atoms WHERE id LIKE ?1 AND namespace = ?2 AND deleted_at IS NULL LIMIT 2".into(),
params: vec![
SqlValue::Text(pattern),
SqlValue::Text(ns.to_owned()),
],
label: None,
})
.await
.map_err(|e| sql_err("compose atom by prefix", e))?;
if rows.len() > 1 {
return Err(RuntimeError::InvalidInput(format!(
"ambiguous atom prefix {id:?} matches multiple atoms"
)));
}
rows.into_iter().next()
} else {
None
}
}
};
row.and_then(|r| atom_from_row(&r))
.ok_or_else(|| RuntimeError::NotFound(format!("atom not found: {id:?}")))
}
fn parse_domain_members(domain: &Domain) -> Result<Vec<String>, RuntimeError> {
if domain.members.is_empty() || domain.members == "[]" {
return Ok(Vec::new());
}
serde_json::from_str::<Vec<String>>(&domain.members).map_err(|e| {
RuntimeError::Internal(format!(
"domain {:?} has invalid members JSON: {e}",
domain.slug
))
})
}
#[derive(Debug, Default)]
struct DomainMemberSizing {
tokens: usize,
live_members: usize,
}
async fn load_domain_member_token_sizes(
runtime: &KhiveRuntime,
ns: &str,
domain_ids: &[String],
) -> Result<(HashMap<String, DomainMemberSizing>, bool), RuntimeError> {
let mut sizes: HashMap<String, DomainMemberSizing> = HashMap::new();
if domain_ids.is_empty() {
return Ok((sizes, false));
}
let placeholders = domain_ids
.iter()
.enumerate()
.map(|(i, _)| format!("?{}", i + 2))
.collect::<Vec<_>>()
.join(",");
let mut params = vec![SqlValue::Text(ns.to_owned())];
params.extend(domain_ids.iter().cloned().map(SqlValue::Text));
let sql = runtime.sql();
let mut reader = match sql.reader().await {
Ok(reader) => reader,
Err(e) if is_timeout(&e) => return Ok((sizes, true)),
Err(e) => return Err(sql_err("suggest member size reader", e)),
};
let rows = match reader
.query_all(SqlStatement {
sql: format!(
"SELECT DISTINCT d.id AS domain_id, a.id AS atom_id, a.name, a.content \
FROM knowledge_domains AS d \
LEFT JOIN json_each(d.members) AS member ON 1 = 1 \
LEFT JOIN knowledge_atoms AS a \
ON a.namespace = d.namespace \
AND a.slug = member.value \
AND a.deleted_at IS NULL \
WHERE d.namespace = ?1 \
AND d.id IN ({placeholders}) \
AND d.deleted_at IS NULL"
),
params,
label: None,
})
.await
{
Ok(rows) => rows,
Err(e) if is_timeout(&e) => return Ok((sizes, true)),
Err(e) => return Err(sql_err("suggest member size query", e)),
};
for row in rows {
let Some(domain_id) = row_str(&row, "domain_id") else {
continue;
};
let sizing = sizes.entry(domain_id).or_default();
let Some(content) = row_str(&row, "content") else {
continue;
};
let name = row_str(&row, "name").unwrap_or_default();
sizing.tokens = sizing
.tokens
.saturating_add(estimate_compose_item_tokens(&name, &content));
sizing.live_members = sizing.live_members.saturating_add(1);
}
Ok((sizes, false))
}
async fn load_atom_body_line_counts(
runtime: &KhiveRuntime,
ns: &str,
atom_ids: &[String],
) -> Result<Option<HashMap<String, usize>>, RuntimeError> {
let mut counts: HashMap<String, usize> = atom_ids.iter().map(|id| (id.clone(), 0)).collect();
if atom_ids.is_empty() {
return Ok(Some(counts));
}
let placeholders = atom_ids
.iter()
.enumerate()
.map(|(i, _)| format!("?{}", i + 2))
.collect::<Vec<_>>()
.join(",");
let mut params = vec![SqlValue::Text(ns.to_owned())];
params.extend(atom_ids.iter().cloned().map(SqlValue::Text));
let sql = runtime.sql();
let mut reader = match sql.reader().await {
Ok(reader) => reader,
Err(e) if is_timeout(&e) => return Ok(None),
Err(e) => return Err(sql_err("search body line count reader", e)),
};
let rows = match reader
.query_all(SqlStatement {
sql: format!(
"SELECT atom_id, \
SUM(CASE WHEN content = '' THEN 0 \
ELSE length(content) \
- length(replace(content, char(10), '')) \
+ (CASE WHEN substr(content, -1) = char(10) \
THEN 0 ELSE 1 END) \
END) AS body_lines \
FROM knowledge_sections \
WHERE namespace = ?1 AND atom_id IN ({placeholders}) \
GROUP BY atom_id"
),
params,
label: None,
})
.await
{
Ok(rows) => rows,
Err(e) if is_timeout(&e) => return Ok(None),
Err(e) => return Err(sql_err("search body line count query", e)),
};
for row in rows {
let Some(atom_id) = row_str(&row, "atom_id") else {
continue;
};
let Some(body_lines) = row_i64(&row, "body_lines") else {
continue;
};
if let Ok(body_lines) = usize::try_from(body_lines) {
counts.insert(atom_id, body_lines);
}
}
Ok(Some(counts))
}
async fn rerank_text_items(
runtime: &KhiveRuntime,
query: &str,
query_embedding: &mut QueryEmbeddingCache,
items: &mut [ScoredTextItem],
) -> Result<(), RuntimeError> {
if items.is_empty() {
return Ok(());
}
let texts: Vec<String> = items.iter().map(|item| item.text.clone()).collect();
if let Some(cosines) = embed_cosine_scores(runtime, query, query_embedding, &texts).await? {
for (item, cos) in items.iter_mut().zip(cosines.iter()) {
item.score = cos.max(0.0);
}
items.sort_by(|a, b| {
b.score
.partial_cmp(&a.score)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| a.slug.cmp(&b.slug))
});
}
Ok(())
}
const KG_BLEND_ENTITY_KINDS: [&str; 2] = ["concept", "document"];
const KG_BLEND_CAP: usize = 5;
struct KgEntityHit {
id: String,
kind: String,
name: String,
description: String,
score: f32,
}
async fn search_kg_entities(
runtime: &KhiveRuntime,
token: &NamespaceToken,
ns: &str,
query: &str,
query_embedding: &mut QueryEmbeddingCache,
cap: usize,
min_score: f32,
) -> Result<Vec<KgEntityHit>, RuntimeError> {
let Some(query_vector) = query_embedding.role_specific.as_deref() else {
return Ok(Vec::new());
};
let candidate_k = ((cap * 4) as u32).max(20);
let mut candidate_ids: Vec<Uuid> = Vec::new();
let mut seen: HashSet<Uuid> = HashSet::new();
for kind in KG_BLEND_ENTITY_KINDS {
let hits = runtime
.hybrid_search(
token,
query,
Some(query_vector.to_vec()),
candidate_k,
Some(kind),
None,
&[],
None,
)
.await?;
for hit in hits {
if seen.insert(hit.entity_id) {
candidate_ids.push(hit.entity_id);
}
}
}
if candidate_ids.is_empty() {
return Ok(Vec::new());
}
let visible_ns: Vec<String> = token
.visible_namespace_strs()
.iter()
.map(|s| s.to_string())
.collect();
let entities_page = runtime
.entities(token)?
.query_entities(
ns,
EntityFilter {
ids: candidate_ids.clone(),
kinds: KG_BLEND_ENTITY_KINDS
.iter()
.map(|k| k.to_string())
.collect(),
namespaces: visible_ns,
..EntityFilter::default()
},
PageRequest {
offset: 0,
limit: candidate_ids.len() as u32,
},
)
.await?;
if entities_page.items.is_empty() {
return Ok(Vec::new());
}
let texts: Vec<String> = entities_page
.items
.iter()
.map(|e| format!("{} {}", e.name, e.description.as_deref().unwrap_or("")))
.collect();
let cosines = match embed_cosine_scores(runtime, query, query_embedding, &texts).await? {
Some(c) => c,
None => return Ok(Vec::new()),
};
let mut hits: Vec<KgEntityHit> = entities_page
.items
.iter()
.zip(cosines.iter())
.map(|(e, &score)| KgEntityHit {
id: e.id.to_string(),
kind: e.kind.clone(),
name: e.name.clone(),
description: e.description.clone().unwrap_or_default(),
score: score.max(0.0),
})
.collect();
hits.sort_by(|a, b| {
b.score
.partial_cmp(&a.score)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| a.id.cmp(&b.id))
});
hits.retain(|h| h.score >= min_score);
hits.truncate(cap);
Ok(hits)
}
const KG_ENTITIES_HEADING: &str = "\n---\n\n## Knowledge graph\n\n";
fn format_kg_entity_line(entity: &KgEntityHit) -> String {
let mut line = format!("- **{}** ({})", entity.name, entity.kind);
if !entity.description.is_empty() {
line.push_str(&format!(" — {}", entity.description));
}
line.push('\n');
line
}
fn trim_kg_entities_to_budget(hits: Vec<KgEntityHit>, remaining_budget: usize) -> Vec<KgEntityHit> {
let mut used = 0usize;
hits.into_iter()
.filter(|h| {
let heading = if used == 0 {
KG_ENTITIES_HEADING.len()
} else {
0
};
let cost = heading + format_kg_entity_line(h).len();
if cost > remaining_budget.saturating_sub(used) {
false
} else {
used += cost;
true
}
})
.collect()
}
fn format_kg_entities_markdown(entities: &[KgEntityHit]) -> String {
let mut out = String::from(KG_ENTITIES_HEADING);
for e in entities {
out.push_str(&format_kg_entity_line(e));
}
out
}
fn format_compose_atom_heading(atom: &Atom) -> String {
format!("\n## {}\n\nSource: {}\n", atom.name, atom.slug)
}
fn format_compose_section(section: &super::compose::ComposeSectionResult, explain: bool) -> String {
let mut out = if explain {
format!(
"\n### {} (score: {:.4})\n\n",
section.heading, section.score
)
} else {
format!("\n### {}\n\n", section.heading)
};
if !section.content.is_empty() {
out.push_str(§ion.content);
out.push('\n');
}
out
}
fn format_compose_whole_atom(atom: &Atom, score: f32, explain: bool) -> String {
let mut out = format_compose_atom_heading(atom);
if explain {
out.push_str(&format!("Score: {score:.4}\n"));
}
if !atom.content.is_empty() {
out.push('\n');
out.push_str(&atom.content);
out.push('\n');
}
out
}
fn format_compose_domain_footer(domains: &[Domain]) -> String {
if domains.is_empty() {
return String::new();
}
let names: Vec<&str> = domains.iter().map(|d| d.name.as_str()).collect();
format!("\n---\n\nDomains: {}\n", names.join(", "))
}
struct PackedCompose<'a> {
markdown: String,
sections: Vec<&'a super::compose::ComposeSectionResult>,
included_atom_ids: HashSet<String>,
}
fn pack_compose_markdown<'a>(
query: &str,
domains: &[Domain],
atoms: &'a [Atom],
items: &[ScoredTextItem],
sections: &'a [super::compose::ComposeSectionResult],
explain: bool,
char_budget: usize,
) -> PackedCompose<'a> {
const PREFIX: &str = "# Knowledge Briefing\n\nQuery: ";
let mut footer = format_compose_domain_footer(domains);
if PREFIX.len() + 1 + footer.len() > char_budget {
footer.clear();
}
let query_budget = char_budget - PREFIX.len() - 1 - footer.len();
let mut query_end = query.len().min(query_budget);
while !query.is_char_boundary(query_end) {
query_end -= 1;
}
let mut markdown = format!("{PREFIX}{}\n", &query[..query_end]);
let mut body_used = 0usize;
let body_budget = char_budget - markdown.len() - footer.len();
let by_id: HashMap<String, &Atom> = atoms.iter().map(|a| (a.id.to_string(), a)).collect();
let sectioned_atom_ids: HashSet<&str> = sections.iter().map(|s| s.atom_id.as_str()).collect();
let mut selected_by_atom: HashMap<&str, Vec<&super::compose::ComposeSectionResult>> =
HashMap::new();
let mut selected_sections = Vec::new();
let mut included_atom_ids = HashSet::new();
for section in sections {
let Some(atom) = by_id.get(§ion.atom_id) else {
continue;
};
let atom_header_cost = if selected_by_atom.contains_key(section.atom_id.as_str()) {
0
} else {
format_compose_atom_heading(atom).len()
};
let cost = atom_header_cost + format_compose_section(section, explain).len();
if cost > body_budget.saturating_sub(body_used) {
continue;
}
body_used += cost;
selected_by_atom
.entry(section.atom_id.as_str())
.or_default()
.push(section);
included_atom_ids.insert(section.atom_id.clone());
selected_sections.push(section);
}
let mut whole_atoms = Vec::new();
for item in items {
if !selected_sections.is_empty() && sectioned_atom_ids.contains(item.id.as_str()) {
continue;
}
let Some(atom) = by_id.get(&item.id) else {
continue;
};
let fragment = format_compose_whole_atom(atom, item.score, explain);
if fragment.len() > body_budget.saturating_sub(body_used) {
continue;
}
body_used += fragment.len();
included_atom_ids.insert(item.id.clone());
whole_atoms.push(fragment);
}
for atom in atoms {
let atom_id = atom.id.to_string();
if let Some(secs) = selected_by_atom.get(atom_id.as_str()) {
markdown.push_str(&format_compose_atom_heading(atom));
for section in secs {
markdown.push_str(&format_compose_section(section, explain));
}
}
}
for fragment in whole_atoms {
markdown.push_str(&fragment);
}
markdown.push_str(&footer);
debug_assert_eq!(markdown.len(), char_budget - body_budget + body_used);
PackedCompose {
markdown,
sections: selected_sections,
included_atom_ids,
}
}
#[cfg(test)]
mod compose_packing_tests {
use super::super::compose::{ComposeSectionResult, ScoreBreakdown};
use super::*;
fn atom(number: u128, name: &str, content: String) -> Atom {
Atom {
id: Uuid::from_u128(number),
namespace: "local".into(),
slug: format!("atom-{number}"),
name: name.into(),
content,
tags: "[]".into(),
properties: None,
status: Some("reviewed".into()),
source_uri: None,
source_type: None,
finalized: true,
created_at: 0,
updated_at: 0,
deleted_at: None,
}
}
fn item(atom: &Atom, score: f32) -> ScoredTextItem {
ScoredTextItem {
id: atom.id.to_string(),
slug: atom.slug.clone(),
name: atom.name.clone(),
text: atom.content.clone(),
score,
}
}
fn domain(name: String) -> Domain {
Domain {
id: Uuid::from_u128(999),
namespace: "local".into(),
slug: "test-domain".into(),
name,
description: None,
tags: "[]".into(),
members: "[]".into(),
created_at: 0,
updated_at: 0,
deleted_at: None,
}
}
fn section(atom: &Atom, heading: &str, content: String, score: f32) -> ComposeSectionResult {
ComposeSectionResult {
section_id: Uuid::new_v4().to_string(),
atom_id: atom.id.to_string(),
section_type: "overview".into(),
heading: heading.into(),
content,
score,
score_breakdown: ScoreBreakdown {
section_cosine: score,
section_bm25: 0.0,
atom_cosine: score,
domain_score: 0.0,
type_weight: 0.0,
},
}
}
#[test]
fn actual_markdown_budget_prices_query_domain_and_explain_in_both_modes() {
let query = "q".repeat(300);
let domains = vec![domain("long-domain-".repeat(15))];
let atom = atom(1, "Source Atom", "a".repeat(1_530));
let atoms = vec![atom.clone()];
let items = vec![item(&atom, 0.9)];
let whole = pack_compose_markdown(&query, &domains, &atoms, &items, &[], true, 2_000);
assert!(whole.markdown.len() <= 2_000);
assert!(
whole.included_atom_ids.is_empty(),
"long atom must not overflow"
);
let sections = vec![section(&atom, "Summary", "s".repeat(1_530), 0.9)];
let sectioned =
pack_compose_markdown(&query, &domains, &atoms, &items, §ions, true, 2_000);
assert!(sectioned.markdown.len() <= 2_000);
assert!(
sectioned.sections.is_empty(),
"long section must not overflow"
);
let long_query = "é".repeat(1_500);
let bounded =
pack_compose_markdown(&long_query, &domains, &atoms, &items, &[], false, 2_000);
assert!(bounded.markdown.len() <= 2_000);
assert!(bounded.markdown.is_char_boundary(bounded.markdown.len()));
}
#[test]
fn atom_only_packing_skips_oversized_first_hit_and_keeps_smaller_hits() {
let atoms = vec![
atom(1, "Too Large", "x".repeat(3_000)),
atom(2, "Small Two", "y".repeat(300)),
atom(3, "Small Three", "z".repeat(300)),
];
let items: Vec<_> = atoms
.iter()
.zip([0.9, 0.8, 0.7])
.map(|(a, s)| item(a, s))
.collect();
let packed = pack_compose_markdown("query", &[], &atoms, &items, &[], false, 2_000);
assert!(!packed.markdown.contains("Too Large"));
assert!(packed.markdown.contains("Small Two"));
assert!(packed.markdown.contains("Small Three"));
assert_eq!(packed.included_atom_ids.len(), 2);
}
#[test]
fn mixed_section_and_sectionless_atoms_both_survive() {
let atoms = vec![
atom(1, "Sectioned", "source body".into()),
atom(2, "Sectionless", "whole atom body".into()),
];
let items = vec![item(&atoms[0], 0.9), item(&atoms[1], 0.8)];
let sections = vec![section(&atoms[0], "Overview", "section body".into(), 0.9)];
let packed = pack_compose_markdown("query", &[], &atoms, &items, §ions, true, 2_000);
assert!(packed.markdown.contains("section body"));
assert!(packed.markdown.contains("whole atom body"));
assert_eq!(packed.sections.len(), 1);
assert_eq!(packed.included_atom_ids.len(), 2);
}
#[test]
fn kg_tail_skips_oversized_hit_and_prices_heading_exactly() {
let hits = vec![
KgEntityHit {
id: "large".into(),
kind: "concept".into(),
name: "large".into(),
description: "x".repeat(3_000),
score: 0.9,
},
KgEntityHit {
id: "small".into(),
kind: "concept".into(),
name: "small".into(),
description: "short".into(),
score: 0.8,
},
];
let kept = trim_kg_entities_to_budget(hits, 80);
assert_eq!(kept.len(), 1);
assert_eq!(kept[0].id, "small");
assert!(format_kg_entities_markdown(&kept).len() <= 80);
}
}
impl KnowledgeHandlers {
pub(crate) async fn search(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
ann: &vamana::SharedAnn,
) -> Result<Value, RuntimeError> {
khive_storage::ensure_request_read_active("knowledge.search")?;
let p: SearchParams = deser(params)?;
let raw_query = p.query.trim().to_string();
if raw_query.is_empty() {
return Err(RuntimeError::InvalidInput("query must not be empty".into()));
}
if let Some(ms) = p.min_score {
if !ms.is_finite() {
return Err(RuntimeError::InvalidInput(
"min_score must be a finite number".into(),
));
}
}
if let Some(ib) = p.intersection_bonus {
if !ib.is_finite() {
return Err(RuntimeError::InvalidInput(
"intersection_bonus must be a finite number".into(),
));
}
}
if let Some(ra) = p.rerank_alpha {
if !ra.is_finite() {
return Err(RuntimeError::InvalidInput(
"rerank_alpha must be a finite number".into(),
));
}
}
if let Some(ref w) = p.weights {
let pairs: &[(&str, Option<f64>)] = &[
("w_exact_name", w.w_exact_name),
("w_name", w.w_name),
("w_tags", w.w_tags),
("w_content", w.w_content),
("expand_discount", w.expand_discount),
("coverage_alpha", w.coverage_alpha),
("w_bigram", w.w_bigram),
];
for (name, val) in pairs {
if let Some(v) = val {
if !v.is_finite() {
return Err(RuntimeError::InvalidInput(format!(
"weights.{name} must be a finite number"
)));
}
}
}
}
let limit = p.limit.unwrap_or(10).clamp(1, 100);
let min_score = p.min_score.unwrap_or(0.0) as f32;
let w = Weights::from_opts(&p);
if let Some(kind) = p.kind.as_deref() {
if !matches!(kind, "atom" | "domain") {
return Err(RuntimeError::InvalidInput(format!(
"kind must be one of: atom, domain; got {kind:?}"
)));
}
}
let type_filter = p.kind.as_deref();
let do_decompose = p.decompose.unwrap_or(false);
let decompose_threshold = p.decompose_threshold.unwrap_or(4);
let intersection_bonus = p.intersection_bonus.unwrap_or(0.25) as f32;
let requested_rerank = p.rerank.unwrap_or(true);
let do_rerank = requested_rerank && !runtime.default_embedder_name().is_empty();
let rerank_alpha = p.rerank_alpha.unwrap_or(0.7) as f32;
let fetch_limit = if do_rerank { limit * 3 } else { limit }.min(100);
let non_stop_count = raw_query
.split_whitespace()
.filter(|w| w.len() >= MIN_TERM_LEN && !is_stop(&w.to_lowercase()))
.count();
let ns = token.namespace().as_str().to_owned();
let requested_statuses = status_values(p.status.as_ref());
let exclude_status_normalized: Option<&str> = p
.exclude_status
.as_deref()
.map(str::trim)
.filter(|s| !s.is_empty());
if let Some(status) = exclude_status_normalized {
if !matches!(status, "draft" | "reviewed" | "deprecated") {
return Err(RuntimeError::InvalidInput(format!(
"exclude_status must be one of: draft, reviewed, deprecated; got {status:?}"
)));
}
}
let effective_exclude_statuses: Vec<&str> = if !requested_statuses.is_empty() {
vec![]
} else if let Some(ex) = exclude_status_normalized {
vec![ex]
} else {
let include_drafts = p.include_drafts.unwrap_or(false);
if include_drafts {
vec!["deprecated"]
} else {
vec!["draft", "deprecated"]
}
};
let allow_deprecated =
deprecated_allowed_by_status_policy(&requested_statuses, &effective_exclude_statuses);
let term_budget = FtsTermBudget::new();
let ctx = SearchCtx {
runtime,
ns: &ns,
role: p.role.as_deref(),
type_filter,
min_score,
w: &w,
fetch_limit,
statuses: &requested_statuses,
exclude_statuses: &effective_exclude_statuses,
term_budget: &term_budget,
};
let ann_k = fetch_limit.max(20);
let (
SearchCoreOutcome {
mut hits,
lexical_timeouts,
lexical_state,
},
CandidateStageOutcome {
ann_hits,
ann_availability,
hydration_failures,
mut query_embedding,
},
) = run_candidate_stages(
&ctx,
token,
ann,
&raw_query,
CandidateStageOptions {
query_embedding: QueryEmbeddingCache::default(),
ann_target: ann_k,
ann_initial_k: ann_k,
operation: "knowledge.search",
},
async {
if do_decompose && non_stop_count >= decompose_threshold {
search_decomposed(&ctx, &raw_query, intersection_bonus).await
} else {
search_core(&ctx, &raw_query, LexicalPass::Full).await
}
},
)
.await?;
let mut ann_unavailable = false;
if !ann_hits.is_empty() {
fuse_ann_hits(&mut hits, &ann_hits, min_score);
}
if matches!(
ann_availability,
Some(AnnAvailability::WarmingTimedOut {
corpus_non_empty: true
})
) && hits.is_empty()
{
ann_unavailable = true;
}
filter_hits_by_status(&mut hits, &requested_statuses, &effective_exclude_statuses);
filter_hits_by_type(&mut hits, type_filter);
if do_rerank && !hits.is_empty() && !khive_storage::request_read_is_cancelled() {
rerank_with_embeddings(
runtime,
&raw_query,
&mut query_embedding,
&mut hits,
rerank_alpha,
)
.await?;
}
apply_status_multipliers(&mut hits, allow_deprecated);
enforce_min_score_floor(&mut hits, min_score);
hits.truncate(limit);
let atom_ids: Vec<String> = hits
.iter()
.filter(|hit| !hit.is_domain)
.map(|hit| hit.id.clone())
.collect();
let mut body_lines_timed_out = false;
let body_line_counts = if khive_storage::request_read_is_cancelled() {
None
} else {
match load_atom_body_line_counts(runtime, &ns, &atom_ids).await? {
Some(counts) => Some(counts),
None => {
body_lines_timed_out = true;
None
}
}
};
let results: Vec<Value> = hits
.iter()
.map(|h| {
let body_lines = if h.is_domain {
None
} else {
body_line_counts
.as_ref()
.and_then(|counts| counts.get(&h.id).copied())
};
json!({
"id": h.id,
"slug": h.slug,
"name": h.name,
"content": h.content,
"body_lines": body_lines,
"tags": h.tags,
"status": h.status,
"finalized": h.finalized,
"kind": if h.is_domain { "domain" } else { "atom" },
"score": h.score,
"score_provenance": h.provenance.to_json(),
})
})
.collect();
let count = results.len();
let mut out = json!({
"results": results,
"total": count,
"candidate_provenance": {
"lexical": lexical_state.as_str(),
"fallback": candidate_fallback(&hits),
"terms_truncated": term_budget.truncated(),
},
});
if ann_unavailable {
out["ann_unavailable"] = json!(true);
}
attach_lexical_timeout_degradation(&mut out, &lexical_timeouts);
if body_lines_timed_out {
attach_body_lines_timeout_degradation(&mut out);
}
attach_hydration_degradation(&mut out, hydration_failures);
if !khive_storage::request_read_is_cancelled() {
khive_storage::ensure_request_read_active("knowledge.search")?;
}
Ok(out)
}
pub(crate) async fn suggest(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
ann: &vamana::SharedAnn,
) -> Result<Value, RuntimeError> {
let (out, _) = Self::suggest_with_query_embedding(
runtime,
token,
params,
ann,
QueryEmbeddingCache::default(),
)
.await?;
Ok(out)
}
async fn suggest_with_query_embedding(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
ann: &vamana::SharedAnn,
query_embedding: QueryEmbeddingCache,
) -> Result<(Value, QueryEmbeddingCache), RuntimeError> {
khive_storage::ensure_request_read_active("knowledge.suggest")?;
let p: SuggestParams = deser(params)?;
let raw_query = p.query.trim().to_string();
if raw_query.is_empty() {
return Err(RuntimeError::InvalidInput("query must not be empty".into()));
}
let word_count = raw_query.split_whitespace().count();
if word_count < 5 {
return Err(RuntimeError::InvalidInput(format!(
"suggest query must be at least 5 words for meaningful domain matching \
(got {word_count}). Use knowledge.search for short keyword queries."
)));
}
let limit = p.limit.unwrap_or(8).clamp(1, 100);
let ns = token.namespace().as_str().to_owned();
const SUGGEST_EXCLUDE: &[&str] = &["draft", "deprecated"];
let term_budget = FtsTermBudget::new();
let ctx = SearchCtx {
runtime,
ns: &ns,
role: p.role.as_deref(),
type_filter: Some("domain"),
min_score: 0.0,
w: &Weights::default(),
fetch_limit: limit * 3,
statuses: &[],
exclude_statuses: SUGGEST_EXCLUDE,
term_budget: &term_budget,
};
let ann_k = (limit * 50).max(200);
let (
SearchCoreOutcome {
mut hits,
lexical_timeouts,
..
},
CandidateStageOutcome {
ann_hits,
ann_availability,
hydration_failures,
mut query_embedding,
},
) = run_candidate_stages(
&ctx,
token,
ann,
&raw_query,
CandidateStageOptions {
query_embedding,
ann_target: ctx.fetch_limit,
ann_initial_k: ann_k,
operation: "knowledge.suggest",
},
search_core(&ctx, &raw_query, LexicalPass::Full),
)
.await?;
let mut ann_unavailable = false;
if !ann_hits.is_empty() {
fuse_ann_hits(&mut hits, &ann_hits, 0.0);
}
if let Some(AnnAvailability::WarmingTimedOut { corpus_non_empty }) = ann_availability {
ann_unavailable = corpus_non_empty;
}
filter_hits_by_status(&mut hits, &[], SUGGEST_EXCLUDE);
filter_hits_by_type(&mut hits, Some("domain"));
let fresh_rerank_applied = if khive_storage::request_read_is_cancelled() {
false
} else {
rerank_with_embeddings(
runtime,
&raw_query,
&mut query_embedding,
&mut hits,
D_SUGGEST_RERANK_ALPHA,
)
.await?
};
hits.retain(|h| h.is_domain);
hits.truncate(limit);
let domain_ids: Vec<String> = hits.iter().map(|h| h.id.clone()).collect();
let (member_token_sizes, member_sizing_timed_out) =
if khive_storage::request_read_is_cancelled() {
(HashMap::new(), !domain_ids.is_empty())
} else {
#[cfg(test)]
let measured = if MEMBER_SIZING_READ_TIMEOUT.try_with(|_| ()).is_ok() {
khive_storage::scope_request_read_deadline(
std::time::Duration::ZERO,
load_domain_member_token_sizes(runtime, &ns, &domain_ids),
)
.await
} else {
load_domain_member_token_sizes(runtime, &ns, &domain_ids).await
};
#[cfg(not(test))]
let measured = load_domain_member_token_sizes(runtime, &ns, &domain_ids).await;
measured?
};
if !khive_storage::request_read_is_cancelled() {
khive_storage::ensure_request_read_active("knowledge.suggest")?;
}
let unmeasured_domain_ids: HashSet<&str> = domain_ids
.iter()
.map(String::as_str)
.filter(|id| member_sizing_timed_out || !member_token_sizes.contains_key(*id))
.collect();
let results: Vec<Value> = hits
.iter()
.filter(|h| !unmeasured_domain_ids.contains(h.id.as_str()))
.filter_map(|h| {
let sizing = member_token_sizes.get(&h.id)?;
Some(json!({
"id": h.id,
"name": h.name,
"score": h.score,
"size": sizing.tokens,
"members": sizing.live_members,
}))
})
.collect();
let count = results.len();
let excluded: Vec<Value> = hits
.iter()
.enumerate()
.filter(|(_, h)| unmeasured_domain_ids.contains(h.id.as_str()))
.map(|(i, h)| {
json!({
"id": h.id,
"name": h.name,
"rank": i + 1,
"score": h.score,
})
})
.collect();
let mut out = json!({ "results": results, "total": count });
if ann_unavailable {
out["ann_unavailable"] = json!(true);
let (mode, note): (&str, &str) = match (count, fresh_rerank_applied) {
(0, _) => (
"no_match",
"ANN index unavailable and lexical/FTS matching also found no \
domain for this query. This does NOT confirm the corpus has \
nothing relevant — only that this call could not find one. \
Do not cache as an absence; retry once the index is healthy.",
),
(_, true) => (
"ann_candidates_degraded",
"ANN index unavailable: candidate retrieval used lexical/FTS \
matching, but fresh embedding cosine reranking was applied to \
those candidates. Final ranking includes a dense signal, while \
topically relevant domains outside the lexical candidate set may \
still be missing. Do not cache; retry once the index is healthy.",
),
(_, false) => (
"lexical_only",
"ANN index unavailable and fresh embedding reranking did not run: \
these results were ranked by lexical/FTS matching only. Ranking \
may be less precise than a healthy call, and topically relevant \
domains outside the lexical match may be missing. Do not cache; \
retry once the index is healthy.",
),
};
out["degraded"] = json!({
"reason": "ann_unavailable",
"mode": mode,
"cache_safe": false,
"note": note,
});
}
attach_lexical_timeout_degradation(&mut out, &lexical_timeouts);
attach_hydration_degradation(&mut out, hydration_failures);
attach_member_sizing_timeout_degradation(&mut out, &excluded);
if !khive_storage::request_read_is_cancelled() {
khive_storage::ensure_request_read_active("knowledge.suggest")?;
}
Ok((out, query_embedding))
}
pub(crate) async fn compose(
runtime: &KhiveRuntime,
token: &NamespaceToken,
params: Value,
ann: &vamana::SharedAnn,
type_weights: HashMap<String, f32>,
) -> Result<Value, RuntimeError> {
let p: ComposeParams = deser(params)?;
let effective_token = match p.namespace.as_deref() {
Some(ns_str) => {
let ns = Namespace::parse(ns_str).map_err(|e| {
RuntimeError::InvalidInput(format!("invalid namespace {ns_str:?}: {e}"))
})?;
if &ns != token.namespace() {
return Err(RuntimeError::InvalidInput(
"knowledge.compose namespace does not match authorized token namespace"
.to_string(),
));
}
token.with_namespace(ns)
}
None => token.clone(),
};
let token = &effective_token;
let raw_query = p.query.trim().to_string();
if raw_query.is_empty() {
return Err(RuntimeError::InvalidInput("query must not be empty".into()));
}
let explain = p.explain.unwrap_or(false);
let mut domain_ids: Vec<String> = p
.domain_ids
.unwrap_or_default()
.into_iter()
.filter(|s| !s.trim().is_empty())
.collect();
let atom_ids: Vec<String> = p
.atom_ids
.unwrap_or_default()
.into_iter()
.filter(|s| !s.trim().is_empty())
.collect();
let is_auto = domain_ids.is_empty() && atom_ids.is_empty();
let atom_ids_only = domain_ids.is_empty() && !atom_ids.is_empty();
let blend_kg = p.blend_kg.unwrap_or(true) && !atom_ids_only;
let mut suggest_ann_unavailable = false;
let mut suggest_hydration_failures = 0usize;
let mut query_embedding = QueryEmbeddingCache::default();
if is_auto {
let word_count = raw_query.split_whitespace().count();
if word_count < 10 {
return Err(RuntimeError::InvalidInput(format!(
"auto-compose query must be at least 10 words for effective domain selection \
(got {word_count}). Provide explicit domain_ids/atom_ids for shorter queries."
)));
}
}
use super::compose::Phase;
let mut timing = super::compose::ComposeTiming::start(&raw_query, is_auto);
macro_rules! try_or_finish {
($e:expr) => {
match $e {
Ok(v) => v,
Err(e) => {
timing.finish(0);
return Err(e.into());
}
}
};
}
try_or_finish!(timing.begin(Phase::Suggest));
if is_auto {
let auto_limit = p.auto_limit.unwrap_or(5).clamp(1, 20);
let suggest_attempt = Self::suggest_with_query_embedding(
runtime,
token,
json!({ "query": &raw_query, "limit": auto_limit }),
ann,
std::mem::take(&mut query_embedding),
)
.await;
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
let suggest_result = match suggest_attempt {
Ok((v, reused_query_embedding)) => {
query_embedding = reused_query_embedding;
suggest_ann_unavailable = v
.get("ann_unavailable")
.and_then(|f| f.as_bool())
.unwrap_or(false);
suggest_hydration_failures = v
.pointer("/degraded/hydration_failures")
.and_then(Value::as_u64)
.and_then(|count| usize::try_from(count).ok())
.unwrap_or(0);
v
}
Err(e) => {
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
tracing::warn!(error = %e, "auto-compose: internal suggest failed, returning empty");
let response = json!({
"status": "ok",
"data": {
"query": raw_query,
"markdown": "# Knowledge Briefing\n\nDomain suggestion unavailable.",
"domains": [],
"atoms": [],
"count": 0,
"suggest_error": e.to_string(),
},
});
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
timing.finish(0);
return Ok(response);
}
};
if let Some(results) = suggest_result.get("results").and_then(|v| v.as_array()) {
for r in results.iter().filter(|r| r["members"] != 0) {
if let Some(id) = r.get("id").and_then(|v| v.as_str()) {
domain_ids.push(id.to_string());
}
}
}
if domain_ids.is_empty() {
let mut data = json!({
"query": raw_query,
"markdown": "# Knowledge Briefing\n\nNo matching domains found for auto-suggest.",
"domains": [],
"atoms": [],
"count": 0,
});
if suggest_ann_unavailable {
data["ann_unavailable"] = json!(true);
}
attach_hydration_degradation(&mut data, suggest_hydration_failures);
let response = json!({ "status": "ok", "data": data });
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
timing.finish(0);
return Ok(response);
}
}
try_or_finish!(timing.begin(Phase::Fetch));
let ns = token.namespace().as_str().to_owned();
let mut resolved_domains: Vec<Domain> = Vec::new();
let mut member_slugs: Vec<String> = Vec::new();
for id in &domain_ids {
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
let domain = try_or_finish!(load_domain_by_id_or_slug(runtime, &ns, id).await);
let members = try_or_finish!(parse_domain_members(&domain));
member_slugs.extend(members);
resolved_domains.push(domain);
}
let mut seen_ids: HashSet<String> = HashSet::new();
let mut ordered_atoms: Vec<Atom> = Vec::new();
let mut omitted_members: Vec<String> = Vec::new();
for slug in &member_slugs {
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
let atom = match load_atom_by_id_or_slug(runtime, &ns, slug).await {
Ok(atom) => atom,
Err(RuntimeError::NotFound(_)) => {
omitted_members.push(slug.clone());
continue;
}
Err(e) => {
timing.finish(0);
return Err(e);
}
};
if seen_ids.insert(atom.id.to_string()) {
ordered_atoms.push(atom);
}
}
for id in &atom_ids {
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
let atom = try_or_finish!(load_atom_by_id_or_slug(runtime, &ns, id).await);
if seen_ids.insert(atom.id.to_string()) {
ordered_atoms.push(atom);
}
}
if is_auto {
const COMPOSE_EXCLUDE: &[&str] = &["draft", "deprecated"];
ordered_atoms.retain(|a| {
let status = a.status.as_deref().unwrap_or("");
!COMPOSE_EXCLUDE.contains(&status)
});
}
if ordered_atoms.is_empty() {
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
let mut data = json!({
"query": raw_query,
"markdown": "# Knowledge Briefing\n\nNo atoms found.",
"domains": [],
"atoms": [],
"count": 0,
});
if suggest_ann_unavailable {
data["ann_unavailable"] = json!(true);
}
if !omitted_members.is_empty() {
data["omissions"] = json!(omitted_members);
}
attach_hydration_degradation(&mut data, suggest_hydration_failures);
let response = json!({ "status": "ok", "data": data });
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
timing.finish(0);
return Ok(response);
}
let mut items: Vec<ScoredTextItem> = ordered_atoms
.iter()
.map(|a| ScoredTextItem {
id: a.id.to_string(),
slug: a.slug.clone(),
name: a.name.clone(),
text: atom_embed_text(a),
score: 1.0,
})
.collect();
try_or_finish!(timing.begin(Phase::Rerank));
if blend_kg
&& query_embedding.role_specific.is_not_attempted()
&& !runtime.default_embedder_name().is_empty()
{
let embedded = try_or_finish!(
khive_storage::await_request_read_phase(
"knowledge.compose",
runtime.embed_query(&raw_query),
)
.await
);
query_embedding.role_specific = match embedded {
Ok(v) => RoleSpecificEmbedding::Vector(v),
Err(_) => RoleSpecificEmbedding::Failed,
};
}
try_or_finish!(
rerank_text_items(runtime, &raw_query, &mut query_embedding, &mut items,).await
);
let atom_ids: Vec<String> = ordered_atoms.iter().map(|a| a.id.to_string()).collect();
let atom_cosine_scores: HashMap<String, f32> = items
.iter()
.map(|item| (item.id.clone(), item.score))
.collect();
try_or_finish!(timing.begin(Phase::Fetch));
let section_map =
try_or_finish!(super::compose::load_sections(runtime, &ns, &atom_ids).await);
let has_sections = !section_map.is_empty();
try_or_finish!(timing.begin(Phase::Rerank));
let section_results = if has_sections {
let domain_member_ids: HashSet<String> = member_slugs
.iter()
.filter_map(|slug| {
ordered_atoms
.iter()
.find(|a| a.slug == *slug)
.map(|a| a.id.to_string())
})
.collect();
let domain_scores: HashMap<String, f32> = ordered_atoms
.iter()
.map(|a| {
let id = a.id.to_string();
let score = if domain_member_ids.contains(&id) {
1.0
} else {
0.0
};
(id, score)
})
.collect();
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
if let Some(qe) = query_embedding.any() {
try_or_finish!(super::compose::score_sections(
&raw_query,
qe,
&atom_cosine_scores,
§ion_map,
&domain_scores,
&type_weights,
&super::compose::ComposeScoreWeights::default(),
))
} else {
Vec::new()
}
} else {
Vec::new()
};
try_or_finish!(timing.begin(Phase::Trim));
let max_tokens = p.max_tokens.unwrap_or(8000).clamp(500, 100_000);
let char_budget = max_tokens * CHARS_PER_TOKEN;
let packed = pack_compose_markdown(
&raw_query,
&resolved_domains,
&ordered_atoms,
&items,
§ion_results,
explain,
char_budget,
);
let section_json: Vec<Value> = if explain {
packed
.sections
.iter()
.map(|s| {
json!({
"section_id": s.section_id,
"atom_id": s.atom_id,
"section_type": s.section_type,
"heading": s.heading,
"score": (s.score * 10000.0).round() / 10000.0,
"breakdown": {
"section_cosine": (s.score_breakdown.section_cosine * 10000.0).round() / 10000.0,
"section_bm25": (s.score_breakdown.section_bm25 * 10000.0).round() / 10000.0,
"atom_cosine": (s.score_breakdown.atom_cosine * 10000.0).round() / 10000.0,
"domain_score": (s.score_breakdown.domain_score * 10000.0).round() / 10000.0,
"type_weight": (s.score_breakdown.type_weight * 10000.0).round() / 10000.0,
},
})
})
.collect()
} else {
Vec::new()
};
let entity_score_floor: Option<f32> = packed
.included_atom_ids
.iter()
.filter_map(|id| atom_cosine_scores.get(id).copied())
.fold(None, |acc, s| Some(acc.map_or(s, |a: f32| a.min(s))));
let mut markdown = packed.markdown;
let mut kg_entities_json: Vec<Value> = Vec::new();
if blend_kg {
if let Some(floor) = entity_score_floor {
match search_kg_entities(
&runtime.core(),
token,
&ns,
&raw_query,
&mut query_embedding,
KG_BLEND_CAP,
floor,
)
.await
{
Ok(kg_hits) => {
let remaining_budget = char_budget.saturating_sub(markdown.len());
let kg_hits = trim_kg_entities_to_budget(kg_hits, remaining_budget);
if !kg_hits.is_empty() {
let kg_markdown = format_kg_entities_markdown(&kg_hits);
if kg_markdown.len() <= remaining_budget {
markdown.push_str(&kg_markdown);
kg_entities_json = kg_hits
.iter()
.map(|e| {
json!({
"id": e.id,
"kind": e.kind,
"name": e.name,
"score": (e.score * 10000.0).round() / 10000.0,
})
})
.collect();
}
}
}
Err(e) => {
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
tracing::warn!(
error = %e,
"knowledge.compose: KG entity blend failed, continuing with atom-only response"
);
}
}
}
}
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
let atom_json: Vec<Value> = items
.iter()
.filter(|item| packed.included_atom_ids.contains(&item.id))
.map(|item| {
json!({
"id": item.id,
"slug": item.slug,
"name": item.name,
"score": (item.score * 10000.0).round() / 10000.0,
})
})
.collect();
let domain_json: Vec<Value> = resolved_domains
.iter()
.map(|d| json!({ "id": d.id.to_string(), "slug": d.slug, "name": d.name }))
.collect();
let count = atom_json.len();
let mut data = json!({
"query": raw_query,
"markdown": markdown,
"domains": domain_json,
"atoms": atom_json,
"count": count,
});
if explain && !section_json.is_empty() {
data["sections"] = json!(section_json);
data["section_count"] = json!(section_json.len());
}
if !kg_entities_json.is_empty() {
data["entities"] = json!(kg_entities_json);
}
if suggest_ann_unavailable {
data["ann_unavailable"] = json!(true);
}
if !omitted_members.is_empty() {
data["omissions"] = json!(omitted_members);
}
attach_hydration_degradation(&mut data, suggest_hydration_failures);
let response = json!({
"status": "ok",
"data": data,
});
try_or_finish!(khive_storage::ensure_request_read_active(
"knowledge.compose"
));
timing.finish(count);
Ok(response)
}
}
#[cfg(test)]
pub(crate) async fn seed_low_overlap_corpus(runtime: &KhiveRuntime, n: u32, vocab_size: u32) {
let y_stride: u32 = 100;
assert_eq!(
n % y_stride,
0,
"seed_low_overlap_corpus requires n a multiple of 100"
);
let x_max = n / y_stride - 1;
let y_max = y_stride - 1;
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: format!(
"WITH RECURSIVE x(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM x WHERE n < {x_max} \
), y(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM y WHERE n < {y_max} \
) \
INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) \
SELECT \
printf('80000000-0000-0000-0000-%012d', x.n * {y_stride} + y.n), \
'local', printf('lowoverlap-%06d', x.n * {y_stride} + y.n), \
printf('Low Overlap %06d', x.n * {y_stride} + y.n), \
'synthetic corpus content entry ' || (x.n * {y_stride} + y.n) || \
' discusses topic term' || ((x.n * {y_stride} + y.n) % {vocab_size}) || \
' with padding context sentence for realistic length and additional filler', \
'[]', NULL, 1, 'reviewed', NULL, NULL, \
x.n * {y_stride} + y.n, x.n * {y_stride} + y.n, NULL \
FROM x CROSS JOIN y WHERE x.n * {y_stride} + y.n < {n}"
),
params: Vec::new(),
label: None,
})
.await
.expect("seed low-overlap corpus");
}
#[cfg(test)]
#[path = "lexical_timeout_tests.rs"]
mod lexical_timeout_tests;
#[cfg(test)]
mod tests {
use super::*;
use khive_storage::types::{SqlRow, StorageResult};
use std::sync::{Arc, Mutex};
tokio::task_local! {
static TERM_PROBES: Arc<Mutex<Vec<SqlStatement>>>;
}
struct TermRecordingReader {
inner: Box<dyn khive_storage::SqlReader>,
probes: Arc<Mutex<Vec<SqlStatement>>>,
}
impl TermRecordingReader {
fn record(&self, statement: &SqlStatement) {
if statement.sql.contains("fts_knowledge MATCH") {
self.probes
.lock()
.expect("term probes")
.push(statement.clone());
}
}
}
#[async_trait::async_trait]
impl khive_storage::SqlReader for TermRecordingReader {
async fn query_row(&mut self, statement: SqlStatement) -> StorageResult<Option<SqlRow>> {
self.record(&statement);
self.inner.query_row(statement).await
}
async fn query_all(&mut self, statement: SqlStatement) -> StorageResult<Vec<SqlRow>> {
self.record(&statement);
self.inner.query_all(statement).await
}
async fn query_scalar(
&mut self,
statement: SqlStatement,
) -> StorageResult<Option<SqlValue>> {
self.record(&statement);
self.inner.query_scalar(statement).await
}
async fn explain(&mut self, statement: SqlStatement) -> StorageResult<Vec<SqlRow>> {
self.inner.explain(statement).await
}
}
pub(super) fn record_term_probes(
inner: Box<dyn khive_storage::SqlReader>,
) -> Box<dyn khive_storage::SqlReader> {
match TERM_PROBES.try_with(Arc::clone) {
Ok(probes) => Box::new(TermRecordingReader { inner, probes }),
Err(_) => inner,
}
}
fn distinct_term_query(count: usize) -> String {
(0..count)
.map(|index| format!("distinctterm{index}"))
.collect::<Vec<_>>()
.join(" ")
}
fn probed_term(statement: &SqlStatement) -> &str {
match &statement.params[0] {
SqlValue::Text(term) => term,
other => panic!("expected bound FTS term, got {other:?}"),
}
}
#[tokio::test]
async fn distinct_term_fan_out_is_bounded_and_reports_truncation() {
let runtime = KhiveRuntime::memory().expect("runtime");
let token = runtime.authorize(Namespace::local()).expect("token");
for query in [
distinct_term_query(FTS_TERM_COUNT_LIMIT * 2),
"alpha beta gamma".into(),
] {
let terms = fts5_candidate_terms(&query);
let probes = Arc::new(Mutex::new(Vec::new()));
let response = TERM_PROBES
.scope(
probes.clone(),
KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": query, "rerank": false}),
&vamana::new_shared(),
),
)
.await
.expect("bounded search");
let probes = probes.lock().expect("term probes");
assert_eq!(probes.len(), terms.len().min(FTS_TERM_COUNT_LIMIT));
assert_eq!(
probes.iter().map(probed_term).collect::<Vec<_>>(),
terms
.iter()
.take(FTS_TERM_COUNT_LIMIT)
.map(String::as_str)
.collect::<Vec<_>>(),
"admission must precede even the rarity-frequency probes"
);
assert_eq!(
response["candidate_provenance"]["terms_truncated"],
terms.len() > FTS_TERM_COUNT_LIMIT
);
assert_eq!(response["candidate_provenance"]["lexical"], "no_match");
}
}
#[tokio::test]
async fn term_budget_is_shared_across_decomposed_sub_queries() {
let runtime = KhiveRuntime::memory().expect("runtime");
let token = runtime.authorize(Namespace::local()).expect("token");
for count in [10, FTS_TERM_COUNT_LIMIT + 18] {
let probes = Arc::new(Mutex::new(Vec::new()));
let response = TERM_PROBES.scope(probes.clone(), KnowledgeHandlers::search(
&runtime, &token,
json!({"query": distinct_term_query(count), "decompose": true, "rerank": false}),
&vamana::new_shared(),
)).await.expect("decomposed bounded search");
assert_eq!(
probes.lock().expect("term probes").len(),
FTS_TERM_COUNT_LIMIT
);
assert_eq!(response["candidate_provenance"]["terms_truncated"], true);
}
}
#[tokio::test]
async fn term_bound_covers_staged_fallback_and_namespace_probes() {
let runtime = KhiveRuntime::memory().expect("runtime");
let query = distinct_term_query(FTS_TERM_COUNT_LIMIT * 2);
let terms = fts5_candidate_terms(&query);
let content = terms
.iter()
.map(|term| term.trim_matches('"'))
.collect::<Vec<_>>()
.join(" ");
let sql = runtime.sql();
let mut writer = sql.writer().await.expect("writer");
for index in 0..4 {
let (namespace, content) = if index < 3 {
("foreign", content.as_str())
} else {
("local", terms.last().unwrap().trim_matches('"'))
};
writer.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms (id, namespace, slug, name, content, tags, finalized, status, created_at, updated_at) VALUES (?1, ?2, ?3, ?3, ?4, '[]', 1, 'reviewed', 0, 0)".into(),
params: vec![
SqlValue::Text(Uuid::new_v4().to_string()),
SqlValue::Text(namespace.into()),
SqlValue::Text(format!("term-bound-{index}")),
SqlValue::Text(content.into()),
],
label: None,
}).await.expect("seed bounded-stage fixture");
}
drop(writer);
let budget = FtsTermBudget::new();
let probes = Arc::new(Mutex::new(Vec::new()));
let outcome = TERM_PROBES
.scope(
probes.clone(),
with_phase_a_widen_ceiling_override(
2,
super::fetch_fts_candidates(
&runtime,
"local",
&query,
None,
&[],
&[],
5,
&budget,
LexicalStage::new(
LexicalPass::Full,
tokio::time::Instant::now(),
lexical_stage_budget(),
),
),
),
)
.await
.expect("bounded staged fetch");
assert_eq!(outcome.state, LexicalCandidateState::NoMatch);
assert!(outcome.atoms.is_empty() && outcome.timeout.is_none());
assert!(budget.truncated());
let probes = probes.lock().expect("term probes");
let allowed: HashSet<_> = terms
.iter()
.take(FTS_TERM_COUNT_LIMIT)
.map(String::as_str)
.collect();
assert!(probes
.iter()
.all(|statement| allowed.contains(probed_term(statement))));
assert_eq!(
probes
.iter()
.filter(|statement| statement.sql.starts_with("SELECT rowid"))
.count(),
FTS_TERM_COUNT_LIMIT
);
assert_eq!(
probes
.iter()
.filter(|statement| statement.sql.starts_with("SELECT count(*) AS frequency"))
.count(),
FTS_TERM_COUNT_LIMIT
);
assert_eq!(
probes
.iter()
.filter(|statement| statement.sql.starts_with("SELECT a.*"))
.count(),
FTS_TERM_COUNT_LIMIT
);
assert_eq!(
probes
.iter()
.filter(|statement| statement
.sql
.starts_with("SELECT 1 AS present FROM fts_knowledge"))
.count(),
FTS_TERM_COUNT_LIMIT
);
}
#[test]
fn lexical_candidate_state_merge_preserves_completed_and_timed_out_passes() {
use LexicalCandidateState::*;
for (states, expected) in [
(vec![], NoMatch),
(vec![NoMatch, NoMatch], NoMatch),
(vec![NoMatch, Filtered], Filtered),
(vec![Filtered, Matched], Matched),
(vec![TimedOut, TimedOut], TimedOut),
(vec![TimedOut, NoMatch], PartialTimeout),
(vec![Matched, TimedOut], PartialTimeout),
(vec![PartialTimeout, Matched], PartialTimeout),
] {
assert_eq!(
LexicalCandidateState::merge(&states),
expected,
"{states:?}"
);
let reversed: Vec<_> = states.into_iter().rev().collect();
assert_eq!(LexicalCandidateState::merge(&reversed), expected);
}
}
async fn seed_candidate_state_fixture(runtime: &KhiveRuntime) {
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms \
(id, namespace, slug, name, content, tags, finalized, status, created_at, updated_at) \
VALUES \
('92700000-0000-0000-0000-000000000001', 'local', 'newest-unrelated', \
'Newest Unrelated', 'ordinary background content', '[]', 1, 'reviewed', 20, 20), \
('92700000-0000-0000-0000-000000000002', 'local', 'filtered-match', \
'Filtered Match', 'zzfilteredzz', '[]', 0, 'draft', 10, 10)".into(),
params: Vec::new(),
label: None,
}).await.expect("seed candidate state rows");
}
#[tokio::test]
async fn true_lexical_miss_does_not_return_newest_rows() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
seed_candidate_state_fixture(&runtime).await;
let query = "zzgenuinelyabsentzz";
let outcome = fetch_fts_candidates(&runtime, "local", query, None, &[], &[], 5)
.await
.expect("true lexical miss");
assert!(
outcome.atoms.is_empty(),
"a true FTS miss must not return recent rows"
);
assert_eq!(outcome.state, LexicalCandidateState::NoMatch);
assert!(outcome.timeout.is_none());
let token = runtime.authorize(Namespace::local()).expect("local token");
let response = KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": query, "rerank": false}),
&vamana::new_shared(),
)
.await
.expect("public search");
assert_eq!(
response,
json!({
"results": [], "total": 0,
"candidate_provenance": {"lexical": "no_match", "fallback": "none", "terms_truncated": false},
})
);
let lexical = KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "ordinary", "rerank": false}),
&vamana::new_shared(),
)
.await
.expect("matching lexical control");
assert_eq!(
lexical["candidate_provenance"],
json!({"lexical": "matched", "fallback": "none", "terms_truncated": false})
);
assert_eq!(lexical["results"][0]["slug"], "newest-unrelated");
assert_eq!(
lexical["results"][0]["score_provenance"],
json!({
"sources": ["lexical"], "embedding_rerank": false,
"normalization": "s_over_s_plus_1", "calibrated": false,
})
);
}
#[tokio::test]
async fn lexical_candidate_state_distinguishes_filtered_match() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
seed_candidate_state_fixture(&runtime).await;
let token = runtime.authorize(Namespace::local()).expect("local token");
let ann = vamana::new_shared();
for (include_drafts, state, total) in [(false, "filtered", 0), (true, "matched", 1)] {
let response = KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "zzfilteredzz", "rerank": false, "include_drafts": include_drafts}),
&ann,
)
.await
.expect("filtered search");
assert_eq!(
response["candidate_provenance"],
json!({"lexical": state, "fallback": "none", "terms_truncated": false})
);
assert_eq!(response["total"], total);
if include_drafts {
assert_eq!(response["results"][0]["slug"], "filtered-match");
}
}
}
async fn fetch_fts_candidates(
runtime: &KhiveRuntime,
ns: &str,
raw_query: &str,
type_filter: Option<&str>,
statuses: &[String],
exclude_statuses: &[&str],
fetch_limit: usize,
) -> Result<FtsFetchOutcome, RuntimeError> {
super::fetch_fts_candidates(
runtime,
ns,
raw_query,
type_filter,
statuses,
exclude_statuses,
fetch_limit,
&FtsTermBudget::new(),
LexicalStage::new(
LexicalPass::Full,
tokio::time::Instant::now(),
lexical_stage_budget(),
),
)
.await
}
struct ProbeRecordingReader {
inner: Box<dyn khive_storage::SqlReader>,
probes: Vec<(SqlStatement, Vec<SqlRow>)>,
}
#[async_trait::async_trait]
impl khive_storage::SqlReader for ProbeRecordingReader {
async fn query_row(&mut self, statement: SqlStatement) -> StorageResult<Option<SqlRow>> {
self.inner.query_row(statement).await
}
async fn query_all(&mut self, statement: SqlStatement) -> StorageResult<Vec<SqlRow>> {
let rows = self.inner.query_all(statement.clone()).await?;
self.probes.push((statement, rows.clone()));
Ok(rows)
}
async fn query_scalar(
&mut self,
statement: SqlStatement,
) -> StorageResult<Option<SqlValue>> {
self.inner.query_scalar(statement).await
}
async fn explain(&mut self, statement: SqlStatement) -> StorageResult<Vec<SqlRow>> {
self.inner.explain(statement).await
}
}
#[tokio::test]
async fn compose_direct_handler_rejects_namespace_token_mismatch() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let token = runtime.authorize(Namespace::local()).expect("local token");
let ann = vamana::new_shared();
let err = KnowledgeHandlers::compose(
&runtime,
&token,
json!({
"namespace": "bench-arm-a",
"query": "must reject before reading",
}),
&ann,
HashMap::new(),
)
.await
.expect_err("a local token must not elevate into a measurement arm");
assert!(
matches!(err, RuntimeError::InvalidInput(ref msg) if msg.contains("does not match authorized token namespace")),
"unexpected error: {err:?}"
);
}
#[test]
fn fts_candidate_terms_recalls_non_contiguous_terms() {
assert_eq!(
fts5_candidate_terms("alpha beta alpha and").join(" OR "),
"\"alpha\" OR \"alphas\" OR \"beta\" OR \"betas\""
);
assert_eq!(
fts5_candidate_terms("RAG").join(" OR "),
"\"rag\" OR \"rags\""
);
assert_eq!(
fts5_candidate_terms("the and").join(" OR "),
"\"the and\"",
"stop-only queries retain the exact-phrase fallback"
);
}
#[tokio::test]
async fn rarity_probes_are_capped_and_sort_rare_terms_before_common_terms() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
seed_low_overlap_corpus(&runtime, 1_100, 20).await;
let mut reader = ProbeRecordingReader {
inner: runtime.sql().reader().await.expect("reader"),
probes: Vec::new(),
};
let terms = [
"\"term1\"",
"\"term18\"",
"\"missing\"",
"\"term11\"",
"\"synthetic\"",
];
let ordered = rarest_fts_terms_first(
&mut reader,
terms.iter().map(|term| (*term).to_string()).collect(),
&mut LexicalStage::new(
LexicalPass::Full,
tokio::time::Instant::now(),
lexical_stage_budget(),
),
)
.await
.expect("frequency probes");
assert_eq!(
ordered,
["\"term11\"", "\"term18\"", "\"synthetic\"", "\"term1\""]
);
assert_eq!(reader.probes.len(), terms.len());
assert_eq!(
reader
.probes
.iter()
.map(|(_, rows)| rows.len())
.collect::<Vec<_>>(),
[1; 5],
"each probe must materialize one aggregate row, including zero matches"
);
assert_eq!(
reader
.probes
.iter()
.map(|(_, rows)| row_i64(&rows[0], "frequency").expect("frequency"))
.collect::<Vec<_>>(),
[501, 55, 0, 55, 501],
"rare counts stay exact and both common terms tie at the cap"
);
for (statement, rows) in &reader.probes {
assert!(matches!(statement.params[1], SqlValue::Integer(501)));
assert_eq!(rows[0].columns.len(), 1);
}
}
#[tokio::test]
async fn fts_candidates_pin_the_rowid_prefix_boundary() {
for (regular_count, best_is_admitted) in [
(FTS_TERM_LIMIT * PHASE_A_OVERFETCH_FACTOR, false),
(FTS_TERM_LIMIT - 1, true),
] {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "WITH RECURSIVE entries(n) AS ( \
VALUES(1) UNION ALL SELECT n + 1 FROM entries WHERE n < ?1 \
) \
INSERT INTO knowledge_atoms ( \
rowid, id, namespace, slug, name, content, tags, finalized, \
status, created_at, updated_at \
) \
SELECT n, printf('92700000-0000-0000-0000-%012d', n), \
'local', printf('prefix-%06d', n), 'Prefix Document', \
'zzprefixzz padding padding padding padding padding padding padding', \
'[]', 1, 'reviewed', 0, 0 FROM entries"
.into(),
params: vec![SqlValue::Integer(regular_count as i64)],
label: None,
})
.await
.expect("seed early matches");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms ( \
rowid, id, namespace, slug, name, content, tags, finalized, \
status, created_at, updated_at \
) VALUES ( \
?1, '92700000-0000-0000-0001-000000000000', 'local', \
'zzprefix-best', 'Prefix Document', ?2, '[]', 1, 'reviewed', 0, 0)"
.into(),
params: vec![
SqlValue::Integer((regular_count + 1) as i64),
SqlValue::Text("zzprefixzz ".repeat(8)),
],
label: None,
})
.await
.expect("seed late repeated match");
drop(writer);
let mut reader = access.reader().await.expect("reader");
let best = reader
.query_row(SqlStatement {
sql: "SELECT a.rowid, a.slug FROM fts_knowledge \
JOIN knowledge_atoms AS a ON a.rowid = fts_knowledge.rowid \
WHERE fts_knowledge MATCH ?1 AND a.namespace = 'local' \
AND a.deleted_at IS NULL \
ORDER BY bm25(fts_knowledge), a.slug LIMIT 1"
.into(),
params: vec![SqlValue::Text("\"zzprefixzz\"".into())],
label: None,
})
.await
.expect("BM25 control query")
.expect("BM25 match");
assert_eq!(row_str(&best, "slug").as_deref(), Some("zzprefix-best"));
assert_eq!(row_i64(&best, "rowid"), Some((regular_count + 1) as i64));
drop(reader);
let outcome = fetch_fts_candidates(
&runtime,
"local",
"zzprefixzz",
None,
&[],
&[],
FTS_TERM_LIMIT,
)
.await
.expect("bounded candidate fetch");
assert!(outcome.timeout.is_none());
assert_eq!(outcome.atoms.len(), FTS_TERM_LIMIT);
assert_eq!(
outcome.atoms.iter().any(|atom| atom.slug == "zzprefix-best"),
best_is_admitted,
"BM25-best row admission must follow the rowid window; regular_count={regular_count}"
);
}
}
#[tokio::test]
async fn phase_a_limit_uses_index_order_without_sorting_matches() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
seed_low_overlap_corpus(&runtime, 1_000, 20).await;
let access = runtime.sql();
let mut reader = access.reader().await.expect("reader");
let statement = phase_a_rowids_statement("\"term1\"", 3);
for bounded in [statement.clone(), term_frequency_statement("\"term1\"")] {
for (query, should_sort) in [
(bounded.sql.clone(), false),
(
bounded
.sql
.replace("ORDER BY rowid", "ORDER BY bm25(fts_knowledge), rowid"),
true,
),
] {
let plan = reader
.query_all(SqlStatement {
sql: format!("EXPLAIN QUERY PLAN {query}"),
params: bounded.params.clone(),
label: None,
})
.await
.expect("query plan");
assert!(!plan.is_empty());
assert!(plan.iter().any(|row| {
row_str(row, "detail")
.is_some_and(|detail| detail.contains("fts_knowledge VIRTUAL TABLE INDEX"))
}));
let sorts = plan.iter().any(|row| {
row_str(row, "detail").is_some_and(|detail| detail.contains("TEMP B-TREE"))
});
assert_eq!(sorts, should_sort, "plan: {plan:?}");
}
}
let rows = reader.query_all(statement).await.expect("bounded rowids");
let ids: Vec<_> = rows
.iter()
.map(|row| row_i64(row, "rowid").unwrap())
.collect();
assert_eq!(ids.len(), 3);
assert!(ids.windows(2).all(|pair| pair[0] < pair[1]));
}
#[tokio::test(start_paused = true)]
async fn rarity_probe_expiry_keeps_the_lexical_arm() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
seed_low_overlap_corpus(&runtime, 1_000, 20).await;
let stage_budget = std::time::Duration::from_secs(1);
let outcome = with_lexical_stage_budget_override_ms(
1_000,
khive_storage::scope_request_read_deadline(
stage_budget,
with_fts_probe_deadline_advance_after_term(
1,
std::time::Duration::from_millis(300),
fetch_fts_candidates(
&runtime,
"local",
"term1 term18",
None,
&[],
&[],
CANDIDATE_POOL,
),
),
),
)
.await
.expect("a cut-off ordering probe must not fail the fetch");
assert!(
!outcome.atoms.is_empty(),
"the ordering probe timing out must not discard the lexical arm"
);
assert!(
outcome.timeout.is_some(),
"the degradation must still be reported, not swallowed"
);
assert_eq!(
outcome.state,
LexicalCandidateState::PartialTimeout,
"candidates in hand with a recorded timeout is partial, never clean"
);
let detail = outcome.timeout.expect("recorded timeout");
assert_eq!(
detail.phase,
LexicalPhase::TermFrequency,
"the reported phase must name the probe, not the fetch"
);
}
#[tokio::test(start_paused = true)]
async fn rarity_probe_decides_the_order_and_its_expiry_falls_back_to_arrival() {
let stage_budget = std::time::Duration::from_secs(1);
let topic = |term: &str| format!("topic {term} ");
let fallback_first_term = "term1";
for query in ["term1 term7", "term7 term1"] {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
seed_low_overlap_corpus(&runtime, 1_000, 20).await;
let ordered = with_lexical_stage_budget_override_ms(
1_000,
khive_storage::scope_request_read_deadline(
stage_budget,
with_fts_deadline_advance_after_term(
1,
stage_budget,
fetch_fts_candidates(
&runtime,
"local",
query,
None,
&[],
&[],
CANDIDATE_POOL,
),
),
),
)
.await
.expect("partial fetch");
let ordered_first = ordered
.atoms
.first()
.map(|atom| atom.content.clone())
.expect("the probe-intact fetch must produce candidates");
assert!(
ordered_first.contains(&topic("term7")),
"with the probe intact the rarer term is queried first whatever the \
caller wrote ({query}); got {} atoms, first content {ordered_first:?}",
ordered.atoms.len()
);
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
seed_low_overlap_corpus(&runtime, 1_000, 20).await;
let fallback = with_lexical_stage_budget_override_ms(
1_000,
khive_storage::scope_request_read_deadline(
stage_budget,
with_fts_probe_deadline_advance_after_term(
1,
std::time::Duration::from_millis(300),
with_fts_deadline_advance_after_term(
1,
stage_budget,
fetch_fts_candidates(
&runtime,
"local",
query,
None,
&[],
&[],
CANDIDATE_POOL,
),
),
),
),
)
.await
.expect("partial fetch");
assert!(
!fallback.atoms.is_empty(),
"the fallback must still produce candidates ({query})"
);
let fallback_first = fallback
.atoms
.first()
.map(|atom| atom.content.clone())
.expect("the fallback must still produce candidates");
assert!(
fallback_first.contains(&topic(fallback_first_term)),
"with the probe cut off the fetch must use the candidate-list \
order, expected {fallback_first_term} first ({query}); got {} \
atoms, first content {fallback_first:?}",
fallback.atoms.len()
);
assert!(
fallback.timeout.is_some(),
"a cut-off probe must still be reported ({query})"
);
}
}
#[tokio::test(start_paused = true)]
async fn rare_term_survives_stage_expiry_independent_of_query_order() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
seed_low_overlap_corpus(&runtime, 1_000, 20).await;
let deadline = std::time::Duration::from_secs(1);
for query in ["term1 term18", "term18 term1"] {
let outcome = khive_storage::scope_request_read_deadline(
deadline,
FTS_TEST_DEADLINE_ADVANCE.scope(
FtsTestDeadlineAdvance {
after_completed_terms: 1,
by: deadline,
},
fetch_fts_candidates(&runtime, "local", query, None, &[], &[], CANDIDATE_POOL),
),
)
.await
.expect("partial fetch");
assert!(outcome.timeout.is_some());
assert_eq!(outcome.state, LexicalCandidateState::PartialTimeout);
assert_eq!(
outcome.atoms.len(),
50,
"the rarer term must complete first"
);
assert!(outcome
.atoms
.iter()
.all(|atom| atom.content.contains("term18")));
}
}
#[tokio::test(start_paused = true)]
async fn per_term_fetch_degrades_at_controlled_deadline_boundary() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
const N: u32 = 1_000;
const VOCAB: u32 = 20;
seed_low_overlap_corpus(&runtime, N, VOCAB).await;
let query = "term0 term1";
let deadline = std::time::Duration::from_millis(650);
let new_result = khive_storage::scope_request_read_deadline(
deadline,
FTS_TEST_DEADLINE_ADVANCE.scope(
FtsTestDeadlineAdvance {
after_completed_terms: 1,
by: deadline,
},
fetch_fts_candidates(&runtime, "local", query, None, &[], &[], CANDIDATE_POOL),
),
)
.await;
let outcome = new_result.expect(
"the per-term fetch must return partial degradation when the controlled deadline \
expires between term queries",
);
assert!(
outcome.timeout.is_some(),
"the controlled deadline must be observed"
);
assert_eq!(outcome.state, LexicalCandidateState::PartialTimeout);
assert!(
!outcome.atoms.is_empty(),
"candidates from the completed term must survive degradation"
);
assert!(
outcome.atoms.len() <= CANDIDATE_POOL,
"partial pool must respect the fetch cap; got {}",
outcome.atoms.len()
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn wall_clock_deadline_on_pack_read_path_surfaces_typed_timeout() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let deadline = std::time::Duration::from_millis(50);
let result = khive_storage::scope_request_read_deadline(deadline, async {
let sql = runtime.sql();
let mut reader = sql.reader().await.expect("reader");
reader
.query_all(SqlStatement {
sql: "WITH RECURSIVE numbers(value) AS (\
SELECT 1 UNION ALL SELECT value + 1 FROM numbers WHERE value < 1000\
) SELECT SUM(a.value * b.value * c.value) \
FROM numbers AS a CROSS JOIN numbers AS b CROSS JOIN numbers AS c"
.into(),
params: vec![],
label: Some("knowledge-deadline-probe".into()),
})
.await
})
.await;
assert!(
matches!(result, Err(khive_storage::StorageError::Timeout { .. })),
"a read crossing the wall-clock deadline must surface the typed \
timeout whichever deadline arm fires; got {result:?}"
);
}
#[tokio::test]
async fn round_robin_merge_keeps_later_term_candidates_from_starving() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
{
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "WITH RECURSIVE x(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM x WHERE n < 9 \
) \
INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) \
SELECT \
printf('90000000-0000-0000-0000-%012d', x.n), \
'local', printf('alpha-%02d', x.n), printf('Alpha %02d', x.n), \
'synthetic content about alpha only', '[]', NULL, 1, \
'reviewed', NULL, NULL, x.n, x.n, NULL \
FROM x"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed alpha rows");
writer
.execute(SqlStatement {
sql: "WITH RECURSIVE x(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM x WHERE n < 2 \
) \
INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) \
SELECT \
printf('91000000-0000-0000-0000-%012d', x.n), \
'local', printf('beta-%02d', x.n), printf('Beta %02d', x.n), \
'synthetic content about beta only', '[]', NULL, 1, \
'reviewed', NULL, NULL, x.n, x.n, NULL \
FROM x"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed beta rows");
}
let fetch_limit = 5;
let outcome =
fetch_fts_candidates(&runtime, "local", "alpha beta", None, &[], &[], fetch_limit)
.await
.expect("fetch must not error");
assert!(outcome.timeout.is_none());
assert_eq!(outcome.state, LexicalCandidateState::Matched);
assert_eq!(outcome.atoms.len(), fetch_limit);
let beta_present = outcome
.atoms
.iter()
.any(|atom| atom.slug.starts_with("beta-"));
assert!(
beta_present,
"round-robin merge must keep the second term's candidates in the pool \
even though the first term alone has more matches than fetch_limit; \
got {:?}",
outcome
.atoms
.iter()
.map(|a| a.slug.as_str())
.collect::<Vec<_>>()
);
}
#[tokio::test(start_paused = true)]
async fn lexical_stage_budget_expiry_does_not_cancel_the_request() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
const N: u32 = 1_000;
const VOCAB: u32 = 20;
seed_low_overlap_corpus(&runtime, N, VOCAB).await;
let query = "term0 term1";
let budget = std::time::Duration::from_millis(50);
let outer_deadline = std::time::Duration::from_secs(60);
let (fetch, still_active) =
khive_storage::scope_request_read_deadline(outer_deadline, async {
let fetch = khive_storage::scope_request_read_deadline(
budget,
FTS_TEST_DEADLINE_ADVANCE.scope(
FtsTestDeadlineAdvance {
after_completed_terms: 1,
by: budget,
},
fetch_fts_candidates(
&runtime,
"local",
query,
None,
&[],
&[],
CANDIDATE_POOL,
),
),
)
.await
.expect("the fetch must not hard-error on its own stage budget");
let still_active =
khive_storage::ensure_request_read_active("test.lexical_stage_budget");
(fetch, still_active)
})
.await;
assert!(
fetch.timeout.is_some(),
"the lexical stage's own narrower budget must be observed"
);
assert!(
!fetch.atoms.is_empty(),
"candidates from the completed term must survive the stage degradation"
);
assert!(
still_active.is_ok(),
"the outer request deadline must still be active once the lexical \
stage's own budget expires and its scope returns; got {still_active:?}"
);
}
#[test]
fn lexical_stage_allowance_scales_only_with_admitted_terms_and_is_capped() {
let base = lexical_stage_budget();
let budget = FtsTermBudget::new();
assert_eq!(
lexical_stage_budget_for_terms(base, budget.available_for("zzmass")),
base,
);
assert_eq!(
lexical_stage_budget_for_terms(base, budget.available_for("zzmass zzlass")),
std::time::Duration::from_millis(2_500),
);
let many = distinct_term_query(FTS_TERM_COUNT_LIMIT * 2);
assert_eq!(
lexical_stage_budget_for_terms(base, budget.available_for(&many)),
std::time::Duration::from_millis(8_000),
);
budget.admit(fts5_candidate_terms(&many));
assert_eq!(budget.available_for("zzmass zzlass"), 0);
assert_eq!(lexical_stage_budget_for_terms(base, 0), base);
}
#[tokio::test(start_paused = true)]
async fn multi_term_search_keeps_lexical_candidates_after_single_term_budget() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms \
(id, namespace, slug, name, content, tags, finalized, status, created_at, updated_at) \
VALUES \
('92700000-0000-0000-0000-000000000011', 'local', 'zzmass-row', \
'First term', 'zzmass content', '[]', 1, 'reviewed', 0, 0), \
('92700000-0000-0000-0000-000000000012', 'local', 'zzlass-row', \
'Second term', 'zzlass content', '[]', 1, 'reviewed', 0, 0)"
.into(),
params: Vec::new(),
label: None,
})
.await
.expect("seed two independently matching terms");
drop(writer);
let token = runtime.authorize(Namespace::local()).expect("local token");
let response = with_fts_deadline_advance_after_term(
1,
std::time::Duration::from_millis(2_100),
KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "zzmass zzlass", "rerank": false}),
&vamana::new_shared(),
),
)
.await
.expect("multi-term search");
assert_eq!(response["candidate_provenance"]["lexical"], "matched");
assert_eq!(response["total"], 2);
}
#[tokio::test]
async fn phase_b_widening_recovers_eligible_rows_behind_an_ineligible_top_page() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "WITH RECURSIVE x(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM x WHERE n < 29 \
) \
INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) \
SELECT \
printf('92000000-0000-0000-0000-%012d', x.n), \
'local', printf('zzwidenzz-dep-%02d', x.n), printf('Widen Dep %02d', x.n), \
'synthetic content about zzwidenzz only', '[]', NULL, 1, \
'deprecated', NULL, NULL, x.n, x.n, NULL \
FROM x"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed deprecated widen rows");
writer
.execute(SqlStatement {
sql: "WITH RECURSIVE x(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM x WHERE n < 2 \
) \
INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) \
SELECT \
printf('92100000-0000-0000-0000-%012d', x.n), \
'local', printf('zzwidenzz-ok-%02d', x.n), printf('Widen Ok %02d', x.n), \
'synthetic content about zzwidenzz only', '[]', NULL, 1, \
'reviewed', NULL, NULL, 100 + x.n, 100 + x.n, NULL \
FROM x"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed reviewed widen rows");
drop(writer);
let outcome = fetch_fts_candidates(&runtime, "local", "zzwidenzz", None, &[], &[], 5)
.await
.expect("fetch must not error");
assert!(outcome.timeout.is_none());
assert_eq!(
outcome.atoms.len(),
3,
"only the 3 reviewed rows are eligible; widening must have looked \
past the all-deprecated first page to find them: {:?}",
outcome
.atoms
.iter()
.map(|a| a.slug.as_str())
.collect::<Vec<_>>()
);
assert!(
outcome
.atoms
.iter()
.all(|a| a.slug.starts_with("zzwidenzz-ok-")),
"no deprecated row may survive into the eligible set: {:?}",
outcome
.atoms
.iter()
.map(|a| a.slug.as_str())
.collect::<Vec<_>>()
);
}
#[tokio::test]
async fn phase_b_accepts_a_genuine_shortfall_without_widening() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) VALUES \
('92200000-0000-0000-0000-000000000000', 'local', 'zzsparsezz-00', \
'Sparse 00', 'synthetic content about zzsparsezz only', '[]', NULL, 1, \
'reviewed', NULL, NULL, 0, 0, NULL), \
('92200000-0000-0000-0000-000000000001', 'local', 'zzsparsezz-01', \
'Sparse 01', 'synthetic content about zzsparsezz only', '[]', NULL, 1, \
'reviewed', NULL, NULL, 1, 1, NULL)"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed sparse rows");
drop(writer);
let outcome = fetch_fts_candidates(&runtime, "local", "zzsparsezz", None, &[], &[], 5)
.await
.expect("fetch must not error");
assert!(outcome.timeout.is_none());
assert_eq!(
outcome.atoms.len(),
2,
"a term with only 2 genuinely eligible matches must return exactly \
those, not fabricate more via widening: {:?}",
outcome
.atoms
.iter()
.map(|a| a.slug.as_str())
.collect::<Vec<_>>()
);
}
#[tokio::test]
async fn phase_a_cross_namespace_matches_are_hydrated_out() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) VALUES \
('92300000-0000-0000-0000-000000000000', 'local', 'zzcrossns-local', \
'Cross NS Local', 'synthetic content about zzcrossns only', '[]', NULL, 1, \
'reviewed', NULL, NULL, 0, 0, NULL), \
('92300000-0000-0000-0000-000000000001', 'other', 'zzcrossns-other', \
'Cross NS Other', 'synthetic content about zzcrossns only', '[]', NULL, 1, \
'reviewed', NULL, NULL, 1, 1, NULL)"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed cross-namespace rows");
drop(writer);
let outcome = fetch_fts_candidates(&runtime, "local", "zzcrossns", None, &[], &[], 10)
.await
.expect("fetch must not error");
assert!(outcome.timeout.is_none());
assert_eq!(
outcome.atoms.len(),
1,
"only the local-namespace row is eligible: {:?}",
outcome
.atoms
.iter()
.map(|a| (a.slug.as_str(), a.namespace.as_str()))
.collect::<Vec<_>>()
);
assert_eq!(outcome.atoms[0].namespace, "local");
assert_eq!(outcome.atoms[0].slug, "zzcrossns-local");
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
#[ignore = "manual 200000-row lexical namespace measurement"]
async fn measure_cross_namespace_lexical_work() {
async fn seed_namespace(
runtime: &KhiveRuntime,
ns: &str,
id_prefix: &str,
rows: i64,
matching_rows: i64,
) {
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "WITH RECURSIVE seq(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM seq WHERE n + 1 < ?3 \
) \
INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, finalized, \
status, created_at, updated_at \
) \
SELECT printf('%s-%012d', ?2, n), ?1, \
printf('measurement-%06d', n), 'Measurement Row', \
CASE WHEN n < ?4 THEN \
'namespacechannel content with ordinary padding text' \
ELSE 'unrelated content with ordinary padding text' END, \
'[]', 1, 'reviewed', n, n FROM seq"
.into(),
params: vec![
SqlValue::Text(ns.into()),
SqlValue::Text(id_prefix.into()),
SqlValue::Integer(rows),
SqlValue::Integer(matching_rows),
],
label: None,
})
.await
.expect("seed namespace corpus");
}
for local_matches in [0, 3] {
for foreign_present in [true, false] {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
if foreign_present {
seed_namespace(
&runtime,
"tenant-a",
"92500000-0000-0000-0000",
200_000,
200_000,
)
.await;
}
seed_namespace(
&runtime,
"tenant-b",
"92600000-0000-0000-0000",
10,
local_matches,
)
.await;
for (mode, query) in [
("single", "namespacechannel"),
("multi", "namespacechannel absentchannel"),
] {
let start = std::time::Instant::now();
let outcome = khive_storage::scope_request_read_deadline(
lexical_stage_budget(),
fetch_fts_candidates(
&runtime,
"tenant-b",
query,
None,
&[],
&[],
CANDIDATE_POOL,
),
)
.await
.expect("bounded lexical fetch");
let elapsed_ms = start.elapsed().as_secs_f64() * 1000.0;
assert!(outcome
.atoms
.iter()
.all(|atom| atom.namespace == "tenant-b"));
println!(
"LEXICAL_NAMESPACE mode={mode} foreign_present={foreign_present} local_matches={local_matches} rows={} lexical_elapsed_ms={elapsed_ms:.3} lexical_timeout={}",
outcome.atoms.len(),
outcome.timeout.is_some(),
);
}
}
}
}
#[tokio::test]
async fn empty_result_fallback_never_leaks_a_foreign_namespace_match() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) VALUES \
('92400000-0000-0000-0000-000000000000', 'local', 'unrelated-local-atom', \
'Unrelated Local Atom', 'generic filler text with no special term', \
'[]', NULL, 1, 'reviewed', NULL, NULL, 0, 0, NULL), \
('92400000-0000-0000-0000-000000000001', 'tenant-b', 'foreign-term-atom', \
'Foreign Term Atom', 'synthetic content about zzoraclezz only', '[]', NULL, 1, \
'reviewed', NULL, NULL, 1, 1, NULL)"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed oracle rows");
drop(writer);
let foreign_match =
fetch_fts_candidates(&runtime, "local", "zzoraclezz", None, &[], &[], 5)
.await
.expect("fetch must not error");
let no_match =
fetch_fts_candidates(&runtime, "local", "zzoracleabsentzz", None, &[], &[], 5)
.await
.expect("fetch must not error");
assert!(foreign_match.timeout.is_none());
assert!(no_match.timeout.is_none());
assert_eq!(foreign_match.state, LexicalCandidateState::NoMatch);
assert_eq!(foreign_match.state, no_match.state);
let foreign_slugs: Vec<&str> = foreign_match
.atoms
.iter()
.map(|a| a.slug.as_str())
.collect();
let absent_slugs: Vec<&str> = no_match.atoms.iter().map(|a| a.slug.as_str()).collect();
assert_eq!(
foreign_slugs, absent_slugs,
"a term matching only in another namespace must produce the exact \
same response as a term matching nowhere at all — any \
difference is a cross-namespace existence oracle"
);
assert!(
foreign_slugs.is_empty(),
"unrelated recent rows are not candidates"
);
}
#[tokio::test]
async fn empty_result_fallback_control_index_match_skips_fallback() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) VALUES \
('92400000-0000-0000-0000-000000000002', 'local', 'indexed-term-atom', \
'Indexed Term Atom', 'synthetic content about zzindexedzz only', '[]', NULL, 1, \
'reviewed', NULL, NULL, 0, 0, NULL), \
('92400000-0000-0000-0000-000000000003', 'local', 'unrelated-recent-atom', \
'Unrelated Recent Atom', 'generic filler text with no special term', '[]', NULL, 1, \
'reviewed', NULL, NULL, 1, 1, NULL)"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed control rows");
drop(writer);
let outcome = fetch_fts_candidates(&runtime, "local", "zzindexedzz", None, &[], &[], 5)
.await
.expect("fetch must not error");
assert!(outcome.timeout.is_none());
assert_eq!(
outcome.atoms.len(),
1,
"only the indexed match may be returned, never the unrelated \
fallback-only row: {:?}",
outcome
.atoms
.iter()
.map(|a| a.slug.as_str())
.collect::<Vec<_>>()
);
assert_eq!(outcome.atoms[0].slug, "indexed-term-atom");
assert_eq!(outcome.state, LexicalCandidateState::Matched);
}
#[tokio::test]
async fn filtered_candidate_state_is_stable_behind_a_foreign_ceiling_prefix() {
let mut public_responses = Vec::new();
for foreign_prefix in [false, true] {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
if foreign_prefix {
writer
.execute(SqlStatement {
sql: "WITH RECURSIVE x(n) AS ( \
VALUES(1) UNION ALL SELECT n + 1 FROM x WHERE n < 20 \
) \
INSERT INTO knowledge_atoms ( \
rowid, id, namespace, slug, name, content, tags, finalized, \
status, created_at, updated_at \
) \
SELECT x.n, printf('92710000-0000-0000-0000-%012d', x.n), \
'foreign', printf('foreign-prefix-%02d', x.n), 'Foreign Match', \
'zzfilteredceilingzz', '[]', 1, 'reviewed', 0, 0 \
FROM x"
.into(),
params: Vec::new(),
label: None,
})
.await
.expect("seed foreign ceiling prefix");
}
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms ( \
rowid, id, namespace, slug, name, content, tags, finalized, \
status, created_at, updated_at \
) VALUES ( \
21, '92710000-0000-0000-0000-000000000021', 'local', \
'local-filtered-match', 'Local Filtered Match', \
'zzfilteredceilingzz', '[]', 0, 'draft', 0, 0 \
)"
.into(),
params: Vec::new(),
label: None,
})
.await
.expect("seed identical local filtered match");
drop(writer);
let mut reader = access.reader().await.expect("reader");
let rows = reader
.query_all(phase_a_rowids_statement("\"zzfilteredceilingzz\"", 20))
.await
.expect("inspect ceiling window");
let rowids: Vec<_> = rows
.iter()
.filter_map(|row| row_i64(row, "rowid"))
.collect();
if foreign_prefix {
assert_eq!(rowids, (1..=20).collect::<Vec<i64>>());
} else {
assert_eq!(rowids, [21]);
}
drop(reader);
let token = runtime.authorize(Namespace::local()).expect("local token");
let ann = vamana::new_shared();
let response = with_phase_a_widen_ceiling_override(20, async {
KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "zzfilteredceilingzz", "rerank": false}),
&ann,
)
.await
})
.await
.expect("public filtered search");
assert_eq!(
response,
json!({
"results": [], "total": 0,
"candidate_provenance": {"lexical": "filtered", "fallback": "none", "terms_truncated": false},
}),
"foreign matches must not change the same local filtered result: {foreign_prefix}"
);
public_responses
.push(serde_json::to_vec(&response).expect("serialize public response"));
}
assert_eq!(public_responses[0], public_responses[1]);
}
#[tokio::test]
async fn phase_b_ceiling_exhaustion_recovers_eligible_row_via_scoped_fallback() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "WITH RECURSIVE x(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM x WHERE n < 19 \
) \
INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) \
SELECT \
printf('92500000-0000-0000-0000-%012d', x.n), \
'local', printf('zzceilingzz-dep-%02d', x.n), printf('Ceiling Dep %02d', x.n), \
'synthetic content about zzceilingzz only', '[]', NULL, 1, \
'deprecated', NULL, NULL, x.n, x.n, NULL \
FROM x"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed deprecated ceiling rows");
writer
.execute(SqlStatement {
sql: "WITH RECURSIVE x(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM x WHERE n < 1 \
) \
INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) \
SELECT \
printf('92510000-0000-0000-0000-%012d', x.n), \
'local', printf('zzceilingzz-ok-%02d', x.n), printf('Ceiling Ok %02d', x.n), \
'synthetic content about zzceilingzz only', '[]', NULL, 1, \
'reviewed', NULL, NULL, 100 + x.n, 100 + x.n, NULL \
FROM x"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed reviewed ceiling rows");
drop(writer);
let outcome = with_phase_a_widen_ceiling_override(20, async {
fetch_fts_candidates(&runtime, "local", "zzceilingzz", None, &[], &[], 5).await
})
.await
.expect("fetch must not error");
assert!(outcome.timeout.is_none());
assert_eq!(
outcome.atoms.len(),
2,
"the 2 reviewed rows sit beyond the ceiling-bounded phase-A \
window; only the eligibility-scoped fallback query can recover \
them: {:?}",
outcome
.atoms
.iter()
.map(|a| a.slug.as_str())
.collect::<Vec<_>>()
);
assert!(
outcome
.atoms
.iter()
.all(|a| a.slug.starts_with("zzceilingzz-ok-")),
"no deprecated row may survive into the eligible set: {:?}",
outcome
.atoms
.iter()
.map(|a| a.slug.as_str())
.collect::<Vec<_>>()
);
}
#[tokio::test]
async fn member_token_sizes_report_timeout_instead_of_a_measured_zero() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) VALUES ( \
'92600000-0000-0000-0000-000000000000', 'local', 'sizing-member-atom', \
'Sizing Member Atom', \
'enough body content to price a non-zero token size for the owning domain once member sizing actually runs to completion', \
'[]', NULL, 1, 'reviewed', NULL, NULL, 0, 0, NULL)"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed member atom");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_domains ( \
id, namespace, slug, name, description, tags, members, status, \
created_at, updated_at, deleted_at \
) VALUES ( \
'92600000-0000-0000-0000-000000000001', 'local', 'sizing-domain', \
'Sizing Domain', NULL, '[]', '[\"sizing-member-atom\"]', 'reviewed', \
0, 0, NULL)"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed domain");
drop(writer);
let domain_ids = vec!["92600000-0000-0000-0000-000000000001".to_string()];
let (degraded_sizes, timed_out) = khive_storage::scope_request_read_deadline(
std::time::Duration::ZERO,
load_domain_member_token_sizes(&runtime, "local", &domain_ids),
)
.await
.expect("an expired read deadline must degrade, not error");
assert!(
timed_out,
"an expired read deadline must be reported as unmeasured"
);
assert!(
degraded_sizes.is_empty(),
"a timed-out batch must not contain fabricated measurements"
);
let (healthy_sizes, healthy_timed_out) =
load_domain_member_token_sizes(&runtime, "local", &domain_ids)
.await
.expect("undeadlined lookup must succeed");
assert!(!healthy_timed_out);
assert!(
healthy_sizes
.get(&domain_ids[0])
.is_some_and(|sizing| sizing.tokens > 0 && sizing.live_members == 1),
"control: without a deadline the lookup measures the real member \
body cost; got {healthy_sizes:?}"
);
}
#[tokio::test]
async fn lexical_stage_budget_override_does_not_leak_across_concurrent_tasks() {
let with_override = tokio::spawn(with_lexical_stage_budget_override_ms(50, async {
tokio::task::yield_now().await;
lexical_stage_budget()
}));
let without_override = tokio::spawn(async {
tokio::task::yield_now().await;
lexical_stage_budget()
});
let overridden = with_override.await.expect("task must not panic");
let baseline = without_override.await.expect("task must not panic");
assert_eq!(overridden, std::time::Duration::from_millis(50));
assert_eq!(
baseline,
std::time::Duration::from_millis(LEXICAL_STAGE_BUDGET_MS),
"a concurrently running task with no override of its own must \
never observe another task's override; got {baseline:?}"
);
}
#[tokio::test]
async fn short_exact_name_is_discoverable_without_ann() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
{
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) VALUES ( \
'93000000-0000-0000-0000-000000000001', 'local', \
'ai', 'AI', \
'artificial intelligence overview content for the corpus', '[]', \
NULL, 1, 'reviewed', NULL, NULL, 1000, 1000, NULL \
)"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed short-name atom");
}
let token = runtime.authorize(Namespace::local()).expect("local token");
let ann = vamana::new_shared();
let exact_case = KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "AI", "rerank": false}),
&ann,
)
.await
.expect("exact-case short-name search must not error");
assert_eq!(exact_case["total"], 1);
assert_eq!(exact_case["results"][0]["slug"], "ai");
assert_eq!(exact_case["candidate_provenance"]["lexical"], "exact_name");
assert_eq!(exact_case["candidate_provenance"]["fallback"], "none");
assert_eq!(
exact_case["results"][0]["score_provenance"]["sources"],
json!(["lexical"])
);
assert!(exact_case["results"][0]["score"].as_f64().unwrap() > 0.0);
let lower_case = KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "ai", "rerank": false}),
&ann,
)
.await
.expect("lower-case short-name search must not error");
assert_eq!(lower_case["total"], 1);
assert_eq!(lower_case["results"][0]["slug"], "ai");
assert_eq!(lower_case["candidate_provenance"]["lexical"], "exact_name");
let miss = KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "zz", "rerank": false}),
&ann,
)
.await
.expect("non-matching short query must not error");
assert_eq!(miss["total"], 0);
assert_eq!(miss["candidate_provenance"]["lexical"], "no_match");
let role_qualified = KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "AI", "role": "researcher", "rerank": false}),
&ann,
)
.await
.expect("role-qualified short-name search must not error");
assert_eq!(role_qualified["total"], 1);
assert_eq!(role_qualified["results"][0]["slug"], "ai");
assert_eq!(
role_qualified["candidate_provenance"]["lexical"],
"exact_name"
);
}
#[tokio::test]
async fn exact_name_probe_reports_an_expired_deadline_as_a_timeout() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let sql = runtime.sql();
let mut reader = sql.reader().await.expect("reader before deadline");
let configured = lexical_stage_budget();
let expired =
khive_storage::scope_request_read_deadline(std::time::Duration::ZERO, async {
let mut stage =
LexicalStage::new(LexicalPass::Full, tokio::time::Instant::now(), configured);
let outcome = fetch_exact_name_candidate(
reader.as_mut(),
"local",
"AI",
None,
&[],
&[],
&mut stage,
)
.await;
let timeout = stage.timeout.expect("exact probe captures timeout details");
assert_eq!(timeout.phase, LexicalPhase::ExactNameProbe);
assert_eq!(timeout.effective_budget_ms, 0);
outcome
})
.await;
assert!(
matches!(expired, Ok(ExactNameProbe::TimedOut)),
"an expired read deadline must surface as TimedOut, never as a \
miss; got {expired:?}"
);
let mut stage =
LexicalStage::new(LexicalPass::Full, tokio::time::Instant::now(), configured);
let healthy =
fetch_exact_name_candidate(reader.as_mut(), "local", "AI", None, &[], &[], &mut stage)
.await
.expect("undeadlined probe must succeed");
assert!(
matches!(healthy, ExactNameProbe::Miss),
"control: without a deadline an unseeded name is a plain miss; got {healthy:?}"
);
assert!(stage.timeout.is_none());
}
#[tokio::test]
async fn exact_name_probe_query_plan_uses_slug_index() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let mut reader = runtime.sql().reader().await.expect("exact-name reader");
let rows = reader
.explain(exact_name_statement(
"local",
"ai",
Some("atom"),
&[],
&["draft", "deprecated"],
))
.await
.expect("explain exact-name probe");
let details: Vec<String> = rows
.iter()
.filter_map(|row| match row.get("detail") {
Some(SqlValue::Text(detail)) => Some(detail.clone()),
_ => None,
})
.collect();
assert!(
details.iter().any(|d| d.contains("SEARCH knowledge_atoms")
&& d.contains("USING INDEX")
&& d.contains("namespace=? AND slug=?")),
"exact-name probe must use an index seek, not a table scan: {details:?}"
);
assert!(
!details.iter().any(|d| d.contains("SCAN knowledge_atoms")),
"exact-name probe must never full-scan knowledge_atoms: {details:?}"
);
}
#[tokio::test]
async fn short_exact_name_probe_respects_namespace_status_type_and_soft_deletion() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let sql = runtime.sql();
let mut writer = sql.writer().await.unwrap();
for (index, (ns, slug, name, status, tags, deleted)) in [
("local", "ai", "AI", "draft", "[]", SqlValue::Null),
("tenant-b", "ai", "AI", "reviewed", "[]", SqlValue::Null),
(
"local",
"ml",
"ML",
"reviewed",
"[\"type:domain\"]",
SqlValue::Null,
),
(
"local",
"zz",
"ZZ",
"reviewed",
"[]",
SqlValue::Integer(1000),
),
(
"local",
"custom-name",
"UI",
"reviewed",
"[]",
SqlValue::Null,
),
]
.into_iter()
.enumerate()
{
writer.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms (id, namespace, slug, name, content, tags, finalized, status, created_at, updated_at, deleted_at) \
VALUES (?1, ?2, ?3, ?4, 'unrelated overview', ?5, 1, ?6, 0, 0, ?7)".into(),
params: vec![SqlValue::Text(format!("93000000-0000-0000-0001-{index:012}")), SqlValue::Text(ns.into()), SqlValue::Text(slug.into()), SqlValue::Text(name.into()), SqlValue::Text(tags.into()), SqlValue::Text(status.into()), deleted],
label: None,
}).await.unwrap();
}
drop(writer);
for (ns, query, kind, statuses, expected_state, expected_count) in [
(
"local",
"AI",
Some("atom"),
vec![],
LexicalCandidateState::Filtered,
0,
),
(
"local",
"AI",
Some("atom"),
vec!["draft".to_string()],
LexicalCandidateState::ExactName,
1,
),
(
"tenant-b",
"AI",
Some("atom"),
vec![],
LexicalCandidateState::ExactName,
1,
),
(
"tenant-c",
"AI",
Some("atom"),
vec![],
LexicalCandidateState::NoMatch,
0,
),
(
"local",
"ML",
Some("atom"),
vec![],
LexicalCandidateState::Filtered,
0,
),
(
"local",
"ML",
Some("domain"),
vec![],
LexicalCandidateState::ExactName,
1,
),
(
"local",
"ZZ",
Some("atom"),
vec![],
LexicalCandidateState::NoMatch,
0,
),
(
"local",
"UI",
Some("atom"),
vec![],
LexicalCandidateState::NoMatch,
0,
),
] {
let outcome = fetch_fts_candidates(
&runtime,
ns,
query,
kind,
&statuses,
&["draft", "deprecated"],
5,
)
.await
.unwrap();
assert!(outcome.timeout.is_none());
assert_eq!(
outcome.state, expected_state,
"{ns}/{query}/{kind:?}/{statuses:?}"
);
assert_eq!(outcome.atoms.len(), expected_count);
assert!(outcome.atoms.iter().all(|atom| atom.namespace == ns));
}
}
#[test]
fn fts_candidate_expression_recalls_non_contiguous_terms() {
assert_eq!(
fts5_candidate_terms("alpha beta alpha and").join(" OR "),
"\"alpha\" OR \"alphas\" OR \"beta\" OR \"betas\""
);
assert_eq!(
fts5_candidate_terms("RAG").join(" OR "),
"\"rag\" OR \"rags\""
);
assert_eq!(
fts5_candidate_terms("the and").join(" OR "),
"\"the and\"",
"stop-only queries retain the exact-phrase fallback"
);
}
#[test]
fn rrf_fusion_preserves_per_hit_score_sources_and_ann_fallback() {
let mut hybrid = vec![make_hit("shared", Some("reviewed"), 0.8)];
let ann = vec![make_ann_hit("shared", Some("reviewed"), 0.9)];
fuse_ann_hits(&mut hybrid, &ann, 0.0);
assert_eq!(hybrid.len(), 1);
assert_eq!(
hybrid[0].provenance.to_json()["sources"],
json!(["lexical", "ann"])
);
assert_eq!(candidate_fallback(&hybrid), "none");
let mut ann_only = Vec::new();
fuse_ann_hits(
&mut ann_only,
&[make_ann_hit("semantic", Some("reviewed"), 0.9)],
0.0,
);
assert_eq!(ann_only.len(), 1);
assert_eq!(ann_only[0].provenance.to_json()["sources"], json!(["ann"]));
assert_eq!(candidate_fallback(&ann_only), "ann");
assert_eq!(
ann_only[0].provenance.to_json(),
json!({
"sources": ["ann"],
"embedding_rerank": false,
"normalization": "s_over_s_plus_1",
"calibrated": false,
})
);
let lexical_only = vec![make_hit("lexical", Some("reviewed"), 0.7)];
assert_eq!(
lexical_only[0].provenance.to_json()["sources"],
json!(["lexical"])
);
assert_eq!(candidate_fallback(&lexical_only), "none");
}
#[tokio::test]
async fn embedding_rerank_provenance_is_true_when_rerank_runs() {
let (runtime, _, fail_query) = rt_with_role_aware_recording_embedder();
fail_query.store(true, std::sync::atomic::Ordering::SeqCst);
{
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) VALUES ( \
'94000000-0000-0000-0000-000000000001', 'local', \
'rerank-target', 'Rerank Target', \
'content that the lexical stage must match for the rerank pass', \
'[]', NULL, 1, 'reviewed', NULL, NULL, 1000, 1000, NULL \
)"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed rerank target atom");
}
let token = runtime.authorize(Namespace::local()).expect("local token");
let ann = vamana::new_shared();
let out = KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "rerank target content", "rerank": true}),
&ann,
)
.await
.expect("rerank-enabled search must not error");
assert_eq!(out["total"], 1);
assert_eq!(
out["results"][0]["score_provenance"]["embedding_rerank"], true,
"a successful embedding rerank must record embedding_rerank: true; got {out:?}"
);
}
#[test]
fn exact_name_provenance_survives_merge_without_hiding_timeouts() {
use LexicalCandidateState::{ExactName, Matched, NoMatch, PartialTimeout, TimedOut};
for (states, expected) in [
(vec![NoMatch, ExactName], ExactName),
(vec![ExactName, Matched], Matched),
(vec![ExactName, TimedOut], PartialTimeout),
(vec![ExactName, PartialTimeout], PartialTimeout),
] {
assert_eq!(LexicalCandidateState::merge(&states), expected);
}
}
#[tokio::test]
async fn missing_ann_hydration_is_dropped_and_reported() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let mut hits = vec![ScoredHit {
id: "00000000-0000-0000-0000-000000001763".to_string(),
slug: String::new(),
name: String::new(),
content: None,
tags: None,
finalized: false,
is_domain: false,
status: None,
score: 0.8,
provenance: ScoreProvenance::ann(),
}];
let failures = hydrate_empty_hits(&runtime, "local", &mut hits).await;
assert_eq!(failures, 1);
assert!(hits.is_empty(), "unhydrated shells must never be returned");
let mut response = json!({"results": [], "total": 0});
attach_hydration_degradation(&mut response, failures);
assert_eq!(response["degraded"]["hydration_failures"], 1);
}
#[test]
fn zero_hydration_failures_do_not_change_the_response() {
let mut response = json!({"results": [], "total": 0});
attach_hydration_degradation(&mut response, 0);
assert!(response.get("degraded").is_none());
}
#[test]
fn hydration_degradation_preserves_existing_diagnostics() {
let mut response = json!({
"results": [],
"total": 0,
"degraded": {
"reason": "ann_unavailable",
"cache_safe": false,
}
});
attach_hydration_degradation(&mut response, 7);
assert_eq!(response["degraded"]["reason"], "ann_unavailable");
assert_eq!(response["degraded"]["cache_safe"], false);
assert_eq!(response["degraded"]["hydration_failures"], 7);
}
#[tokio::test]
async fn hydration_chunks_candidate_sets_above_sqlite_bind_ceiling() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
{
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "WITH RECURSIVE x(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM x WHERE n < 20 \
), y(n) AS ( \
VALUES(0) UNION ALL SELECT n + 1 FROM y WHERE n < 49 \
) \
INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) \
SELECT \
printf('70000000-0000-0000-0000-%012d', x.n * 50 + y.n), \
'local', printf('hydrate-%04d', x.n * 50 + y.n), \
printf('Hydrate %04d', x.n * 50 + y.n), 'hydration content', \
'[]', NULL, 1, 'reviewed', NULL, NULL, \
x.n * 50 + y.n, x.n * 50 + y.n, NULL \
FROM x CROSS JOIN y WHERE x.n * 50 + y.n < 1005"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed hydration rows");
}
let mut hits: Vec<ScoredHit> = (0..1005)
.map(|i| ScoredHit {
id: format!("70000000-0000-0000-0000-{i:012}"),
slug: String::new(),
name: String::new(),
content: None,
tags: None,
finalized: false,
is_domain: false,
status: None,
score: 1.0,
provenance: ScoreProvenance::ann(),
})
.collect();
let failures = hydrate_empty_hits(&runtime, "local", &mut hits).await;
assert_eq!(failures, 0);
assert_eq!(hits.len(), 1005);
assert!(hits.iter().all(|hit| hit.slug.starts_with("hydrate-")));
}
#[tokio::test]
async fn hydrate_atoms_statement_plan_uses_primary_key_not_namespace_index() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let ids: Vec<String> = (0..250)
.map(|i| format!("aaaaaaaa-0000-0000-0000-{i:012}"))
.collect();
let mut reader = runtime.sql().reader().await.expect("plan reader");
let rows = reader
.explain(hydrate_atoms_statement("local", &ids))
.await
.expect("explain atom hydration statement");
let details: Vec<String> = rows
.iter()
.filter_map(|row| match row.get("detail") {
Some(SqlValue::Text(detail)) => Some(detail.clone()),
_ => None,
})
.collect();
assert!(
details
.iter()
.any(|detail| detail.contains("USING INDEX sqlite_autoindex_knowledge_atoms_1")),
"atom hydration must seek the primary key: {details:?}"
);
assert!(
!details
.iter()
.any(|detail| detail.contains("idx_knowledge_atoms_ns")),
"atom hydration must not fall back to a namespace index: {details:?}"
);
}
#[tokio::test]
async fn hydrate_domains_statement_plan_uses_primary_key_not_namespace_index() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let ids: Vec<String> = (0..250)
.map(|i| format!("bbbbbbbb-0000-0000-0000-{i:012}"))
.collect();
let mut reader = runtime.sql().reader().await.expect("plan reader");
let rows = reader
.explain(hydrate_domains_statement("local", &ids))
.await
.expect("explain domain hydration statement");
let details: Vec<String> = rows
.iter()
.filter_map(|row| match row.get("detail") {
Some(SqlValue::Text(detail)) => Some(detail.clone()),
_ => None,
})
.collect();
assert!(
details.iter().any(|detail| {
detail.contains("USING INDEX sqlite_autoindex_knowledge_domains_1")
}),
"domain hydration must seek the primary key: {details:?}"
);
assert!(
!details
.iter()
.any(|detail| detail.contains("idx_knowledge_domains_ns")),
"domain hydration must not fall back to a namespace index: {details:?}"
);
}
#[tokio::test]
async fn phase_b_hydration_statement_plan_uses_primary_key_not_namespace_index() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let rowids: Vec<i64> = (1..=HYDRATION_ID_CHUNK as i64).collect();
let mut reader = runtime.sql().reader().await.expect("plan reader");
let rows = reader
.explain(phase_b_hydration_statement("local", &rowids, &[], &[], ""))
.await
.expect("explain phase-b hydration statement");
let details: Vec<String> = rows
.iter()
.filter_map(|row| match row.get("detail") {
Some(SqlValue::Text(detail)) => Some(detail.clone()),
_ => None,
})
.collect();
assert!(
details
.iter()
.any(|detail| detail.contains("USING INTEGER PRIMARY KEY")),
"phase-b hydration must seek the rowid primary key: {details:?}"
);
assert!(
!details
.iter()
.any(|detail| detail.contains("idx_knowledge_atoms_ns")),
"phase-b hydration must not fall back to a namespace index: {details:?}"
);
}
#[tokio::test]
async fn hydrate_atoms_statement_still_scopes_by_namespace() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms ( \
id, namespace, slug, name, content, tags, properties, finalized, \
status, source_uri, source_type, created_at, updated_at, deleted_at \
) VALUES \
('90000000-0000-0000-0000-000000000001', 'local', 'local-one', \
'Local One', 'local content', '[]', NULL, 1, 'reviewed', NULL, NULL, \
1, 1, NULL), \
('90000000-0000-0000-0000-000000000002', 'local', 'local-two', \
'Local Two', 'local content', '[]', NULL, 1, 'reviewed', NULL, NULL, \
2, 2, NULL), \
('90000000-0000-0000-0000-000000000003', 'other', 'other-one', \
'Other One', 'other content', '[]', NULL, 1, 'reviewed', NULL, NULL, \
3, 3, NULL)"
.to_string(),
params: Vec::new(),
label: None,
})
.await
.expect("seed cross-namespace atoms");
drop(writer);
let mut hits: Vec<ScoredHit> = [
"90000000-0000-0000-0000-000000000001",
"90000000-0000-0000-0000-000000000002",
"90000000-0000-0000-0000-000000000003",
]
.iter()
.map(|id| ScoredHit {
id: id.to_string(),
slug: String::new(),
name: String::new(),
content: None,
tags: None,
finalized: false,
is_domain: false,
status: None,
score: 1.0,
provenance: ScoreProvenance::ann(),
})
.collect();
let failures = hydrate_empty_hits(&runtime, "local", &mut hits).await;
assert_eq!(
failures, 1,
"the other-namespace row must be reported as an unhydrated candidate"
);
assert_eq!(hits.len(), 2, "only the local-namespace rows may hydrate");
assert!(
hits.iter()
.all(|hit| hit.id != "90000000-0000-0000-0000-000000000003"),
"the other-namespace row must never be returned: {:?}",
hits.iter().map(|h| &h.id).collect::<Vec<_>>()
);
assert!(hits.iter().any(|hit| hit.slug == "local-one"));
assert!(hits.iter().any(|hit| hit.slug == "local-two"));
}
#[test]
fn knowledge_ann_query_paths_use_query_intent_embed() {
let src = include_str!("search.rs");
let generic_needle: String = [".embed(", "raw_query)"].concat();
let generic_borrowed_needle: String = [".embed(", "&raw_query)"].concat();
let generic_count = src
.lines()
.filter(|l| !l.contains("concat") && !l.contains("needle"))
.filter(|l| l.contains(&generic_needle) || l.contains(&generic_borrowed_needle))
.count();
assert_eq!(
generic_count, 0,
"ANN query paths must not call generic {generic_needle}; \
found {generic_count} occurrence(s) — use embed_query instead"
);
let query_intent_needle: String = [".embed_query(", "raw_query)"].concat();
let query_intent_borrowed_needle: String = [".embed_query(", "&raw_query)"].concat();
let query_intent_count = src
.lines()
.filter(|l| !l.contains("concat") && !l.contains("needle"))
.filter(|l| {
l.contains(&query_intent_needle) || l.contains(&query_intent_borrowed_needle)
})
.count();
assert_eq!(
query_intent_count, 2,
"expected exactly 2 query-intent call sites \
(shared ANN runner + compose KG-blend gate), found {query_intent_count}"
);
}
#[tokio::test]
async fn query_embedding_cache_reuses_query_vector_across_reranks() {
use std::sync::{Arc, Mutex};
use async_trait::async_trait;
use khive_runtime::{AllowAllGate, BackendId, EmbedderProvider, RuntimeConfig};
use lattice_embed::{EmbedError, EmbeddingModel, EmbeddingService};
const MODEL_KEY: &str = "all-minilm-l6-v2";
const DIM: usize = 384;
struct RecordingService {
texts: Arc<Mutex<Vec<String>>>,
}
#[async_trait]
impl EmbeddingService for RecordingService {
async fn embed(
&self,
texts: &[String],
_model: EmbeddingModel,
) -> Result<Vec<Vec<f32>>, EmbedError> {
self.texts
.lock()
.expect("recording lock")
.extend(texts.iter().cloned());
Ok(texts.iter().map(|_| vec![0.5; DIM]).collect())
}
fn supports_model(&self, _model: EmbeddingModel) -> bool {
true
}
fn name(&self) -> &'static str {
"query-reuse-recording-service"
}
}
struct RecordingProvider {
texts: Arc<Mutex<Vec<String>>>,
}
#[async_trait]
impl EmbedderProvider for RecordingProvider {
fn name(&self) -> &str {
MODEL_KEY
}
fn dimensions(&self) -> usize {
DIM
}
async fn build(
&self,
) -> Result<Arc<dyn EmbeddingService>, khive_runtime::RuntimeError> {
Ok(Arc::new(RecordingService {
texts: Arc::clone(&self.texts),
}))
}
}
let texts = Arc::new(Mutex::new(Vec::new()));
let runtime = KhiveRuntime::new(RuntimeConfig {
web: Default::default(),
telemetry: Default::default(),
mounts: Vec::new(),
brain: Default::default(),
git_write: Default::default(),
display_timezone: khive_runtime::config::resolve_default_display_timezone(),
events_split: None,
db_path: None,
blob_hydration_bytes: khive_runtime::DEFAULT_BLOB_HYDRATION_BYTES,
default_namespace: Namespace::local(),
embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
additional_embedding_models: Vec::new(),
gate: Arc::new(AllowAllGate),
packs: vec!["knowledge".to_string()],
backend_id: BackendId::main(),
brain_profile: None,
visible_namespaces: Vec::new(),
allowed_outbound_namespaces: Vec::new(),
actor_id: None,
exec: Default::default(),
})
.expect("runtime");
runtime.register_embedder(RecordingProvider {
texts: Arc::clone(&texts),
});
let query = "one request-local query vector";
let mut query_embedding = QueryEmbeddingCache::default();
let first = vec![
"first candidate".to_string(),
"second candidate".to_string(),
];
let second = vec!["third candidate".to_string()];
assert_eq!(
embed_cosine_scores(&runtime, query, &mut query_embedding, &first)
.await
.expect("first rerank")
.expect("first scores")
.len(),
2
);
assert!(
query_embedding.any().is_some(),
"first rerank must fill cache"
);
assert!(
query_embedding.role_specific.is_not_attempted(),
"embed_cosine_scores must cache the batch vector as generic, \
never role_specific — it came from embed_batch, not embed_query"
);
assert_eq!(
embed_cosine_scores(&runtime, query, &mut query_embedding, &second)
.await
.expect("second rerank")
.expect("second scores")
.len(),
1
);
let recorded = texts.lock().expect("recording lock");
assert_eq!(
recorded
.iter()
.filter(|text| text.as_str() == query)
.count(),
1,
"the shared query must be embedded exactly once: {recorded:?}"
);
assert_eq!(recorded.len(), 4, "one query plus three candidates");
}
const ROLE_RECORDING_MODEL_KEY: &str = "all-minilm-l6-v2";
const ROLE_RECORDING_DIM: usize = 384;
const ROLE_RECORDING_QUERY: &str = "graph traversal caching strategies distributed \
knowledge retrieval systems degraded embedding providers";
const ROLE_RECORDING_ATOM_CONTENT: &str = "graph traversal caching strategies distributed \
knowledge retrieval systems degraded embedding providers require resilient fallback \
behavior across production knowledge retrieval pipelines and search infrastructure";
#[derive(Debug, Default)]
struct RoleAwareRecordingCalls {
query: Vec<String>,
generic: Vec<String>,
query_gate: Option<std::sync::Arc<tokio::sync::Semaphore>>,
}
struct RoleAwareRecordingService {
calls: std::sync::Arc<std::sync::Mutex<RoleAwareRecordingCalls>>,
fail_query: std::sync::Arc<std::sync::atomic::AtomicBool>,
}
#[async_trait::async_trait]
impl lattice_embed::EmbeddingService for RoleAwareRecordingService {
async fn embed(
&self,
texts: &[String],
_model: lattice_embed::EmbeddingModel,
) -> Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
self.calls
.lock()
.expect("recording lock")
.generic
.extend(texts.iter().cloned());
Ok(texts
.iter()
.map(|_| vec![0.5; ROLE_RECORDING_DIM])
.collect())
}
async fn embed_query(
&self,
texts: &[String],
_model: lattice_embed::EmbeddingModel,
) -> Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
let gate = {
let mut calls = self.calls.lock().expect("recording lock");
calls.query.extend(texts.iter().cloned());
calls.query_gate.clone()
};
if let Some(gate) = gate {
gate.acquire()
.await
.expect("query gate remains open")
.forget();
}
if self.fail_query.load(std::sync::atomic::Ordering::SeqCst) {
return Err(lattice_embed::EmbedError::InferenceFailed(
"forced query-embedding failure".into(),
));
}
Ok(texts
.iter()
.map(|_| vec![0.25; ROLE_RECORDING_DIM])
.collect())
}
fn supports_model(&self, _model: lattice_embed::EmbeddingModel) -> bool {
true
}
fn name(&self) -> &'static str {
"role-aware-recording-service"
}
}
struct RoleAwareRecordingProvider {
calls: std::sync::Arc<std::sync::Mutex<RoleAwareRecordingCalls>>,
fail_query: std::sync::Arc<std::sync::atomic::AtomicBool>,
}
#[async_trait::async_trait]
impl khive_runtime::EmbedderProvider for RoleAwareRecordingProvider {
fn name(&self) -> &str {
ROLE_RECORDING_MODEL_KEY
}
fn dimensions(&self) -> usize {
ROLE_RECORDING_DIM
}
async fn build(
&self,
) -> Result<std::sync::Arc<dyn lattice_embed::EmbeddingService>, RuntimeError> {
Ok(std::sync::Arc::new(RoleAwareRecordingService {
calls: std::sync::Arc::clone(&self.calls),
fail_query: std::sync::Arc::clone(&self.fail_query),
}))
}
}
fn rt_with_role_aware_recording_embedder() -> (
KhiveRuntime,
std::sync::Arc<std::sync::Mutex<RoleAwareRecordingCalls>>,
std::sync::Arc<std::sync::atomic::AtomicBool>,
) {
let calls = std::sync::Arc::new(std::sync::Mutex::new(RoleAwareRecordingCalls::default()));
let fail_query = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let runtime = KhiveRuntime::new(khive_runtime::RuntimeConfig {
web: Default::default(),
telemetry: Default::default(),
mounts: Vec::new(),
brain: Default::default(),
git_write: Default::default(),
display_timezone: khive_runtime::config::resolve_default_display_timezone(),
events_split: None,
db_path: None,
blob_hydration_bytes: khive_runtime::DEFAULT_BLOB_HYDRATION_BYTES,
default_namespace: Namespace::local(),
embedding_model: Some(lattice_embed::EmbeddingModel::AllMiniLmL6V2),
additional_embedding_models: Vec::new(),
gate: std::sync::Arc::new(khive_runtime::AllowAllGate),
packs: vec!["kg".to_string(), "knowledge".to_string()],
backend_id: khive_runtime::BackendId::main(),
brain_profile: None,
visible_namespaces: Vec::new(),
allowed_outbound_namespaces: Vec::new(),
actor_id: None,
exec: Default::default(),
})
.expect("in-memory runtime");
runtime.register_embedder(RoleAwareRecordingProvider {
calls: std::sync::Arc::clone(&calls),
fail_query: std::sync::Arc::clone(&fail_query),
});
(runtime, calls, fail_query)
}
#[tokio::test]
async fn search_and_suggest_start_lexical_reads_while_query_embedding_waits() {
for suggest in [false, true] {
let (runtime, calls, _) = rt_with_role_aware_recording_embedder();
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms \
(id, namespace, slug, name, content, tags, finalized, status, created_at, updated_at) \
VALUES ('94000000-0000-0000-0000-000000000238', 'local', \
'candidate-overlap', 'Candidate Overlap', \
'graph traversal caching strategies distributed knowledge retrieval', \
'[]', 1, 'reviewed', 0, 0)"
.into(),
params: Vec::new(),
label: None,
})
.await
.expect("seed lexical hit");
drop(writer);
let gate = Arc::new(tokio::sync::Semaphore::new(0));
calls.lock().expect("recording lock").query_gate = Some(Arc::clone(&gate));
let token = runtime.authorize(Namespace::local()).expect("token");
let ann = vamana::new_shared_for_role(false);
let probes = Arc::new(Mutex::new(Vec::new()));
let query = "graph traversal caching strategies distributed knowledge retrieval";
let future = TERM_PROBES.scope(probes.clone(), async {
if suggest {
KnowledgeHandlers::suggest(&runtime, &token, json!({"query": query}), &ann)
.await
} else {
KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": query, "rerank": false}),
&ann,
)
.await
}
});
tokio::pin!(future);
let overlapped = tokio::time::timeout(std::time::Duration::from_secs(3), async {
loop {
let embedding_started = !calls.lock().expect("recording lock").query.is_empty();
let lexical_started = !probes.lock().expect("term probes").is_empty();
if embedding_started && lexical_started {
break;
}
tokio::select! {
result = &mut future => panic!("candidate stages finished before gate release: {result:?}"),
() = tokio::time::sleep(std::time::Duration::from_millis(1)) => {}
}
}
})
.await;
gate.add_permits(1);
assert!(
overlapped.is_ok(),
"lexical read waited for embedding: suggest={suggest}"
);
let response = future
.await
.expect("candidate stages complete after gate release");
if !suggest {
assert_eq!(response["results"][0]["slug"], "candidate-overlap");
assert_eq!(response["candidate_provenance"]["lexical"], "matched");
}
}
}
#[tokio::test(start_paused = true)]
async fn failed_embedding_and_timed_out_lexical_stage_return_degraded_search() {
let (runtime, _, fail_query) = rt_with_role_aware_recording_embedder();
fail_query.store(true, std::sync::atomic::Ordering::SeqCst);
let token = runtime.authorize(Namespace::local()).expect("token");
let ann = vamana::new_shared_for_role(false);
let response = crate::knowledge::lexical_timeout::tests::with_timeout(
vec![LexicalPhase::ReaderOpen],
std::time::Duration::from_millis(1),
KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "graph traversal caching strategies", "rerank": false}),
&ann,
),
)
.await
.expect("both recoverable candidate failures remain a response");
assert_eq!(response["total"], 0);
assert_eq!(response["candidate_provenance"]["lexical"], "timed_out");
assert_eq!(response["degraded"]["lexical_timeout"], true);
}
#[tokio::test(start_paused = true)]
async fn completed_ann_candidate_survives_lexical_stage_timeout() {
let (runtime, _, _) = rt_with_role_aware_recording_embedder();
let runtime = runtime.with_ann_fresh_tail_enabled(false);
let atom_id = Uuid::from_u128(0x94000000000000000000000000000239);
let access = runtime.sql();
let mut writer = access.writer().await.expect("writer");
writer
.execute(SqlStatement {
sql: "INSERT INTO knowledge_atoms \
(id, namespace, slug, name, content, tags, finalized, status, created_at, updated_at) \
VALUES (?1, 'local', 'ann-timeout-survivor', 'ANN Timeout Survivor', \
'dense candidate outside this lexical query', '[]', 1, 'reviewed', 0, 0)"
.into(),
params: vec![SqlValue::Text(atom_id.to_string())],
label: None,
})
.await
.expect("seed ANN hydration row");
writer
.execute(SqlStatement {
sql: "INSERT INTO ann_consumer_watermark \
(consumer, namespace, embedding_model, watermark) \
VALUES ('knowledge:knowledge.atom', 'local', ?1, 0)"
.into(),
params: vec![SqlValue::Text(ROLE_RECORDING_MODEL_KEY.into())],
label: None,
})
.await
.expect("register loaded ANN consumer");
drop(writer);
let ann = vamana::new_shared_for_role(false);
let key = vamana::AnnKey::new("local", ROLE_RECORDING_MODEL_KEY);
let bridge = vamana::AnnBridge::build(
vec![0.25; ROLE_RECORDING_DIM],
ROLE_RECORDING_DIM,
vec![atom_id],
)
.expect("build loaded bridge");
vamana::install_if_fresher(&ann, &key, bridge).await;
let token = runtime.authorize(Namespace::local()).expect("token");
let response = crate::knowledge::lexical_timeout::tests::with_timeout(
vec![LexicalPhase::ReaderOpen],
std::time::Duration::from_millis(1),
KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": "graph traversal caching strategies", "rerank": false}),
&ann,
),
)
.await
.expect("lexical timeout retains completed ANN result");
assert_eq!(response["total"], 1);
assert_eq!(response["results"][0]["slug"], "ann-timeout-survivor");
assert_eq!(
response["results"][0]["score_provenance"]["sources"],
json!(["ann"])
);
assert_eq!(response["candidate_provenance"]["fallback"], "ann");
assert_eq!(response["degraded"]["lexical_timeout"], true);
}
fn build_role_recording_registry(rt: &KhiveRuntime) -> khive_runtime::VerbRegistry {
let mut builder = khive_runtime::VerbRegistryBuilder::new();
builder.register(khive_pack_kg::KgPack::new(rt.clone()));
builder.register(crate::KnowledgePack::new(rt.clone()));
let registry = builder.build().expect("registry builds");
rt.install_edge_rules(registry.all_edge_rules());
registry
}
async fn seed_role_recording_corpus(registry: &khive_runtime::VerbRegistry) {
registry
.dispatch(
"knowledge.upsert_atoms",
json!({
"atoms": [{
"slug": "role-recording-atom",
"name": "Role Recording Atom",
"finalized": true,
"content": ROLE_RECORDING_ATOM_CONTENT
}]
}),
)
.await
.expect("upsert atom");
registry
.dispatch(
"knowledge.upsert_domains",
json!({
"domains": [{
"slug": "role-recording-domain",
"name": "Role Recording Domain",
"description": ROLE_RECORDING_ATOM_CONTENT,
"members": ["role-recording-atom"]
}]
}),
)
.await
.expect("upsert domain");
registry
.dispatch("knowledge.index", json!({ "rebuild_ann": false }))
.await
.expect("index");
}
#[tokio::test]
async fn compose_auto_does_not_retry_role_specific_embed_after_suggest_failure() {
let (rt, calls, fail_query) = rt_with_role_aware_recording_embedder();
let registry = build_role_recording_registry(&rt);
seed_role_recording_corpus(®istry).await;
fail_query.store(true, std::sync::atomic::Ordering::SeqCst);
let ann = vamana::new_shared();
let token = rt.authorize(Namespace::local()).expect("authorize");
let result = KnowledgeHandlers::compose(
&rt,
&token,
json!({ "query": ROLE_RECORDING_QUERY }),
&ann,
HashMap::new(),
)
.await
.expect("compose must not Err when the query embedding is degraded");
let attempts = calls
.lock()
.expect("recording lock")
.query
.iter()
.filter(|text| text.as_str() == ROLE_RECORDING_QUERY)
.count();
assert_eq!(
attempts, 1,
"a failed embed_query must not be retried later in the same request; result: {result}"
);
assert_eq!(
result["data"]["count"].as_u64(),
Some(1),
"the atom must still reach the briefing through the degraded blend path; \
result: {result}"
);
}
#[tokio::test]
async fn compose_auto_reuses_successful_suggest_embed_without_retry() {
let (rt, calls, _fail_query) = rt_with_role_aware_recording_embedder();
let registry = build_role_recording_registry(&rt);
seed_role_recording_corpus(®istry).await;
let ann = vamana::new_shared();
let token = rt.authorize(Namespace::local()).expect("authorize");
let result = KnowledgeHandlers::compose(
&rt,
&token,
json!({ "query": ROLE_RECORDING_QUERY }),
&ann,
HashMap::new(),
)
.await
.expect("compose must not Err");
let attempts = calls
.lock()
.expect("recording lock")
.query
.iter()
.filter(|text| text.as_str() == ROLE_RECORDING_QUERY)
.count();
assert_eq!(
attempts, 1,
"a successful embed_query must be reused, not repeated; result: {result}"
);
assert_eq!(
result["data"]["count"].as_u64(),
Some(1),
"result: {result}"
);
}
#[tokio::test]
async fn compose_direct_call_without_suggest_still_embeds_query_once() {
let (rt, calls, _fail_query) = rt_with_role_aware_recording_embedder();
let registry = build_role_recording_registry(&rt);
seed_role_recording_corpus(®istry).await;
let ann = vamana::new_shared();
let token = rt.authorize(Namespace::local()).expect("authorize");
let result = KnowledgeHandlers::compose(
&rt,
&token,
json!({
"query": ROLE_RECORDING_QUERY,
"domain_ids": ["role-recording-domain"],
}),
&ann,
HashMap::new(),
)
.await
.expect("compose must not Err");
let attempts = calls
.lock()
.expect("recording lock")
.query
.iter()
.filter(|text| text.as_str() == ROLE_RECORDING_QUERY)
.count();
assert_eq!(
attempts, 1,
"a stage that never tried must still embed once; result: {result}"
);
assert_eq!(
result["data"]["count"].as_u64(),
Some(1),
"result: {result}"
);
}
#[tokio::test]
async fn search_suggest_compose_dispatch_query_through_embed_query_not_generic() {
for verb in ["search", "suggest", "compose"] {
let (rt, calls, _fail_query) = rt_with_role_aware_recording_embedder();
let registry = build_role_recording_registry(&rt);
seed_role_recording_corpus(®istry).await;
let ann = vamana::new_shared();
let token = rt.authorize(Namespace::local()).expect("authorize");
match verb {
"search" => {
KnowledgeHandlers::search(
&rt,
&token,
json!({ "query": ROLE_RECORDING_QUERY }),
&ann,
)
.await
.expect("search must not Err");
}
"suggest" => {
KnowledgeHandlers::suggest(
&rt,
&token,
json!({ "query": ROLE_RECORDING_QUERY }),
&ann,
)
.await
.expect("suggest must not Err");
}
"compose" => {
KnowledgeHandlers::compose(
&rt,
&token,
json!({ "query": ROLE_RECORDING_QUERY }),
&ann,
HashMap::new(),
)
.await
.expect("compose must not Err");
}
_ => unreachable!(),
}
let recorded = calls.lock().expect("recording lock");
assert!(
recorded
.query
.iter()
.any(|text| text == ROLE_RECORDING_QUERY),
"{verb}: query text must reach embed_query at least once; recorded={recorded:?}"
);
assert!(
!recorded
.generic
.iter()
.any(|text| text == ROLE_RECORDING_QUERY),
"{verb}: query text must never reach the generic embed path; recorded={recorded:?}"
);
}
}
fn make_hit(id: &str, status: Option<&str>, score: f32) -> ScoredHit {
ScoredHit {
id: id.to_string(),
slug: id.to_string(),
name: id.to_string(),
content: None,
tags: None,
finalized: false,
is_domain: false,
status: status.map(str::to_string),
score,
provenance: ScoreProvenance::lexical(),
}
}
fn make_ann_hit(id: &str, status: Option<&str>, score: f32) -> ScoredHit {
let mut hit = make_hit(id, status, score);
hit.provenance = ScoreProvenance::ann();
hit
}
#[test]
fn rrf_overlap_retains_both_candidate_sources() {
let mut hits = vec![
make_hit("shared", Some("reviewed"), 8.0),
make_hit("lexical-only", Some("reviewed"), 4.0),
];
let ann = vec![
make_ann_hit("shared", Some("reviewed"), 0.9),
make_ann_hit("ann-only", Some("reviewed"), 0.8),
];
fuse_ann_hits(&mut hits, &ann, 0.0);
assert_eq!(hits.len(), 3);
assert_eq!(hits[0].id, "shared");
assert_eq!(hits[0].score, 1.0);
assert_eq!(
hits[0].provenance.to_json(),
json!({
"sources": ["lexical", "ann"],
"embedding_rerank": false,
"normalization": "s_over_s_plus_1",
"calibrated": false,
})
);
let lexical = hits.iter().find(|hit| hit.id == "lexical-only").unwrap();
let ann = hits.iter().find(|hit| hit.id == "ann-only").unwrap();
assert_eq!(lexical.provenance, ScoreProvenance::lexical());
assert_eq!(ann.provenance, ScoreProvenance::ann());
assert_eq!(lexical.score, ann.score);
}
#[test]
fn decomposed_overlap_merges_provenance_without_counting_duplicates_twice() {
let full = vec![
make_hit("shared", Some("reviewed"), 8.0),
make_hit("full-only", Some("reviewed"), 6.0),
];
let subqueries = [
vec![
make_ann_hit("shared", Some("reviewed"), 100.0),
make_hit("sub-shared", Some("reviewed"), 10.0),
make_ann_hit("sub-shared", Some("reviewed"), 50.0),
],
vec![
make_ann_hit("shared", Some("reviewed"), 100.0),
make_ann_hit("sub-shared", Some("reviewed"), 50.0),
make_ann_hit("ann-only", Some("reviewed"), 2.0),
],
];
let hits = merge_decomposed_hits(full, subqueries, 0.5, 10);
let ids: Vec<_> = hits.iter().map(|hit| hit.id.as_str()).collect();
assert_eq!(ids, ["shared", "full-only", "sub-shared", "ann-only"]);
assert_eq!(hits[0].score, 12.0);
assert_eq!(hits[1].score, 6.0);
assert_eq!(hits[2].score, 4.5);
assert!((hits[3].score - 0.6).abs() < 1e-6);
for hit in [&hits[0], &hits[2]] {
assert!(hit.provenance.lexical && hit.provenance.ann);
assert!(!hit.provenance.embedding_rerank);
}
assert_eq!(hits[1].provenance, ScoreProvenance::lexical());
assert_eq!(hits[3].provenance, ScoreProvenance::ann());
}
#[test]
fn candidate_fallback_requires_ann_without_any_lexical_source() {
let lexical = make_hit("lexical", None, 1.0);
let ann = make_ann_hit("ann", None, 1.0);
let mut overlap = lexical.clone();
overlap.provenance.merge_sources(ann.provenance);
assert_eq!(candidate_fallback(&[]), "none");
assert_eq!(candidate_fallback(std::slice::from_ref(&ann)), "ann");
assert_eq!(candidate_fallback(std::slice::from_ref(&lexical)), "none");
assert_eq!(candidate_fallback(&[lexical, ann]), "none");
assert_eq!(candidate_fallback(&[overlap]), "none");
}
#[tokio::test]
async fn skipped_embedding_rerank_preserves_scores_and_provenance() {
let runtime = KhiveRuntime::new(khive_runtime::RuntimeConfig {
db_path: None,
..khive_runtime::RuntimeConfig::no_embeddings()
})
.expect("in-memory runtime without embeddings");
assert!(runtime.config().db_path.is_none());
let mut hits = vec![
make_hit("lexical", None, 3.0),
make_ann_hit("ann", None, 0.8),
];
let applied = rerank_with_embeddings(
&runtime,
"provenance query",
&mut QueryEmbeddingCache::default(),
&mut hits,
0.7,
)
.await
.expect("optional rerank");
assert!(!applied);
assert_eq!(hits[0].score, 3.0);
assert_eq!(hits[1].score, 0.8);
assert_eq!(hits[0].provenance, ScoreProvenance::lexical());
assert_eq!(hits[1].provenance, ScoreProvenance::ann());
}
#[tokio::test]
async fn search_reports_lexical_provenance_and_successful_embedding_rerank() {
let (runtime, calls, fail_query) = rt_with_role_aware_recording_embedder();
let registry = build_role_recording_registry(&runtime);
seed_role_recording_corpus(®istry).await;
fail_query.store(true, std::sync::atomic::Ordering::SeqCst);
let token = runtime.authorize(Namespace::local()).expect("local token");
let ann = vamana::new_shared();
for rerank in [false, true] {
calls.lock().expect("recording lock").generic.clear();
let response = KnowledgeHandlers::search(
&runtime,
&token,
json!({"query": ROLE_RECORDING_QUERY, "kind": "atom", "rerank": rerank}),
&ann,
)
.await
.expect("search");
assert_eq!(response["total"], 1, "{response}");
assert_eq!(response["results"][0]["slug"], "role-recording-atom");
assert_eq!(
response["results"][0]["score_provenance"],
json!({
"sources": ["lexical"],
"embedding_rerank": rerank,
"normalization": "s_over_s_plus_1",
"calibrated": false,
})
);
let recorded = calls.lock().expect("recording lock");
if rerank {
assert_eq!(
recorded.generic,
[
ROLE_RECORDING_QUERY.to_string(),
format!("Role Recording Atom {ROLE_RECORDING_ATOM_CONTENT}")
]
);
} else {
assert!(recorded.generic.is_empty());
}
}
}
#[test]
fn explicit_status_is_an_exact_allowlist_for_hydrated_hits() {
let mut hits = vec![
make_hit("reviewed", Some("reviewed"), 0.9),
make_hit("draft", Some("draft"), 0.8),
make_hit("deprecated", Some("deprecated"), 0.7),
make_hit("missing-status", None, 0.6),
];
filter_hits_by_status(&mut hits, &["draft".to_string()], &[]);
let ids: Vec<&str> = hits.iter().map(|hit| hit.id.as_str()).collect();
assert_eq!(ids, ["draft"]);
}
#[test]
fn deprecated_multiplier_gate_uses_resolved_status_policy() {
assert!(!deprecated_allowed_by_status_policy(
&[],
&["draft", "deprecated"]
));
assert!(!deprecated_allowed_by_status_policy(&[], &["deprecated"]));
assert!(deprecated_allowed_by_status_policy(&[], &["reviewed"]));
assert!(!deprecated_allowed_by_status_policy(
&["reviewed".to_string()],
&[]
));
assert!(deprecated_allowed_by_status_policy(
&["deprecated".to_string()],
&[]
));
}
#[test]
fn filter_excluded_statuses_removes_draft_hits() {
let mut hits = vec![
make_hit("reviewed-1", Some("reviewed"), 0.8),
make_hit("draft-1", Some("draft"), 0.7),
make_hit("reviewed-2", Some("reviewed"), 0.6),
make_hit("draft-2", Some("draft"), 0.5),
];
filter_by_excluded_statuses(&mut hits, &["draft", "deprecated"]);
let ids: Vec<&str> = hits.iter().map(|h| h.id.as_str()).collect();
assert_eq!(
ids,
["reviewed-1", "reviewed-2"],
"draft hits must be removed"
);
}
#[test]
fn filter_excluded_statuses_removes_deprecated_hits() {
let mut hits = vec![
make_hit("reviewed-1", Some("reviewed"), 0.9),
make_hit("deprecated-1", Some("deprecated"), 0.8),
];
filter_by_excluded_statuses(&mut hits, &["draft", "deprecated"]);
let ids: Vec<&str> = hits.iter().map(|h| h.id.as_str()).collect();
assert_eq!(ids, ["reviewed-1"]);
}
#[test]
fn filter_excluded_statuses_empty_list_is_noop() {
let mut hits = vec![
make_hit("draft-1", Some("draft"), 0.9),
make_hit("reviewed-1", Some("reviewed"), 0.8),
];
filter_by_excluded_statuses(&mut hits, &[]);
assert_eq!(hits.len(), 2, "empty exclude list must be a no-op");
}
#[test]
fn filter_excluded_statuses_null_status_treated_as_not_excluded() {
let mut hits = vec![
make_hit("no-status", None, 0.9),
make_hit("draft-1", Some("draft"), 0.7),
];
filter_by_excluded_statuses(&mut hits, &["draft", "deprecated"]);
let ids: Vec<&str> = hits.iter().map(|h| h.id.as_str()).collect();
assert_eq!(ids, ["no-status"], "null-status hit must survive exclusion");
}
#[test]
fn normalize_rrf_score_is_bounded_and_monotonic() {
let k = RRF_K;
let max_single = 1.0f32 / (k as f32 + 1.0);
let scores_single = [
max_single * 0.25,
max_single * 0.5,
max_single,
max_single * 1.5,
];
let normed_single: Vec<f32> = scores_single
.iter()
.map(|&r| normalize_rrf_score(r, 1, k))
.collect();
for &s in &normed_single {
assert!((0.0..=1.0).contains(&s), "score out of range: {s}");
}
assert!(normed_single[0] < normed_single[1]);
assert!(normed_single[1] < normed_single[2]);
assert_eq!(normed_single[3], 1.0);
let max_two = 2.0f32 / (k as f32 + 1.0);
let scores_two = [max_two * 0.25, max_two * 0.75, max_two, max_two * 2.0];
let normed_two: Vec<f32> = scores_two
.iter()
.map(|&r| normalize_rrf_score(r, 2, k))
.collect();
for &s in &normed_two {
assert!((0.0..=1.0).contains(&s), "score out of range: {s}");
}
assert!(normed_two[0] < normed_two[1]);
assert!(normed_two[1] < normed_two[2]);
assert_eq!(normed_two[3], 1.0);
let raw = [0.001f32, 0.005, 0.010, 0.015];
let normed: Vec<f32> = raw.iter().map(|&r| normalize_rrf_score(r, 1, k)).collect();
let raw_order: Vec<usize> = {
let mut idx: Vec<usize> = (0..raw.len()).collect();
idx.sort_by(|&a, &b| raw[b].partial_cmp(&raw[a]).unwrap());
idx
};
let norm_order: Vec<usize> = {
let mut idx: Vec<usize> = (0..normed.len()).collect();
idx.sort_by(|&a, &b| normed[b].partial_cmp(&normed[a]).unwrap());
idx
};
assert_eq!(
raw_order, norm_order,
"normalization must not invert ranking"
);
}
#[test]
fn normalize_rrf_score_zero_source_count_returns_zero() {
assert_eq!(normalize_rrf_score(0.5, 0, RRF_K), 0.0);
}
#[test]
fn min_score_floor_drops_hit_squashed_below_threshold_by_status_multiplier() {
let mut hits = vec![make_hit("atom-1", Some("reviewed"), 0.0)];
fuse_ann_hits(&mut hits, &[], 0.7);
assert_eq!(hits.len(), 1, "fusion stage must admit the 1.0 RRF hit");
assert_eq!(hits[0].score, 1.0);
apply_status_multipliers(&mut hits, false);
assert!((hits[0].score - 0.5).abs() < 1e-6, "1.0 squashes to 0.5");
enforce_min_score_floor(&mut hits, 0.7);
assert!(
hits.is_empty(),
"0.5 post-multiplier score must not clear a 0.7 floor"
);
}
#[test]
fn min_score_floor_keeps_hit_at_or_above_threshold_after_multiplier() {
let mut hits = vec![make_hit("atom-1", Some("reviewed"), 0.0)];
fuse_ann_hits(&mut hits, &[], 0.4);
assert_eq!(hits.len(), 1, "fusion stage must admit the 1.0 RRF hit");
apply_status_multipliers(&mut hits, false);
let squashed = hits[0].score;
enforce_min_score_floor(&mut hits, 0.4);
assert_eq!(
hits.len(),
1,
"0.5 post-multiplier score clears a 0.4 floor"
);
assert_eq!(hits[0].id, "atom-1");
assert!(hits[0].score >= 0.4);
assert_eq!(hits[0].score, squashed, "floor must not rewrite scores");
}
#[test]
fn min_score_floor_zero_is_noop_on_multiplier_survivors() {
let build = || {
let mut hits = vec![
make_hit("atom-1", Some("reviewed"), 0.9),
make_hit("atom-2", Some("draft"), 0.6),
make_hit("atom-3", Some("deprecated"), 0.8),
];
apply_status_multipliers(&mut hits, false);
hits
};
let before = build();
let mut after = build();
enforce_min_score_floor(&mut after, 0.0);
let ids_before: Vec<&str> = before.iter().map(|h| h.id.as_str()).collect();
let ids_after: Vec<&str> = after.iter().map(|h| h.id.as_str()).collect();
assert_eq!(ids_after, ids_before);
for (a, b) in after.iter().zip(before.iter()) {
assert_eq!(a.score, b.score);
}
}
#[tokio::test]
async fn body_line_counts_degrade_to_none_under_expired_read_deadline() {
let runtime = KhiveRuntime::memory().expect("in-memory runtime");
let atom_ids = vec!["10000000-0000-0000-0000-000000000001".to_owned()];
let degraded = khive_storage::scope_request_read_deadline(
std::time::Duration::ZERO,
load_atom_body_line_counts(&runtime, "local", &atom_ids),
)
.await;
assert!(
matches!(degraded, Ok(None)),
"an expired read deadline must degrade body-line metadata to \
None, never error the search; got {degraded:?}"
);
let healthy = load_atom_body_line_counts(&runtime, "local", &atom_ids)
.await
.expect("undeadlined lookup must succeed");
assert_eq!(
healthy.and_then(|counts| counts.get(&atom_ids[0]).copied()),
Some(0),
"control: without a deadline the lookup returns real counts"
);
}
}