1use std::collections::HashMap;
4use std::sync::Mutex;
5
6use async_trait::async_trait;
7use serde_json::Value;
8use uuid::Uuid;
9
10use khive_brain_core::SectionPosteriorState;
11use khive_runtime::pack::{PackByIdResolver, PackRuntime};
12use khive_runtime::{
13 KhiveRuntime, Namespace, NamespaceToken, PackSchemaPlan, Resolved, RuntimeError, VerbRegistry,
14};
15use khive_storage::types::{SqlStatement, SqlValue};
16use khive_storage::{PhaseCancelledPayload, PhaseCompletedPayload, PhaseStartedPayload};
17use khive_types::{EventKind, HandlerDef, Pack};
18
19use crate::knowledge::util::{atom_from_row, atom_to_json, domain_from_row, domain_to_json};
20use crate::knowledge::vamana;
21use crate::knowledge::KnowledgeHandlers;
22use crate::vocab::{KNOWLEDGE_HANDLERS, KNOWLEDGE_SCHEMA_PLAN_STMTS};
23
24pub struct KnowledgePack {
26 pub(crate) runtime: KhiveRuntime,
27 pub(crate) ann: vamana::SharedAnn,
28 pub(crate) section_posteriors: Mutex<HashMap<String, SectionPosteriorState>>,
34 pub(crate) brain_profile: Option<String>,
40}
41
42impl Pack for KnowledgePack {
43 const NAME: &'static str = "knowledge";
44 const NOTE_KINDS: &'static [&'static str] = &[];
45 const ENTITY_KINDS: &'static [&'static str] = &[];
46 const BRAIN_CONSUMER_KINDS: &'static [&'static str] =
47 &[khive_brain_core::ConsumerKind::KnowledgeCompose.as_str()];
48 const HANDLERS: &'static [HandlerDef] = &KNOWLEDGE_HANDLERS;
49 const REQUIRES: &'static [&'static str] = &["kg"];
50 const SCHEMA_PLAN: Option<PackSchemaPlan> = Some(PackSchemaPlan {
51 pack: "knowledge",
52 statements: &KNOWLEDGE_SCHEMA_PLAN_STMTS,
53 });
54}
55
56impl KnowledgePack {
57 pub fn new(runtime: KhiveRuntime) -> Self {
59 Self::new_with_index_role(runtime, true)
60 }
61
62 pub fn new_with_index_role(runtime: KhiveRuntime, builds_corpus_indexes: bool) -> Self {
67 let brain_profile = runtime.config().brain_profile.clone();
68 Self {
69 runtime,
70 ann: vamana::new_shared_for_role(builds_corpus_indexes),
71 section_posteriors: Mutex::new(HashMap::new()),
72 brain_profile,
73 }
74 }
75}
76
77struct KnowledgePackFactory;
78
79impl khive_runtime::PackFactory for KnowledgePackFactory {
80 khive_runtime::pack_factory_metadata!(KnowledgePack);
81
82 fn create(&self, runtime: KhiveRuntime) -> Box<dyn khive_runtime::PackRuntime> {
83 Box::new(KnowledgePack::new_with_index_role(
84 runtime,
85 khive_runtime::daemon::is_warm_index_host(),
86 ))
87 }
88
89 fn create_resolver(
90 &self,
91 runtime: KhiveRuntime,
92 ) -> Option<Box<dyn khive_runtime::PackByIdResolver>> {
93 Some(Box::new(KnowledgePack::new(runtime)))
94 }
95}
96
97inventory::submit! { khive_runtime::PackRegistration(&KnowledgePackFactory) }
98
99#[async_trait]
100impl PackRuntime for KnowledgePack {
101 khive_runtime::pack_runtime_metadata!();
102
103 async fn warm(&self) {
104 if !self.runtime.is_read_only() {
108 crate::knowledge::vamana::warm_known_snapshots(&self.runtime, &self.ann).await;
109 crate::knowledge::vamana::start_rotation_watcher(&self.runtime, &self.ann);
110 }
111 if !self.runtime.default_embedder_name().is_empty() {
112 let runtime = self.runtime.clone();
113 let token = match runtime.authorize(khive_runtime::Namespace::local()) {
122 Ok(token) => Some(token),
123 Err(e) => {
124 tracing::warn!(
125 error = %e,
126 "knowledge_embedder_warm: failed to mint ADR-103 phase-span \
127 attribution token; warmup proceeds without telemetry"
128 );
129 None
130 }
131 };
132 tokio::spawn(async move {
133 if let Some(token) = &token {
134 khive_runtime::emit_phase_event(
135 &runtime,
136 token,
137 "knowledge.embedder_warm",
138 EventKind::PhaseStarted,
139 PhaseStartedPayload {
140 work_class: "warm".into(),
141 phase: "knowledge_embedder_warm".into(),
142 corpus_size: None,
143 },
144 )
145 .await;
146 }
147 let phase_start = std::time::Instant::now();
148 let cpu_start = khive_runtime::process_resource_usage();
149 let result = runtime.embed("__khive_knowledge_warm__").await;
150 if let Some(token) = &token {
151 let wall_us = phase_start.elapsed().as_micros() as i64;
152 let cpu_us = khive_runtime::cpu_delta_us(
153 cpu_start,
154 khive_runtime::process_resource_usage(),
155 );
156 match &result {
157 Err(e) if khive_runtime::is_benign_shutdown_cancellation(e) => {
158 khive_runtime::emit_phase_event(
159 &runtime,
160 token,
161 "knowledge.embedder_warm",
162 EventKind::PhaseCancelled,
163 PhaseCancelledPayload {
164 work_class: "warm".into(),
165 phase: "knowledge_embedder_warm".into(),
166 wall_us,
167 cpu_us,
168 },
169 )
170 .await;
171 }
172 _ => {
173 khive_runtime::emit_phase_event(
174 &runtime,
175 token,
176 "knowledge.embedder_warm",
177 EventKind::PhaseCompleted,
178 PhaseCompletedPayload {
179 work_class: "warm".into(),
180 phase: "knowledge_embedder_warm".into(),
181 wall_us,
182 cpu_us,
183 },
184 )
185 .await;
186 }
187 }
188 }
189 let _ = result;
190 });
191 }
192 }
193
194 async fn dispatch(
195 &self,
196 verb: &str,
197 params: Value,
198 registry: &VerbRegistry,
199 token: &NamespaceToken,
200 ) -> Result<Value, RuntimeError> {
201 match verb {
202 "knowledge.upsert_atoms" => {
203 KnowledgeHandlers::upsert_atoms(&self.runtime, token, params).await
204 }
205 "knowledge.upsert_domains" => {
206 KnowledgeHandlers::upsert_domains(&self.runtime, token, params).await
207 }
208 "knowledge.get" => KnowledgeHandlers::get(&self.runtime, token, params).await,
209 "knowledge.list" => KnowledgeHandlers::list(&self.runtime, token, params).await,
210 "knowledge.delete_atoms" => {
211 KnowledgeHandlers::delete_atoms(&self.runtime, token, params).await
212 }
213 "knowledge.stats" => KnowledgeHandlers::stats(&self.runtime, token, params).await,
214 "knowledge.eval_retrieval" => {
215 KnowledgeHandlers::eval_retrieval(&self.runtime, token, params, &self.ann).await
216 }
217 "knowledge.index" => {
218 KnowledgeHandlers::index(&self.runtime, token, params, &self.ann, None).await
219 }
220 "knowledge.fold" => KnowledgeHandlers::fold(&self.runtime, token, params).await,
221 "knowledge.search" => {
222 KnowledgeHandlers::search(&self.runtime, token, params, &self.ann).await
223 }
224 "knowledge.suggest" => {
225 KnowledgeHandlers::suggest(&self.runtime, token, params, &self.ann).await
226 }
227 "knowledge.compose" => {
228 let effective_token = match params.get("namespace") {
234 None => token.clone(),
235 Some(Value::String(ns_str)) => {
236 let ns = Namespace::parse(ns_str).map_err(|e| {
237 RuntimeError::InvalidInput(format!("invalid namespace {ns_str:?}: {e}"))
238 })?;
239 if &ns != token.namespace() {
240 return Err(RuntimeError::InvalidInput(
241 "knowledge.compose namespace does not match authorized token namespace"
242 .to_string(),
243 ));
244 }
245 token.with_namespace(ns)
249 }
250 Some(_) => {
251 return Err(RuntimeError::InvalidInput(
252 "invalid namespace: expected a string".to_string(),
253 ));
254 }
255 };
256 let type_weights = self
257 .resolve_compose_type_weights(registry, &effective_token)
258 .await;
259 KnowledgeHandlers::compose(
260 &self.runtime,
261 &effective_token,
262 params,
263 &self.ann,
264 type_weights,
265 )
266 .await
267 }
268 "knowledge.edit" => {
269 KnowledgeHandlers::edit(&self.runtime, token, params, &self.ann).await
270 }
271 "knowledge.import" => {
272 KnowledgeHandlers::import(&self.runtime, token, params, &self.ann).await
273 }
274 "knowledge.challenge" => {
275 KnowledgeHandlers::challenge(&self.runtime, token, params).await
276 }
277 "knowledge.adjudicate" => {
278 KnowledgeHandlers::adjudicate(&self.runtime, token, params).await
279 }
280 "knowledge.learn" => self.handle_learn(token, params).await,
281 "knowledge.cite" => self.handle_cite(token, params).await,
282 "knowledge.topic" => self.handle_topic(token, params).await,
283 "knowledge.feedback" => self.handle_feedback(token, params, registry).await,
284 _ => Err(RuntimeError::InvalidInput(format!(
285 "knowledge pack does not handle verb {verb:?}"
286 ))),
287 }
288 }
289}
290
291#[async_trait]
292impl PackByIdResolver for KnowledgePack {
293 async fn resolve_by_id(&self, id: Uuid) -> Result<Option<Resolved>, RuntimeError> {
299 let sql = self.runtime.sql();
300 let id_str = id.to_string();
301
302 let mut reader = sql
303 .reader()
304 .await
305 .map_err(|e| RuntimeError::Internal(format!("knowledge resolve_by_id reader: {e}")))?;
306
307 let domain_row = reader
309 .query_row(SqlStatement {
310 sql: khive_runtime::sql!("knowledge_resolver_live_domain").into(),
311 params: vec![SqlValue::Text(id_str.clone())],
312 label: Some("knowledge.resolve_by_id.domain".into()),
313 })
314 .await
315 .map_err(|e| {
316 RuntimeError::Internal(format!("knowledge resolve_by_id domain query: {e}"))
317 })?;
318
319 if let Some(row) = domain_row {
320 if let Some(domain) = domain_from_row(&row) {
321 return Ok(Some(Resolved::PackRecord {
322 pack: "knowledge".into(),
323 kind: "domain".into(),
324 data: domain_to_json(&domain),
325 }));
326 }
327 }
328
329 let atom_row = reader
331 .query_row(SqlStatement {
332 sql: khive_runtime::sql!("knowledge_resolver_live_atom").into(),
333 params: vec![SqlValue::Text(id_str)],
334 label: Some("knowledge.resolve_by_id.atom".into()),
335 })
336 .await
337 .map_err(|e| {
338 RuntimeError::Internal(format!("knowledge resolve_by_id atom query: {e}"))
339 })?;
340
341 if let Some(row) = atom_row {
342 if let Some(atom) = atom_from_row(&row) {
343 return Ok(Some(Resolved::PackRecord {
344 pack: "knowledge".into(),
345 kind: "atom".into(),
346 data: atom_to_json(&atom),
347 }));
348 }
349 }
350
351 Ok(None)
352 }
353
354 async fn resolve_by_id_including_deleted(
358 &self,
359 id: Uuid,
360 ) -> Result<Option<Resolved>, RuntimeError> {
361 let sql = self.runtime.sql();
362 let id_str = id.to_string();
363
364 let mut reader = sql.reader().await.map_err(|e| {
365 RuntimeError::Internal(format!(
366 "knowledge resolve_by_id_including_deleted reader: {e}"
367 ))
368 })?;
369
370 let domain_row = reader
371 .query_row(SqlStatement {
372 sql: khive_runtime::sql!("knowledge_resolver_domain_including_deleted").into(),
373 params: vec![SqlValue::Text(id_str.clone())],
374 label: Some("knowledge.resolve_by_id_incl_deleted.domain".into()),
375 })
376 .await
377 .map_err(|e| {
378 RuntimeError::Internal(format!(
379 "knowledge resolve_by_id_including_deleted domain query: {e}"
380 ))
381 })?;
382
383 if let Some(row) = domain_row {
384 if let Some(domain) = domain_from_row(&row) {
385 return Ok(Some(Resolved::PackRecord {
386 pack: "knowledge".into(),
387 kind: "domain".into(),
388 data: domain_to_json(&domain),
389 }));
390 }
391 }
392
393 let atom_row = reader
394 .query_row(SqlStatement {
395 sql: khive_runtime::sql!("knowledge_resolver_atom_including_deleted").into(),
396 params: vec![SqlValue::Text(id_str)],
397 label: Some("knowledge.resolve_by_id_incl_deleted.atom".into()),
398 })
399 .await
400 .map_err(|e| {
401 RuntimeError::Internal(format!(
402 "knowledge resolve_by_id_including_deleted atom query: {e}"
403 ))
404 })?;
405
406 if let Some(row) = atom_row {
407 if let Some(atom) = atom_from_row(&row) {
408 return Ok(Some(Resolved::PackRecord {
409 pack: "knowledge".into(),
410 kind: "atom".into(),
411 data: atom_to_json(&atom),
412 }));
413 }
414 }
415
416 Ok(None)
417 }
418
419 fn private_record_verbs(&self) -> &'static [&'static str] {
420 &[
421 "knowledge.upsert_atoms",
422 "knowledge.upsert_domains",
423 "knowledge.edit",
424 ]
425 }
426
427 async fn delete_by_id(&self, id: Uuid, hard: bool) -> Result<serde_json::Value, RuntimeError> {
433 let sql = self.runtime.sql();
434 let id_str = id.to_string();
435
436 let kind = match self.resolve_by_id_including_deleted(id).await? {
438 Some(Resolved::PackRecord { kind, .. }) => kind,
439 _ => {
440 return Err(RuntimeError::NotFound(format!(
441 "knowledge record not found: {id}"
442 )));
443 }
444 };
445
446 let now_us = std::time::SystemTime::now()
447 .duration_since(std::time::UNIX_EPOCH)
448 .unwrap_or_default()
449 .as_micros() as i64;
450
451 let mut writer = sql
452 .writer()
453 .await
454 .map_err(|e| RuntimeError::Internal(format!("knowledge delete_by_id writer: {e}")))?;
455
456 match kind.as_str() {
457 "domain" => {
458 if hard {
459 writer
463 .execute_batch(vec![
464 SqlStatement {
465 sql: khive_runtime::sql!("knowledge_atom_sections_delete").into(),
466 params: vec![SqlValue::Text(id_str.clone())],
467 label: Some(
468 "knowledge.delete_by_id.domain_mirror_sections.hard".into(),
469 ),
470 },
471 SqlStatement {
472 sql: khive_runtime::sql!("knowledge_atom_hard_delete").into(),
473 params: vec![SqlValue::Text(id_str.clone())],
474 label: Some("knowledge.delete_by_id.domain_mirror.hard".into()),
475 },
476 SqlStatement {
477 sql: khive_runtime::sql!("knowledge_domain_hard_delete").into(),
478 params: vec![SqlValue::Text(id_str.clone())],
479 label: Some("knowledge.delete_by_id.domain.hard".into()),
480 },
481 ])
482 .await
483 .map_err(|e| {
484 RuntimeError::Internal(format!(
485 "knowledge delete_by_id domain hard: {e}"
486 ))
487 })?;
488 } else {
489 writer
490 .execute(SqlStatement {
491 sql: khive_runtime::sql!("knowledge_domain_soft_delete").into(),
492 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
493 label: Some("knowledge.delete_by_id.domain.soft".into()),
494 })
495 .await
496 .map_err(|e| {
497 RuntimeError::Internal(format!(
498 "knowledge delete_by_id domain soft: {e}"
499 ))
500 })?;
501 writer
503 .execute(SqlStatement {
504 sql: khive_runtime::sql!("knowledge_atom_soft_delete").into(),
505 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
506 label: Some("knowledge.delete_by_id.domain_mirror.soft".into()),
507 })
508 .await
509 .map_err(|e| {
510 RuntimeError::Internal(format!(
511 "knowledge delete_by_id domain mirror soft: {e}"
512 ))
513 })?;
514 }
515 }
516 "atom" => {
517 if hard {
518 writer
520 .execute_batch(vec![
521 SqlStatement {
522 sql: khive_runtime::sql!("knowledge_atom_sections_delete").into(),
523 params: vec![SqlValue::Text(id_str.clone())],
524 label: Some("knowledge.delete_by_id.atom_sections.hard".into()),
525 },
526 SqlStatement {
527 sql: khive_runtime::sql!("knowledge_atom_hard_delete").into(),
528 params: vec![SqlValue::Text(id_str.clone())],
529 label: Some("knowledge.delete_by_id.atom.hard".into()),
530 },
531 ])
532 .await
533 .map_err(|e| {
534 RuntimeError::Internal(format!("knowledge delete_by_id atom hard: {e}"))
535 })?;
536 } else {
537 writer
538 .execute(SqlStatement {
539 sql: khive_runtime::sql!("knowledge_atom_soft_delete").into(),
540 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
541 label: Some("knowledge.delete_by_id.atom.soft".into()),
542 })
543 .await
544 .map_err(|e| {
545 RuntimeError::Internal(format!("knowledge delete_by_id atom soft: {e}"))
546 })?;
547 }
548 }
549 other => {
550 return Err(RuntimeError::Internal(format!(
551 "knowledge delete_by_id: unexpected kind {other:?}"
552 )));
553 }
554 }
555
556 Ok(serde_json::json!({
557 "deleted": true,
558 "id": id_str,
559 "kind": kind,
560 "hard": hard,
561 }))
562 }
563}
564
565#[cfg(test)]
566mod tests {
567 use khive_runtime::pack::PackRuntime;
568 use khive_runtime::{KhiveRuntime, Namespace, RuntimeConfig};
569 use lattice_embed::EmbeddingModel;
570
571 use super::KnowledgePack;
572
573 #[tokio::test]
582 async fn knowledge_warm_emits_no_phase_events_when_no_embedder_configured() {
583 let rt = KhiveRuntime::memory().expect("in-memory runtime");
584 let token = rt.authorize(Namespace::local()).expect("authorize local");
585 let event_store = rt.events(&token).expect("event store must be available");
586
587 let pack = KnowledgePack::new(rt.clone());
588 pack.warm().await;
589
590 let page = event_store
591 .query_events(
592 khive_storage::EventFilter::default(),
593 khive_storage::PageRequest {
594 limit: 10,
595 offset: 0,
596 },
597 )
598 .await
599 .expect("query events");
600
601 assert!(
602 page.items.is_empty(),
603 "no embedder configured -> KnowledgePack::warm() must emit zero phase events \
604 (configured-only branch must not fire, and warm_known_snapshots must not \
605 independently emit): {:?}",
606 page.items
607 );
608 }
609
610 #[tokio::test]
611 async fn read_only_knowledge_cache_miss_does_not_start_ann_writer_lifecycle() {
612 let dir = tempfile::tempdir().expect("tempdir");
613 let config = RuntimeConfig {
614 db_path: Some(dir.path().join("read-only-knowledge-ann.db")),
615 embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
616 additional_embedding_models: vec![],
617 ..RuntimeConfig::no_embeddings()
618 };
619 drop(KhiveRuntime::new(config.clone()).expect("migrate snapshot source"));
620
621 #[cfg(unix)]
622 {
623 let db_path = config.db_path.as_ref().expect("db path");
624 khive_storage::test_support::freeze_snapshot_sidecars(db_path);
625 }
626
627 let read_only = KhiveRuntime::new_readonly(config).expect("open snapshot read-only");
628 let token = read_only
629 .authorize(Namespace::local())
630 .expect("authorize local");
631 let pack = KnowledgePack::new(read_only.clone());
632 let key = crate::knowledge::vamana::AnnKey::new(
633 token.namespace().as_str(),
634 read_only.default_embedder_name(),
635 );
636 let before = read_only.backend().pool().writer_acquisition_snapshot();
637
638 crate::knowledge::vamana::ensure_ann_background(&read_only, &token, &pack.ann);
639
640 assert!(
641 !crate::knowledge::vamana::is_warming_not_loaded(&pack.ann, &key),
642 "a read-only search cache miss must not claim or spawn an ANN warm slot"
643 );
644 assert_eq!(
645 read_only.backend().pool().writer_acquisition_snapshot(),
646 before,
647 "read-only ANN admission must not acquire a writer"
648 );
649 }
650
651 #[tokio::test(start_paused = true)]
660 #[serial_test::serial(background_tasks)]
661 async fn writable_warm_starts_one_tracked_watcher_idempotently_and_it_exits_on_drop() {
662 let dir = tempfile::tempdir().expect("tempdir");
663 let config = RuntimeConfig {
664 db_path: Some(dir.path().join("rotation-watcher-lifecycle.db")),
665 embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
666 additional_embedding_models: vec![],
667 ..RuntimeConfig::no_embeddings()
668 };
669 let rt = KhiveRuntime::new(config).expect("writable runtime");
670 let pack = KnowledgePack::new(rt);
671
672 let before = khive_runtime::background_task_count();
673 pack.warm().await;
674 assert!(
675 crate::knowledge::vamana::rotation_watch_started_for_test(&pack.ann),
676 "a writable warm must start the rotation watcher"
677 );
678 assert_eq!(
679 khive_runtime::background_task_count(),
680 before + 1,
681 "warm must track exactly one rotation watcher task"
682 );
683
684 pack.warm().await;
686 assert_eq!(
687 khive_runtime::background_task_count(),
688 before + 1,
689 "a repeated warm must be idempotent and not start a second watcher"
690 );
691
692 let ann_weak = std::sync::Arc::downgrade(&pack.ann);
695 drop(pack);
696 assert!(
697 ann_weak.upgrade().is_none(),
698 "dropping the pack must drop its last strong ANN reference"
699 );
700
701 tokio::time::advance(std::time::Duration::from_secs(6)).await;
706 let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(60);
707 while khive_runtime::background_task_count() != before {
708 assert!(
709 tokio::time::Instant::now() < deadline,
710 "the watcher must exit once its ANN state is dropped"
711 );
712 tokio::time::sleep(std::time::Duration::from_millis(50)).await;
713 }
714 assert_eq!(
715 khive_runtime::background_task_count(),
716 before,
717 "the watcher must exit once its ANN state is dropped"
718 );
719 }
720}