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(),
db_path: None,
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(),
db_path: None,
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(),
db_path: Some(db_path),
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_atoms",
json!({
"atoms": [{
"slug": "degrade-compose-atom",
"name": "Degrade Compose Atom",
"content": "attention mechanism self-attention transformer encoder decoder positional embedding layer normalization residual connection feed forward dense sparse retrieval vector nearest neighbor"
}]
}),
)
.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::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}"
);
}
#[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 serving throughput latency batching cache scheduling gpu utilization request queuing parallelism autoscaling 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)
);
}