use crate::knowledge::{vamana, KnowledgeHandlers};
use async_trait::async_trait;
use khive_pack_kg::KgPack;
use khive_runtime::{
AllowAllGate, BackendId, EmbedderProvider, KhiveRuntime, Namespace, RuntimeConfig,
VerbRegistry, VerbRegistryBuilder,
};
use lattice_embed::{EmbedError, EmbeddingModel, EmbeddingService};
use serde_json::json;
use std::sync::Arc;
const MODEL_KEY: &str = "all-minilm-l6-v2";
const DIM: usize = 384;
struct FakeDimService;
#[async_trait]
impl EmbeddingService for FakeDimService {
async fn embed(
&self,
texts: &[String],
_model: EmbeddingModel,
) -> Result<Vec<Vec<f32>>, EmbedError> {
Ok(texts
.iter()
.enumerate()
.map(|(i, _)| {
let v = (i + 1) as f32;
let norm = (DIM as f32 * v * v).sqrt();
vec![v / norm; DIM]
})
.collect())
}
fn supports_model(&self, _model: EmbeddingModel) -> bool {
true
}
fn name(&self) -> &'static str {
"fake-dim"
}
}
struct FakeDimProvider;
#[async_trait]
impl EmbedderProvider for FakeDimProvider {
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(FakeDimService))
}
}
struct ControlledRankingService {
fail_fresh_rerank: bool,
}
#[async_trait]
impl EmbeddingService for ControlledRankingService {
async fn embed(
&self,
texts: &[String],
_model: EmbeddingModel,
) -> Result<Vec<Vec<f32>>, EmbedError> {
if self.fail_fresh_rerank
&& texts.len() > 1
&& texts[0].contains("speculative decoding inference acceleration")
{
return Err(EmbedError::InferenceFailed(
"controlled fresh-rerank failure".into(),
));
}
Ok(texts
.iter()
.map(|text| {
let lower = text.to_lowercase();
if lower.contains("semantic_target")
|| lower.contains("speculative decoding inference acceleration")
{
let mut vector = vec![0.0; DIM];
vector[0] = 1.0;
vector
} else if lower.contains("lexical_collision") {
let mut vector = vec![0.0; DIM];
vector[1] = 1.0;
vector
} else {
vec![1.0 / (DIM as f32).sqrt(); DIM]
}
})
.collect())
}
fn supports_model(&self, _model: EmbeddingModel) -> bool {
true
}
fn name(&self) -> &'static str {
"controlled-ranking"
}
}
struct ControlledRankingProvider {
fail_fresh_rerank: bool,
}
#[async_trait]
impl EmbedderProvider for ControlledRankingProvider {
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(ControlledRankingService {
fail_fresh_rerank: self.fail_fresh_rerank,
}))
}
}
fn rt_with_fake_embedder() -> KhiveRuntime {
let rt = KhiveRuntime::new(RuntimeConfig {
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![],
gate: Arc::new(AllowAllGate),
packs: vec!["kg".to_string(), "knowledge".to_string()],
backend_id: BackendId::main(),
brain_profile: None,
visible_namespaces: vec![],
allowed_outbound_namespaces: vec![],
actor_id: None,
})
.expect("in-memory runtime");
rt.register_embedder(FakeDimProvider);
rt
}
fn rt_with_controlled_ranking(fail_fresh_rerank: bool) -> KhiveRuntime {
let rt = KhiveRuntime::new(RuntimeConfig {
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![],
gate: Arc::new(AllowAllGate),
packs: vec!["kg".to_string(), "knowledge".to_string()],
backend_id: BackendId::main(),
brain_profile: None,
visible_namespaces: vec![],
allowed_outbound_namespaces: vec![],
actor_id: None,
})
.expect("in-memory runtime");
rt.register_embedder(ControlledRankingProvider { fail_fresh_rerank });
rt
}
fn file_rt_with_fake_embedder(db_path: std::path::PathBuf) -> KhiveRuntime {
let rt = KhiveRuntime::new(RuntimeConfig {
git_write: Default::default(),
display_timezone: khive_runtime::config::resolve_default_display_timezone(),
events_split: None,
db_path: Some(db_path),
blob_hydration_bytes: khive_runtime::DEFAULT_BLOB_HYDRATION_BYTES,
default_namespace: Namespace::local(),
embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
additional_embedding_models: vec![],
gate: Arc::new(AllowAllGate),
packs: vec!["kg".to_string(), "knowledge".to_string()],
backend_id: BackendId::main(),
brain_profile: None,
visible_namespaces: vec![],
allowed_outbound_namespaces: vec![],
actor_id: None,
})
.expect("file-backed runtime");
rt.register_embedder(FakeDimProvider);
rt
}
fn build_registry(rt: &KhiveRuntime) -> VerbRegistry {
let mut builder = VerbRegistryBuilder::new();
builder.register(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
}
struct TimeoutOverrideReset;
impl Drop for TimeoutOverrideReset {
fn drop(&mut self) {
vamana::set_warm_wait_timeout_override_ms(0);
}
}
static TIMEOUT_OVERRIDE_SERIAL: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
#[tokio::test]
async fn search_preserves_timeout_fallback_policy() {
let _serial = TIMEOUT_OVERRIDE_SERIAL.lock().await;
vamana::set_warm_wait_timeout_override_ms(50);
let _reset = TimeoutOverrideReset;
let rt = rt_with_fake_embedder();
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_atoms",
json!({
"atoms": [{
"slug": "degrade-search-atom",
"name": "Degrade Search Atom",
"finalized": true,
"content": "lexicalsentinel transformer retrieval corpus benchmark search latency vector index nearest neighbor ranking fusion embedding cosine similarity attention encoder decoder positional normalization residual connection"
}]
}),
)
.await
.expect("upsert atom");
registry
.dispatch("knowledge.index", json!({ "rebuild_ann": false }))
.await
.expect("index");
let ann = vamana::new_shared();
let key = vamana::AnnKey::new("local", rt.default_embedder_name());
vamana::simulate_warming_in_flight(&ann, key);
let token = rt.authorize(Namespace::local()).expect("authorize");
let empty = KnowledgeHandlers::search(
&rt,
&token,
json!({ "query": "unfindablegossamer", "kind": "domain", "rerank": false }),
&ann,
)
.await
.expect("empty search must not Err");
assert_eq!(empty["total"], 0, "result: {empty}");
assert_eq!(empty["ann_unavailable"], true, "result: {empty}");
let lexical = KnowledgeHandlers::search(
&rt,
&token,
json!({ "query": "lexicalsentinel", "rerank": false }),
&ann,
)
.await
.expect("lexical fallback search must not Err");
assert!(
lexical["total"].as_u64().unwrap_or_default() > 0,
"lexical fallback must retain its hit; result: {lexical}"
);
assert!(
lexical.get("ann_unavailable").is_none(),
"search preserves its existing no-advisory policy when FTS found hits; result: {lexical}"
);
}
#[tokio::test]
async fn suggest_sets_ann_unavailable_when_warming_times_out() {
let _serial = TIMEOUT_OVERRIDE_SERIAL.lock().await;
vamana::set_warm_wait_timeout_override_ms(50);
let _reset = TimeoutOverrideReset;
let rt = rt_with_fake_embedder();
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_atoms",
json!({
"atoms": [{
"slug": "degrade-suggest-atom",
"name": "Degrade Suggest Atom",
"content": "transformer neural network attention mechanism self-attention encoder decoder positional embedding layer normalization residual connection feed forward dense sparse retrieval vector index"
}]
}),
)
.await
.expect("upsert atom");
registry
.dispatch("knowledge.index", json!({ "rebuild_ann": false }))
.await
.expect("index");
let ann = vamana::new_shared();
let model = rt.default_embedder_name().to_string();
let key = vamana::AnnKey::new("local", &model);
vamana::simulate_warming_in_flight(&ann, key);
let token = rt.authorize(Namespace::local()).expect("authorize");
let result = KnowledgeHandlers::suggest(
&rt,
&token,
json!({ "query": "machine learning neural network transformer attention" }),
&ann,
)
.await
.expect("suggest must not Err");
assert_eq!(
result.get("ann_unavailable").and_then(|v| v.as_bool()),
Some(true),
"suggest must carry ann_unavailable=true when ANN warming times out \
and FTS hits are empty; got: {result}"
);
}
#[tokio::test]
async fn compose_propagates_ann_unavailable_in_auto_mode() {
let _serial = TIMEOUT_OVERRIDE_SERIAL.lock().await;
vamana::set_warm_wait_timeout_override_ms(50);
let _reset = TimeoutOverrideReset;
let rt = rt_with_fake_embedder();
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_domains",
json!({
"domains": [{
"slug": "degrade-empty-compose-domain",
"name": "Degrade Empty Compose Domain",
"description": "machine learning neural network transformer attention architecture multi head self attention retrieval composition domain with intentionally empty membership for reliable production operations",
"members": []
}]
}),
)
.await
.expect("upsert empty domain");
registry
.dispatch("knowledge.index", json!({ "rebuild_ann": false }))
.await
.expect("index");
let ann = vamana::new_shared();
let model = rt.default_embedder_name().to_string();
let key = vamana::AnnKey::new("local", &model);
vamana::simulate_warming_in_flight(&ann, key);
let token = rt.authorize(Namespace::local()).expect("authorize");
let result = KnowledgeHandlers::compose(
&rt,
&token,
json!({
"query": "machine learning neural network transformer attention architecture multi head self attention"
}),
&ann,
std::collections::HashMap::new(),
)
.await
.expect("compose must not Err");
assert_eq!(
result
.get("data")
.and_then(|d| d.get("ann_unavailable"))
.and_then(|v| v.as_bool()),
Some(true),
"compose must propagate ann_unavailable=true from its internal suggest call; \
got: {result}"
);
assert_eq!(
result["data"]["markdown"], "# Knowledge Briefing\n\nNo atoms found.",
"the regression must exercise the empty-member early return; got: {result}"
);
}
#[tokio::test]
async fn warm_known_snapshots_loads_persisted_snapshot() {
let dir = tempfile::TempDir::new().expect("tempdir");
let rt = file_rt_with_fake_embedder(dir.path().join("test.db"));
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_atoms",
json!({
"atoms": [
{
"slug": "warm-snap-atom-a",
"name": "Warm Snapshot Atom A",
"content": "dense retrieval corpus benchmark search latency gradient descent vector index nearest neighbor ranking fusion pipeline embedding rerank cosine similarity unique warm78a"
},
{
"slug": "warm-snap-atom-b",
"name": "Warm Snapshot Atom B",
"content": "ranking fusion pipeline embedding rerank cosine similarity unique warm78b transformer attention mechanism self-attention encoder decoder positional feed forward dense neural network gradient"
}
]
}),
)
.await
.expect("upsert atoms");
let index_result = registry
.dispatch("knowledge.index", json!({ "rebuild_ann": true }))
.await
.expect("index with rebuild_ann=true");
let indexed = index_result
.get("indexed")
.and_then(|v| v.as_u64())
.unwrap_or(0);
assert!(
indexed >= 2,
"knowledge.index must embed at least 2 atoms for this test to be meaningful; \
got indexed={indexed}"
);
let ann = vamana::new_shared();
let model = rt.default_embedder_name().to_string();
let key = vamana::AnnKey::new("local", &model);
let dummy_query = vec![1.0f32 / (DIM as f32).sqrt(); DIM];
assert!(
vamana::search_loaded(&ann, &key, &dummy_query, 1)
.await
.is_none(),
"precondition: fresh SharedAnn must have no index loaded before warm_known_snapshots"
);
vamana::warm_known_snapshots(&rt, &ann).await;
assert!(
vamana::search_loaded(&ann, &key, &dummy_query, 1)
.await
.is_some(),
"search_loaded must return Some after warm_known_snapshots loads the snapshot; \
model={model}, key={key:?}"
);
}
#[tokio::test]
async fn suggest_reports_degraded_candidates_or_lexical_only_from_ranking_consequence() {
let _serial = TIMEOUT_OVERRIDE_SERIAL.lock().await;
vamana::set_warm_wait_timeout_override_ms(50);
let _reset = TimeoutOverrideReset;
for (fail_fresh_rerank, expected_mode, expected_winner) in [
(false, "ann_candidates_degraded", "Opaque Systems Domain"),
(
true,
"lexical_only",
"Speculative Decoding Methods for Inference",
),
] {
let rt = rt_with_controlled_ranking(fail_fresh_rerank);
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_domains",
json!({"domains": [
{
"slug": "degrade-semantic-domain",
"name": "Opaque Systems Domain",
"description": "SEMANTIC_TARGET speculative serving throughput decoding latency batching inference cache scheduling acceleration gpu utilization techniques request queuing large scale parallelism language aware autoscaling models deployment topology load balancing production workloads resource management observability reliability"
},
{
"slug": "degrade-lexical-collision",
"name": "Speculative Decoding Methods for Inference",
"description": "LEXICAL_COLLISION techniques for large language models emphasize decoding speculation, inference methods, acceleration strategies, model techniques, language processing, and unrelated terminology repeated for lexical matching"
}
]}),
)
.await
.expect("upsert domains");
registry
.dispatch("knowledge.index", json!({ "rebuild_ann": false }))
.await
.expect("index");
let ann = vamana::new_shared();
let key = vamana::AnnKey::new("local", rt.default_embedder_name());
vamana::simulate_warming_in_flight(&ann, key);
let token = rt.authorize(Namespace::local()).expect("authorize");
let result = KnowledgeHandlers::suggest(
&rt,
&token,
json!({
"query": "speculative decoding inference acceleration techniques for large language models"
}),
&ann,
)
.await
.expect("suggest must not Err");
assert_eq!(result["ann_unavailable"], true, "result: {result}");
assert_eq!(
result["degraded"]["mode"], expected_mode,
"result: {result}"
);
assert_eq!(
result["results"][0]["name"], expected_winner,
"result: {result}"
);
}
}
#[tokio::test]
async fn suggest_flags_degraded_no_match_when_hits_empty() {
let _serial = TIMEOUT_OVERRIDE_SERIAL.lock().await;
vamana::set_warm_wait_timeout_override_ms(50);
let _reset = TimeoutOverrideReset;
let rt = rt_with_fake_embedder();
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_atoms",
json!({
"atoms": [{
"slug": "degrade-suggest-atom-2",
"name": "Degrade Suggest Atom 2",
"content": "transformer neural network attention mechanism self-attention encoder decoder positional embedding layer normalization residual connection feed forward dense sparse retrieval vector index"
}]
}),
)
.await
.expect("upsert atom");
registry
.dispatch("knowledge.index", json!({ "rebuild_ann": false }))
.await
.expect("index");
let ann = vamana::new_shared();
let model = rt.default_embedder_name().to_string();
let key = vamana::AnnKey::new("local", &model);
vamana::simulate_warming_in_flight(&ann, key);
let token = rt.authorize(Namespace::local()).expect("authorize");
let result = KnowledgeHandlers::suggest(
&rt,
&token,
json!({ "query": "machine learning neural network transformer attention" }),
&ann,
)
.await
.expect("suggest must not Err");
assert_eq!(result.get("total").and_then(|v| v.as_u64()), Some(0));
assert_eq!(
result.get("ann_unavailable").and_then(|v| v.as_bool()),
Some(true)
);
let degraded = result
.get("degraded")
.unwrap_or_else(|| panic!("degraded object must be present; got: {result}"));
assert_eq!(
degraded.get("mode").and_then(|v| v.as_str()),
Some("no_match"),
"zero-hit degraded suggest must report mode=no_match, distinct from lexical_only; got: {result}"
);
assert_eq!(
degraded.get("cache_safe").and_then(|v| v.as_bool()),
Some(false)
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn lexical_timeout_degrades_suggest_to_ann_backed_results() {
let rt = rt_with_fake_embedder();
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_domains",
json!({"domains": [{
"slug": "degrade-lexical-timeout-domain",
"name": "Degrade Lexical Timeout Domain",
"description": "a domain seeded only so ANN has a real vector to serve from the fresh-tail scan path when the lexical fetch itself exceeds the request read deadline during this regression test",
"members": []
}]}),
)
.await
.expect("upsert domain");
registry
.dispatch("knowledge.index", json!({ "rebuild_ann": false }))
.await
.expect("index");
crate::knowledge::search::seed_low_overlap_corpus(&rt, 200_000, 20).await;
let ann = vamana::new_shared();
let token = rt.authorize(Namespace::local()).expect("authorize");
let query = "term0 term1 term2 term3 term4 term5 term6 term7";
let deadline = std::time::Duration::from_millis(200);
let result = khive_storage::scope_request_read_deadline(
deadline,
KnowledgeHandlers::suggest(&rt, &token, json!({ "query": query }), &ann),
)
.await
.expect("suggest must not Err on a lexical-stage read timeout");
assert_eq!(
result["degraded"]["lexical_timeout"], true,
"suggest must flag degraded.lexical_timeout when the lexical fetch times out; got: {result}"
);
assert!(
result["total"].as_u64().unwrap_or(0) > 0,
"ANN candidates fetched before the lexical stage must still produce results; got: {result}"
);
assert_eq!(
result["results"][0]["name"], "Degrade Lexical Timeout Domain",
"the only vector-backed candidate must be the seeded domain; got: {result}"
);
}
#[tokio::test]
async fn malformed_fts5_match_expression_still_errors() {
let rt = KhiveRuntime::memory().expect("in-memory runtime");
let sql = rt.sql();
let mut reader = sql.reader().await.expect("reader");
let result = reader
.query_all(khive_storage::types::SqlStatement {
sql: "SELECT a.rowid FROM fts_knowledge \
JOIN knowledge_atoms AS a ON a.rowid = fts_knowledge.rowid \
WHERE fts_knowledge MATCH ?1 AND fts_knowledge.namespace = ?2 \
ORDER BY bm25(fts_knowledge) LIMIT 10"
.to_string(),
params: vec![
khive_storage::types::SqlValue::Text("\"unterminated OR OR".to_string()),
khive_storage::types::SqlValue::Text("local".to_string()),
],
label: None,
})
.await;
let err = result.expect_err("a malformed FTS5 MATCH expression must not silently succeed");
assert!(
!matches!(err, khive_storage::StorageError::Timeout { .. }),
"a syntax error must not be classified as StorageError::Timeout, got {err:?}"
);
}