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::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
const MODEL_KEY: &str = "all-minilm-l6-v2";
pub(super) 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,
query_embedded: AtomicBool,
}
#[async_trait]
impl EmbeddingService for ControlledRankingService {
async fn embed(
&self,
texts: &[String],
_model: EmbeddingModel,
) -> Result<Vec<Vec<f32>>, EmbedError> {
if self.fail_fresh_rerank && self.query_embedded.swap(false, Ordering::AcqRel) {
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())
}
async fn embed_query(
&self,
texts: &[String],
model: EmbeddingModel,
) -> Result<Vec<Vec<f32>>, EmbedError> {
let result = self.embed(texts, model).await;
if result.is_ok() {
self.query_embedded.store(true, Ordering::Release);
}
result
}
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,
query_embedded: AtomicBool::new(false),
}))
}
}
fn rt_with_fake_embedder() -> KhiveRuntime {
let rt = KhiveRuntime::new(RuntimeConfig {
wal_ceiling_bytes: 0,
wal_ceiling_configured_bytes: 0,
wal_ceiling_source: Default::default(),
wal_ceiling_env_raw: None,
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![],
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,
exec: Default::default(),
..khive_runtime::RuntimeConfig::no_embeddings()
})
.expect("in-memory runtime");
rt.register_embedder(FakeDimProvider);
rt
}
fn rt_with_controlled_ranking(fail_fresh_rerank: bool) -> KhiveRuntime {
let rt = KhiveRuntime::new(RuntimeConfig {
wal_ceiling_bytes: 0,
wal_ceiling_configured_bytes: 0,
wal_ceiling_source: Default::default(),
wal_ceiling_env_raw: None,
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![],
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,
exec: Default::default(),
..khive_runtime::RuntimeConfig::no_embeddings()
})
.expect("in-memory runtime");
rt.register_embedder(ControlledRankingProvider { fail_fresh_rerank });
rt
}
pub(super) fn file_rt_with_fake_embedder(db_path: std::path::PathBuf) -> KhiveRuntime {
let rt = KhiveRuntime::new(RuntimeConfig {
wal_ceiling_bytes: 0,
wal_ceiling_configured_bytes: 0,
wal_ceiling_source: Default::default(),
wal_ceiling_env_raw: None,
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: 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,
exec: Default::default(),
..khive_runtime::RuntimeConfig::no_embeddings()
})
.expect("file-backed runtime");
rt.register_embedder(FakeDimProvider);
rt
}
pub(super) 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
}
async fn lexical_timeout_fixture(
atoms: Vec<serde_json::Value>,
domain: serde_json::Value,
) -> (KhiveRuntime, VerbRegistry) {
let rt = rt_with_fake_embedder();
let registry = build_registry(&rt);
if !atoms.is_empty() {
registry
.dispatch("knowledge.upsert_atoms", json!({"atoms": atoms}))
.await
.expect("upsert member atoms");
}
registry
.dispatch("knowledge.upsert_domains", json!({"domains": [domain]}))
.await
.expect("upsert domain");
registry
.dispatch("knowledge.index", json!({"rebuild_ann": false}))
.await
.expect("index");
(rt, 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}"
);
let reranked = KnowledgeHandlers::search(
&rt,
&token,
json!({ "query": "lexicalsentinel", "rerank": true }),
&ann,
)
.await
.expect("cold ANN must not block stored-vector rerank");
assert_eq!(
reranked["rerank_provenance"]["stored_vector_lookup"], "supported",
"result: {reranked}"
);
assert!(
reranked["rerank_provenance"]["from_stored"]
.as_u64()
.unwrap_or_default()
> 0,
"cold serving ANN must still read persisted candidate vectors: {reranked}"
);
}
#[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 matching domains found for auto-suggest.",
"compose must skip the zero-member domain while preserving the signal; got: {result}"
);
}
#[tokio::test]
async fn auto_compose_skips_zero_size_suggested_domains() {
let rt = KhiveRuntime::memory().expect("in-memory runtime");
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_atoms",
json!({"atoms": [{
"slug": "compose-live-member",
"name": "Compose Live Member",
"content": "Stored text supplies a valid live member with a measurable cost for each domain while the separate domain descriptions determine candidate relevance and ordering.",
"finalized": true
}]}),
)
.await
.expect("upsert live member");
registry
.dispatch(
"knowledge.upsert_domains",
json!({"domains": [
{
"slug": "compose-empty-domain",
"name": "Compose Empty Domain",
"description": "Lexical domain member sizing search uses the live content of member atoms to calculate the estimated token cost before a fold selection admits the domain into its budget.",
"members": []
},
{
"slug": "compose-populated-domain",
"name": "Compose Populated Domain",
"description": "Lexical domain member sizing search uses the live content of member atoms to calculate the estimated token cost before a fold selection admits the domain into its budget.",
"members": ["compose-live-member"]
}
]}),
)
.await
.expect("upsert empty and populated domains");
let response = registry
.dispatch(
"knowledge.compose",
json!({"query": "explain lexical domain member sizing search and token cost for automatic composition"}),
)
.await
.expect("auto-compose succeeds");
let domains = response["data"]["domains"].as_array().expect("domains");
assert_eq!(domains.len(), 1, "got: {response}");
assert_eq!(domains[0]["slug"], "compose-populated-domain");
assert_eq!(response["data"]["count"], 1, "got: {response}");
assert_eq!(response["data"]["atoms"][0]["slug"], "compose-live-member");
let explicit = registry
.dispatch(
"knowledge.compose",
json!({"query": "empty domain", "domain_ids": ["compose-empty-domain"]}),
)
.await
.expect("explicit empty-domain request remains supported");
assert_eq!(
explicit["data"]["markdown"], "# Knowledge Briefing\n\nNo atoms found.",
"the candidate skip must not apply to explicit domain ids: {explicit}"
);
}
#[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(start_paused = true)]
async fn lexical_timeout_degrades_suggest_to_ann_backed_results() {
let (rt, _registry) = lexical_timeout_fixture(
Vec::new(),
json!({
"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 reader times out during this regression test",
"members": []
}),
)
.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 result = crate::knowledge::lexical_timeout::tests::with_timeout(
vec![crate::knowledge::lexical_timeout::LexicalPhase::ReaderOpen],
std::time::Duration::from_millis(1),
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_eq!(
result["total"], 1,
"ANN must survive lexical timeout: {result}"
);
assert_eq!(
result["results"][0]["name"],
"Degrade Lexical Timeout Domain"
);
let surfaced: Vec<&str> = result["results"]
.as_array()
.into_iter()
.flatten()
.chain(
result["degraded"]["member_sizing_timeout"]["excluded"]
.as_array()
.into_iter()
.flatten(),
)
.filter_map(|hit| hit["name"].as_str())
.collect();
assert_eq!(
surfaced,
vec!["Degrade Lexical Timeout Domain"],
"the only vector-backed candidate must be surfaced exactly once, served or withheld; got: {result}"
);
for hit in result["results"].as_array().into_iter().flatten() {
assert!(
hit["size"].is_u64(),
"every served result carries a measured size; got: {result}"
);
}
}
#[tokio::test(start_paused = true)]
async fn lexical_timeout_reports_member_sizing_as_unmeasured_not_zero() {
let (rt, registry) = lexical_timeout_fixture(
vec![json!({
"slug": "degrade-sizing-member-atom",
"name": "Degrade Sizing Member Atom",
"finalized": true,
"content": "enough body content to price a non-zero token size for the owning domain if member sizing ever ran to completion"
})],
json!({
"slug": "degrade-sizing-domain",
"name": "Degrade Sizing Domain",
"description": "a domain with a real member atom, so a real (non-zero) size would be computed if member sizing ran, proving a timeout is reported as unmeasured rather than a coincidental zero",
"members": ["degrade-sizing-member-atom"]
}),
)
.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 result = crate::knowledge::search::with_member_sizing_read_timeout(
crate::knowledge::lexical_timeout::tests::with_timeout(
vec![crate::knowledge::lexical_timeout::LexicalPhase::ReaderOpen],
std::time::Duration::from_millis(1),
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, "got: {result}");
assert!(
result["results"].as_array().is_some_and(Vec::is_empty),
"an unmeasured domain must be withheld from `results` entirely, never \
left in with size 0 or null; got: {result}"
);
let excluded = result["degraded"]["member_sizing_timeout"]["excluded"]
.as_array()
.cloned()
.unwrap_or_default();
assert_eq!(
excluded.len(),
1,
"the degradation entry must list the excluded domain; got: {result}"
);
assert_eq!(excluded[0]["rank"], 1, "got: {result}");
assert_eq!(excluded[0]["name"], "Degrade Sizing Domain");
assert!(
excluded[0]["id"].is_string()
&& excluded[0]["name"].is_string()
&& excluded[0]["score"].is_number()
&& excluded[0].get("size").is_none(),
"an excluded entry must carry id/name/rank/score for reference, and no \
size; got: {result}"
);
registry
.dispatch(
"knowledge.fold",
json!({ "candidates": result["results"].clone(), "budget": 10_000 }),
)
.await
.expect(
"suggest's results must feed fold unmodified even when a domain was \
excluded for an unmeasured size (issue #105 passthrough)",
);
}
#[tokio::test(start_paused = true)]
async fn suggest_results_under_a_member_sizing_timeout_still_pass_through_fold() {
let (rt, registry) = lexical_timeout_fixture(
vec![json!({
"slug": "degrade-sizing-passthrough-atom",
"name": "Degrade Sizing Passthrough Atom",
"finalized": true,
"content": "enough body content to price a non-zero token size for the owning domain if member sizing ever ran to completion"
})],
json!({
"slug": "degrade-sizing-passthrough-domain",
"name": "Degrade Sizing Passthrough Domain",
"description": "a domain with a real member atom, so a real (non-zero) size would be computed if member sizing ran, proving a timeout is reported as unmeasured rather than a coincidental zero",
"members": ["degrade-sizing-passthrough-atom"]
}),
)
.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 result = crate::knowledge::search::with_member_sizing_read_timeout(
crate::knowledge::lexical_timeout::tests::with_timeout(
vec![crate::knowledge::lexical_timeout::LexicalPhase::ReaderOpen],
std::time::Duration::from_millis(1),
KnowledgeHandlers::suggest(&rt, &token, json!({ "query": query }), &ann),
),
)
.await
.expect("suggest must not Err on a lexical-stage read timeout");
assert!(
result["degraded"]["member_sizing_timeout"]["excluded"]
.as_array()
.is_some_and(|excluded| !excluded.is_empty()),
"the degraded scenario must produce at least one excluded domain; got: {result}"
);
registry
.dispatch(
"knowledge.fold",
json!({ "candidates": result["results"].clone(), "budget": 10_000 }),
)
.await
.expect("suggest's results must feed fold unmodified (issue #105 passthrough)");
}
#[tokio::test]
async fn suggest_member_sizing_serves_a_domain_with_only_a_deleted_member_at_zero() {
let rt = KhiveRuntime::memory().expect("in-memory runtime");
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_atoms",
json!({"atoms": [{
"slug": "sizing-deleted-member",
"name": "Sizing Deleted Member",
"content": "A live member body with enough content to have a nonzero estimated token cost before the atom is soft deleted.",
"finalized": true
}]}),
)
.await
.expect("upsert member atom");
registry
.dispatch(
"knowledge.upsert_domains",
json!({"domains": [{
"slug": "sizing-measured-domain",
"name": "Sizing Measured Domain",
"description": "Lexical domain member sizing search uses the live content of member atoms to calculate the estimated token cost before a fold selection admits the domain into its budget.",
"members": ["sizing-deleted-member"]
}]}),
)
.await
.expect("upsert domain");
let token = rt.authorize(Namespace::local()).expect("authorize");
let ann = vamana::new_shared();
let params = json!({"query": "lexical domain member sizing search", "limit": 1});
let baseline = KnowledgeHandlers::suggest(&rt, &token, params.clone(), &ann)
.await
.expect("suggest with live member");
assert_eq!(baseline["total"], 1, "got: {baseline}");
assert!(baseline["results"][0]["size"].as_u64().unwrap_or(0) > 0);
assert_eq!(baseline["results"][0]["members"], 1, "got: {baseline}");
let deleted = registry
.dispatch(
"knowledge.delete_atoms",
json!({"ids": ["sizing-deleted-member"]}),
)
.await
.expect("soft-delete member atom");
assert_eq!(deleted["deleted"], 1, "got: {deleted}");
let result = KnowledgeHandlers::suggest(&rt, &token, params, &ann)
.await
.expect("suggest with deleted member");
assert_eq!(result["total"], 1, "got: {result}");
assert_eq!(result["results"][0]["id"], baseline["results"][0]["id"]);
assert_eq!(result["results"][0]["size"], 0, "got: {result}");
assert_eq!(result["results"][0]["members"], 0, "got: {result}");
assert!(
result["degraded"].get("member_sizing_timeout").is_none(),
"a measured zero must not be excluded; got: {result}"
);
assert_ne!(result["degraded"]["lexical_timeout"], true);
registry
.dispatch(
"knowledge.fold",
json!({"candidates": result["results"], "budget": 10_000}),
)
.await
.expect("member counts must preserve the unmodified suggest-to-fold input");
}
#[tokio::test]
async fn suggest_member_sizing_counts_only_live_members() {
const LIVE_NAME: &str = "Sizing Live Member";
const LIVE_BODY: &str = "Stored text supplies a valid live member with a measurable cost for each domain while the separate domain descriptions determine candidate relevance and ordering.";
let rt = KhiveRuntime::memory().expect("in-memory runtime");
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_atoms",
json!({"atoms": [
{
"slug": "sizing-live-member",
"name": LIVE_NAME,
"content": LIVE_BODY,
"finalized": true
},
{
"slug": "sizing-removed-member",
"name": "Sizing Removed Member",
"content": LIVE_BODY,
"finalized": true
}
]}),
)
.await
.expect("upsert members");
registry
.dispatch(
"knowledge.upsert_domains",
json!({"domains": [{
"slug": "sizing-mixed-domain",
"name": "Sizing Mixed Domain",
"description": "Lexical domain member sizing search uses the live content of member atoms to calculate the estimated token cost before a fold selection admits the domain into its budget.",
"members": ["sizing-live-member", "sizing-removed-member"]
}]}),
)
.await
.expect("upsert domain");
let deleted = registry
.dispatch(
"knowledge.delete_atoms",
json!({"ids": ["sizing-removed-member"]}),
)
.await
.expect("delete one member");
assert_eq!(deleted["deleted"], 1);
let token = rt.authorize(Namespace::local()).expect("authorize");
let result = KnowledgeHandlers::suggest(
&rt,
&token,
json!({"query": "lexical domain member sizing search", "limit": 1}),
&vamana::new_shared(),
)
.await
.expect("suggest mixed membership");
assert_eq!(result["total"], 1, "got: {result}");
assert_eq!(result["results"][0]["members"], 1, "got: {result}");
assert_eq!(
result["results"][0]["size"],
crate::knowledge::util::estimate_compose_item_tokens(LIVE_NAME, LIVE_BODY),
"deleted members must not contribute to the measured cost; got: {result}"
);
assert!(result["degraded"].get("member_sizing_timeout").is_none());
}
#[tokio::test]
async fn suggest_member_sizing_counts_each_distinct_live_atom_once() {
const NAME: &str = "Sizing Shared Member Name";
const BODY: &str = "Stored text supplies a valid live member with a measurable cost for each domain while the separate domain descriptions determine candidate relevance and ordering.";
let rt = KhiveRuntime::memory().expect("in-memory runtime");
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_atoms",
json!({"atoms": [
{
"slug": "sizing-distinct-member-a",
"name": NAME,
"content": BODY,
"finalized": true
},
{
"slug": "sizing-distinct-member-b",
"name": NAME,
"content": BODY,
"finalized": true
}
]}),
)
.await
.expect("upsert distinct atoms with identical names and content");
registry
.dispatch(
"knowledge.upsert_domains",
json!({"domains": [
{
"slug": "sizing-repeated-domain",
"name": "Sizing Repeated Domain",
"description": "Lexical domain member sizing search uses the live content of member atoms to calculate the estimated token cost before a fold selection admits the domain into its budget.",
"members": ["sizing-distinct-member-a", "sizing-distinct-member-a"]
},
{
"slug": "sizing-distinct-domain",
"name": "Sizing Distinct Domain",
"description": "Lexical domain member sizing search uses the live content of member atoms to calculate the estimated token cost before a fold selection admits the domain into its budget.",
"members": ["sizing-distinct-member-a", "sizing-distinct-member-b", "sizing-distinct-member-a"]
}
]}),
)
.await
.expect("upsert repeated and distinct membership");
let token = rt.authorize(Namespace::local()).expect("authorize");
let result = KnowledgeHandlers::suggest(
&rt,
&token,
json!({"query": "lexical domain member sizing search", "limit": 2}),
&vamana::new_shared(),
)
.await
.expect("suggest domains with repeated and distinct members");
assert_eq!(result["total"], 2, "got: {result}");
let results = result["results"].as_array().expect("suggest results");
let single_atom_size = crate::knowledge::util::estimate_compose_item_tokens(NAME, BODY);
for (name, expected_members) in [("Sizing Repeated Domain", 1), ("Sizing Distinct Domain", 2)] {
let domain = results
.iter()
.find(|domain| domain["name"] == name)
.expect("domain is served");
assert_eq!(domain["members"], expected_members, "got: {result}");
assert_eq!(
domain["size"],
single_atom_size * expected_members,
"got: {result}"
);
}
assert!(result["degraded"].get("member_sizing_timeout").is_none());
}
#[tokio::test]
async fn suggest_member_sizing_serves_empty_or_missing_members_at_zero() {
for members in [json!([]), json!(["absent-member"])] {
let rt = KhiveRuntime::memory().expect("in-memory runtime");
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_domains",
json!({"domains": [{
"slug": "sizing-empty-domain",
"name": "Sizing Empty Domain",
"description": "Lexical domain member sizing search uses the live content of member atoms to calculate the estimated token cost before a fold selection admits the domain into its budget.",
"members": members
}]}),
)
.await
.expect("upsert domain without live members");
let token = rt.authorize(Namespace::local()).expect("authorize");
let result = KnowledgeHandlers::suggest(
&rt,
&token,
json!({"query": "lexical domain member sizing search", "limit": 1}),
&vamana::new_shared(),
)
.await
.expect("suggest domain without live members");
assert_eq!(result["total"], 1, "got: {result}");
assert_eq!(result["results"][0]["name"], "Sizing Empty Domain");
assert_eq!(result["results"][0]["size"], 0, "got: {result}");
assert_eq!(result["results"][0]["members"], 0, "got: {result}");
assert!(result["degraded"].get("member_sizing_timeout").is_none());
assert_ne!(result["degraded"]["lexical_timeout"], true);
}
}
#[tokio::test]
async fn suggest_member_sizing_withholds_a_missing_domain_with_rank_and_score() {
let rt = KhiveRuntime::memory().expect("in-memory runtime");
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_domains",
json!({"domains": [
{
"slug": "sizing-kept-domain",
"name": "Sizing Kept Domain",
"description": "Lexical domain member sizing search keeps measured domains available for token budget selection, because a fold budget can only admit domains whose compose cost is known.",
"members": []
},
{
"slug": "sizing-missing-domain",
"name": "Sizing Missing Domain",
"description": "Lexical domain member sizing search withholds domains whose canonical row cannot be measured and lists them under the degraded exclusion key with their rank and score.",
"members": []
}
]}),
)
.await
.expect("upsert domains");
let token = rt.authorize(Namespace::local()).expect("authorize");
let ann = vamana::new_shared();
let params = json!({"query": "lexical domain member sizing search", "limit": 2});
let baseline = KnowledgeHandlers::suggest(&rt, &token, params.clone(), &ann)
.await
.expect("suggest with both domain rows");
assert_eq!(baseline["total"], 2, "got: {baseline}");
let baseline_hits = baseline["results"].as_array().expect("baseline results");
let missing_rank = baseline_hits
.iter()
.position(|hit| hit["name"] == "Sizing Missing Domain")
.expect("domain to remove");
let missing = &baseline_hits[missing_rank];
let kept = baseline_hits
.iter()
.find(|hit| hit["name"] == "Sizing Kept Domain")
.expect("domain to retain");
let access = rt.sql();
let mut writer = access.writer().await.expect("writer");
let removed = writer
.execute(khive_storage::types::SqlStatement {
sql: "DELETE FROM knowledge_domains WHERE namespace = 'local' AND id = ?1".into(),
params: vec![khive_storage::types::SqlValue::Text(
missing["id"].as_str().expect("domain id").to_owned(),
)],
label: None,
})
.await
.expect("remove canonical domain row");
assert_eq!(removed, 1);
drop(writer);
let result = KnowledgeHandlers::suggest(&rt, &token, params, &ann)
.await
.expect("suggest with a missing domain row");
assert_eq!(result["results"], json!([kept]), "got: {result}");
assert_eq!(result["total"], 1, "got: {result}");
assert_eq!(
result["degraded"]["member_sizing_timeout"]["excluded"],
json!([{
"id": missing["id"],
"name": missing["name"],
"rank": missing_rank + 1,
"score": missing["score"]
}]),
"the missing domain must be withheld with its original rank and score, without a size; got: {result}"
);
assert_ne!(result["degraded"]["lexical_timeout"], true);
}
#[tokio::test]
async fn search_still_reranks_after_a_lexical_stage_only_timeout() {
let rt = rt_with_fake_embedder();
let registry = build_registry(&rt);
registry
.dispatch(
"knowledge.upsert_atoms",
json!({
"atoms": [{
"slug": "degrade-lexical-budget-atom",
"name": "Degrade Lexical Budget Atom",
"finalized": true,
"content": "lexicalbudgetsentinel 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");
crate::knowledge::search::seed_low_overlap_corpus(&rt, 1_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 stage_budget =
std::time::Duration::from_millis(crate::knowledge::search::LEXICAL_STAGE_BUDGET_MS * 4);
assert!(stage_budget < std::time::Duration::from_secs(30));
tokio::time::pause();
let result =
khive_storage::scope_request_read_deadline(std::time::Duration::from_secs(30), async {
let result = crate::knowledge::search::with_fts_deadline_advance_after_term(
1,
stage_budget,
KnowledgeHandlers::search(&rt, &token, json!({ "query": query }), &ann),
)
.await;
assert!(khive_storage::ensure_request_read_active("test.search_stage").is_ok());
result
})
.await
.expect("search must not Err on a lexical-stage-only timeout");
assert_eq!(
result["degraded"]["lexical_timeout"], true,
"search must flag degraded.lexical_timeout when only the lexical \
stage's own budget expires; got: {result}"
);
assert!(
result["total"].as_u64().unwrap_or(0) > 0,
"the seeded, ANN-indexed atom must still surface as a candidate; got: {result}"
);
assert_eq!(
result["rerank_provenance"]["stored_vector_lookup"], "supported",
"rerank must read persisted vectors after a lexical-only timeout; got: {result}"
);
assert!(
result["rerank_provenance"]["from_stored"]
.as_u64()
.unwrap_or(0)
> 0,
"rerank must use the indexed atom's stored vector after a lexical-only timeout; got: {result}"
);
assert!(
result["results"].as_array().is_some_and(|hits| hits
.iter()
.any(|hit| hit["score_provenance"]["embedding_rerank"].as_bool() == Some(true))),
"a result must carry the applied embedding-rerank flag; got: {result}"
);
}
include!("ann_degrade_tests/suggest_lexical_timeout.rs");
#[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:?}"
);
}