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, SchemaPlan,
14 VerbRegistry,
15};
16use khive_storage::types::{SqlStatement, SqlValue};
17use khive_storage::{PhaseCancelledPayload, PhaseCompletedPayload, PhaseStartedPayload};
18use khive_types::{EventKind, HandlerDef, Pack};
19
20use crate::knowledge::util::{atom_from_row, atom_to_json, domain_from_row, domain_to_json};
21use crate::knowledge::vamana;
22use crate::knowledge::KnowledgeHandlers;
23use crate::vocab::{KNOWLEDGE_HANDLERS, KNOWLEDGE_SCHEMA_PLAN_STMTS};
24
25pub struct KnowledgePack {
27 pub(crate) runtime: KhiveRuntime,
28 pub(crate) ann: vamana::SharedAnn,
29 pub(crate) section_posteriors: Mutex<HashMap<String, SectionPosteriorState>>,
35 pub(crate) brain_profile: Option<String>,
41}
42
43impl Pack for KnowledgePack {
44 const NAME: &'static str = "knowledge";
45 const NOTE_KINDS: &'static [&'static str] = &[];
46 const ENTITY_KINDS: &'static [&'static str] = &[];
47 const BRAIN_CONSUMER_KINDS: &'static [&'static str] =
48 &[khive_brain_core::ConsumerKind::KnowledgeCompose.as_str()];
49 const HANDLERS: &'static [HandlerDef] = &KNOWLEDGE_HANDLERS;
50 const REQUIRES: &'static [&'static str] = &["kg"];
51 const SCHEMA_PLAN: Option<PackSchemaPlan> = Some(PackSchemaPlan {
52 pack: "knowledge",
53 statements: &KNOWLEDGE_SCHEMA_PLAN_STMTS,
54 });
55}
56
57impl KnowledgePack {
58 pub fn new(runtime: KhiveRuntime) -> Self {
60 let brain_profile = runtime.config().brain_profile.clone();
61 Self {
62 runtime,
63 ann: vamana::new_shared(),
64 section_posteriors: Mutex::new(HashMap::new()),
65 brain_profile,
66 }
67 }
68}
69
70struct KnowledgePackFactory;
71
72impl khive_runtime::PackFactory for KnowledgePackFactory {
73 fn name(&self) -> &'static str {
74 "knowledge"
75 }
76
77 fn requires(&self) -> &'static [&'static str] {
78 &["kg"]
79 }
80
81 fn create(&self, runtime: KhiveRuntime) -> Box<dyn khive_runtime::PackRuntime> {
82 Box::new(KnowledgePack::new(runtime))
83 }
84
85 fn create_resolver(
86 &self,
87 runtime: KhiveRuntime,
88 ) -> Option<Box<dyn khive_runtime::PackByIdResolver>> {
89 Some(Box::new(KnowledgePack::new(runtime)))
90 }
91}
92
93inventory::submit! { khive_runtime::PackRegistration(&KnowledgePackFactory) }
94
95#[async_trait]
96impl PackRuntime for KnowledgePack {
97 fn name(&self) -> &str {
98 <KnowledgePack as Pack>::NAME
99 }
100
101 fn note_kinds(&self) -> &'static [&'static str] {
102 <KnowledgePack as Pack>::NOTE_KINDS
103 }
104
105 fn entity_kinds(&self) -> &'static [&'static str] {
106 <KnowledgePack as Pack>::ENTITY_KINDS
107 }
108
109 fn brain_consumer_kinds(&self) -> &'static [&'static str] {
110 <KnowledgePack as Pack>::BRAIN_CONSUMER_KINDS
111 }
112
113 fn handlers(&self) -> &'static [HandlerDef] {
114 &KNOWLEDGE_HANDLERS
115 }
116
117 fn requires(&self) -> &'static [&'static str] {
118 <KnowledgePack as Pack>::REQUIRES
119 }
120
121 fn schema_plan(&self) -> SchemaPlan {
122 SchemaPlan {
123 pack: "knowledge",
124 statements: &KNOWLEDGE_SCHEMA_PLAN_STMTS,
125 }
126 }
127
128 async fn warm(&self) {
129 if !self.runtime.is_read_only() {
133 crate::knowledge::vamana::warm_known_snapshots(&self.runtime, &self.ann).await;
134 }
135 if !self.runtime.default_embedder_name().is_empty() {
136 let runtime = self.runtime.clone();
137 let token = match runtime.authorize(khive_runtime::Namespace::local()) {
146 Ok(token) => Some(token),
147 Err(e) => {
148 tracing::warn!(
149 error = %e,
150 "knowledge_embedder_warm: failed to mint ADR-103 phase-span \
151 attribution token; warmup proceeds without telemetry"
152 );
153 None
154 }
155 };
156 tokio::spawn(async move {
157 if let Some(token) = &token {
158 khive_runtime::emit_phase_event(
159 &runtime,
160 token,
161 "knowledge.embedder_warm",
162 EventKind::PhaseStarted,
163 PhaseStartedPayload {
164 work_class: "warm".into(),
165 phase: "knowledge_embedder_warm".into(),
166 corpus_size: None,
167 },
168 )
169 .await;
170 }
171 let phase_start = std::time::Instant::now();
172 let cpu_start = khive_runtime::process_resource_usage();
173 let result = runtime.embed("__khive_knowledge_warm__").await;
174 if let Some(token) = &token {
175 let wall_us = phase_start.elapsed().as_micros() as i64;
176 let cpu_us = khive_runtime::cpu_delta_us(
177 cpu_start,
178 khive_runtime::process_resource_usage(),
179 );
180 match &result {
181 Err(e) if khive_runtime::is_benign_shutdown_cancellation(e) => {
182 khive_runtime::emit_phase_event(
183 &runtime,
184 token,
185 "knowledge.embedder_warm",
186 EventKind::PhaseCancelled,
187 PhaseCancelledPayload {
188 work_class: "warm".into(),
189 phase: "knowledge_embedder_warm".into(),
190 wall_us,
191 cpu_us,
192 },
193 )
194 .await;
195 }
196 _ => {
197 khive_runtime::emit_phase_event(
198 &runtime,
199 token,
200 "knowledge.embedder_warm",
201 EventKind::PhaseCompleted,
202 PhaseCompletedPayload {
203 work_class: "warm".into(),
204 phase: "knowledge_embedder_warm".into(),
205 wall_us,
206 cpu_us,
207 },
208 )
209 .await;
210 }
211 }
212 }
213 let _ = result;
214 });
215 }
216 }
217
218 async fn dispatch(
219 &self,
220 verb: &str,
221 params: Value,
222 registry: &VerbRegistry,
223 token: &NamespaceToken,
224 ) -> Result<Value, RuntimeError> {
225 match verb {
226 "knowledge.upsert_atoms" => {
227 KnowledgeHandlers::upsert_atoms(&self.runtime, token, params).await
228 }
229 "knowledge.upsert_domains" => {
230 KnowledgeHandlers::upsert_domains(&self.runtime, token, params).await
231 }
232 "knowledge.get" => KnowledgeHandlers::get(&self.runtime, token, params).await,
233 "knowledge.list" => KnowledgeHandlers::list(&self.runtime, token, params).await,
234 "knowledge.delete_atoms" => {
235 KnowledgeHandlers::delete_atoms(&self.runtime, token, params).await
236 }
237 "knowledge.stats" => KnowledgeHandlers::stats(&self.runtime, token, params).await,
238 "knowledge.eval_retrieval" => {
239 KnowledgeHandlers::eval_retrieval(&self.runtime, token, params, &self.ann).await
240 }
241 "knowledge.index" => {
242 KnowledgeHandlers::index(&self.runtime, token, params, &self.ann, None).await
243 }
244 "knowledge.fold" => KnowledgeHandlers::fold(&self.runtime, token, params).await,
245 "knowledge.search" => {
246 KnowledgeHandlers::search(&self.runtime, token, params, &self.ann).await
247 }
248 "knowledge.suggest" => {
249 KnowledgeHandlers::suggest(&self.runtime, token, params, &self.ann).await
250 }
251 "knowledge.compose" => {
252 let effective_token = match params.get("namespace") {
258 None => token.clone(),
259 Some(Value::String(ns_str)) => {
260 let ns = Namespace::parse(ns_str).map_err(|e| {
261 RuntimeError::InvalidInput(format!("invalid namespace {ns_str:?}: {e}"))
262 })?;
263 if &ns != token.namespace() {
264 return Err(RuntimeError::InvalidInput(
265 "knowledge.compose namespace does not match authorized token namespace"
266 .to_string(),
267 ));
268 }
269 token.with_namespace(ns)
273 }
274 Some(_) => {
275 return Err(RuntimeError::InvalidInput(
276 "invalid namespace: expected a string".to_string(),
277 ));
278 }
279 };
280 let type_weights = self
281 .resolve_compose_type_weights(registry, &effective_token)
282 .await;
283 KnowledgeHandlers::compose(
284 &self.runtime,
285 &effective_token,
286 params,
287 &self.ann,
288 type_weights,
289 )
290 .await
291 }
292 "knowledge.edit" => {
293 KnowledgeHandlers::edit(&self.runtime, token, params, &self.ann).await
294 }
295 "knowledge.import" => {
296 KnowledgeHandlers::import(&self.runtime, token, params, &self.ann).await
297 }
298 "knowledge.challenge" => {
299 KnowledgeHandlers::challenge(&self.runtime, token, params).await
300 }
301 "knowledge.adjudicate" => {
302 KnowledgeHandlers::adjudicate(&self.runtime, token, params).await
303 }
304 "knowledge.learn" => self.handle_learn(token, params).await,
305 "knowledge.cite" => self.handle_cite(token, params).await,
306 "knowledge.topic" => self.handle_topic(token, params).await,
307 "knowledge.feedback" => self.handle_feedback(token, params, registry).await,
308 _ => Err(RuntimeError::InvalidInput(format!(
309 "knowledge pack does not handle verb {verb:?}"
310 ))),
311 }
312 }
313}
314
315#[async_trait]
316impl PackByIdResolver for KnowledgePack {
317 async fn resolve_by_id(&self, id: Uuid) -> Result<Option<Resolved>, RuntimeError> {
323 let sql = self.runtime.sql();
324 let id_str = id.to_string();
325
326 let mut reader = sql
327 .reader()
328 .await
329 .map_err(|e| RuntimeError::Internal(format!("knowledge resolve_by_id reader: {e}")))?;
330
331 let domain_row = reader
333 .query_row(SqlStatement {
334 sql: "SELECT id, namespace, slug, name, description, tags, members, \
335 created_at, updated_at, deleted_at \
336 FROM knowledge_domains WHERE id = ?1 AND deleted_at IS NULL LIMIT 1"
337 .into(),
338 params: vec![SqlValue::Text(id_str.clone())],
339 label: Some("knowledge.resolve_by_id.domain".into()),
340 })
341 .await
342 .map_err(|e| {
343 RuntimeError::Internal(format!("knowledge resolve_by_id domain query: {e}"))
344 })?;
345
346 if let Some(row) = domain_row {
347 if let Some(domain) = domain_from_row(&row) {
348 return Ok(Some(Resolved::PackRecord {
349 pack: "knowledge".into(),
350 kind: "domain".into(),
351 data: domain_to_json(&domain),
352 }));
353 }
354 }
355
356 let atom_row = reader
358 .query_row(SqlStatement {
359 sql: "SELECT id, namespace, slug, name, content, tags, properties, \
360 status, finalized, source_uri, source_type, created_at, updated_at, deleted_at \
361 FROM knowledge_atoms WHERE id = ?1 AND deleted_at IS NULL LIMIT 1"
362 .into(),
363 params: vec![SqlValue::Text(id_str)],
364 label: Some("knowledge.resolve_by_id.atom".into()),
365 })
366 .await
367 .map_err(|e| {
368 RuntimeError::Internal(format!("knowledge resolve_by_id atom query: {e}"))
369 })?;
370
371 if let Some(row) = atom_row {
372 if let Some(atom) = atom_from_row(&row) {
373 return Ok(Some(Resolved::PackRecord {
374 pack: "knowledge".into(),
375 kind: "atom".into(),
376 data: atom_to_json(&atom),
377 }));
378 }
379 }
380
381 Ok(None)
382 }
383
384 async fn resolve_by_id_including_deleted(
388 &self,
389 id: Uuid,
390 ) -> Result<Option<Resolved>, RuntimeError> {
391 let sql = self.runtime.sql();
392 let id_str = id.to_string();
393
394 let mut reader = sql.reader().await.map_err(|e| {
395 RuntimeError::Internal(format!(
396 "knowledge resolve_by_id_including_deleted reader: {e}"
397 ))
398 })?;
399
400 let domain_row = reader
401 .query_row(SqlStatement {
402 sql: "SELECT id, namespace, slug, name, description, tags, members, \
403 created_at, updated_at, deleted_at \
404 FROM knowledge_domains WHERE id = ?1 LIMIT 1"
405 .into(),
406 params: vec![SqlValue::Text(id_str.clone())],
407 label: Some("knowledge.resolve_by_id_incl_deleted.domain".into()),
408 })
409 .await
410 .map_err(|e| {
411 RuntimeError::Internal(format!(
412 "knowledge resolve_by_id_including_deleted domain query: {e}"
413 ))
414 })?;
415
416 if let Some(row) = domain_row {
417 if let Some(domain) = domain_from_row(&row) {
418 return Ok(Some(Resolved::PackRecord {
419 pack: "knowledge".into(),
420 kind: "domain".into(),
421 data: domain_to_json(&domain),
422 }));
423 }
424 }
425
426 let atom_row = reader
427 .query_row(SqlStatement {
428 sql: "SELECT id, namespace, slug, name, content, tags, properties, \
429 status, finalized, source_uri, source_type, created_at, updated_at, deleted_at \
430 FROM knowledge_atoms WHERE id = ?1 LIMIT 1"
431 .into(),
432 params: vec![SqlValue::Text(id_str)],
433 label: Some("knowledge.resolve_by_id_incl_deleted.atom".into()),
434 })
435 .await
436 .map_err(|e| {
437 RuntimeError::Internal(format!(
438 "knowledge resolve_by_id_including_deleted atom query: {e}"
439 ))
440 })?;
441
442 if let Some(row) = atom_row {
443 if let Some(atom) = atom_from_row(&row) {
444 return Ok(Some(Resolved::PackRecord {
445 pack: "knowledge".into(),
446 kind: "atom".into(),
447 data: atom_to_json(&atom),
448 }));
449 }
450 }
451
452 Ok(None)
453 }
454
455 async fn delete_by_id(&self, id: Uuid, hard: bool) -> Result<serde_json::Value, RuntimeError> {
461 let sql = self.runtime.sql();
462 let id_str = id.to_string();
463
464 let kind = match self.resolve_by_id_including_deleted(id).await? {
466 Some(Resolved::PackRecord { kind, .. }) => kind,
467 _ => {
468 return Err(RuntimeError::NotFound(format!(
469 "knowledge record not found: {id}"
470 )));
471 }
472 };
473
474 let now_us = std::time::SystemTime::now()
475 .duration_since(std::time::UNIX_EPOCH)
476 .unwrap_or_default()
477 .as_micros() as i64;
478
479 let mut writer = sql
480 .writer()
481 .await
482 .map_err(|e| RuntimeError::Internal(format!("knowledge delete_by_id writer: {e}")))?;
483
484 match kind.as_str() {
485 "domain" => {
486 if hard {
487 writer
491 .execute_batch(vec![
492 SqlStatement {
493 sql: "DELETE FROM knowledge_sections WHERE atom_id = ?1".into(),
494 params: vec![SqlValue::Text(id_str.clone())],
495 label: Some(
496 "knowledge.delete_by_id.domain_mirror_sections.hard".into(),
497 ),
498 },
499 SqlStatement {
500 sql: "DELETE FROM knowledge_atoms WHERE id = ?1".into(),
501 params: vec![SqlValue::Text(id_str.clone())],
502 label: Some("knowledge.delete_by_id.domain_mirror.hard".into()),
503 },
504 SqlStatement {
505 sql: "DELETE FROM knowledge_domains WHERE id = ?1".into(),
506 params: vec![SqlValue::Text(id_str.clone())],
507 label: Some("knowledge.delete_by_id.domain.hard".into()),
508 },
509 ])
510 .await
511 .map_err(|e| {
512 RuntimeError::Internal(format!(
513 "knowledge delete_by_id domain hard: {e}"
514 ))
515 })?;
516 } else {
517 writer
518 .execute(SqlStatement {
519 sql: "UPDATE knowledge_domains SET deleted_at = ?1 \
520 WHERE id = ?2 AND deleted_at IS NULL"
521 .into(),
522 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
523 label: Some("knowledge.delete_by_id.domain.soft".into()),
524 })
525 .await
526 .map_err(|e| {
527 RuntimeError::Internal(format!(
528 "knowledge delete_by_id domain soft: {e}"
529 ))
530 })?;
531 writer
533 .execute(SqlStatement {
534 sql: "UPDATE knowledge_atoms SET deleted_at = ?1 \
535 WHERE id = ?2 AND deleted_at IS NULL"
536 .into(),
537 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
538 label: Some("knowledge.delete_by_id.domain_mirror.soft".into()),
539 })
540 .await
541 .map_err(|e| {
542 RuntimeError::Internal(format!(
543 "knowledge delete_by_id domain mirror soft: {e}"
544 ))
545 })?;
546 }
547 }
548 "atom" => {
549 if hard {
550 writer
552 .execute_batch(vec![
553 SqlStatement {
554 sql: "DELETE FROM knowledge_sections WHERE atom_id = ?1".into(),
555 params: vec![SqlValue::Text(id_str.clone())],
556 label: Some("knowledge.delete_by_id.atom_sections.hard".into()),
557 },
558 SqlStatement {
559 sql: "DELETE FROM knowledge_atoms WHERE id = ?1".into(),
560 params: vec![SqlValue::Text(id_str.clone())],
561 label: Some("knowledge.delete_by_id.atom.hard".into()),
562 },
563 ])
564 .await
565 .map_err(|e| {
566 RuntimeError::Internal(format!("knowledge delete_by_id atom hard: {e}"))
567 })?;
568 } else {
569 writer
570 .execute(SqlStatement {
571 sql: "UPDATE knowledge_atoms SET deleted_at = ?1 \
572 WHERE id = ?2 AND deleted_at IS NULL"
573 .into(),
574 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
575 label: Some("knowledge.delete_by_id.atom.soft".into()),
576 })
577 .await
578 .map_err(|e| {
579 RuntimeError::Internal(format!("knowledge delete_by_id atom soft: {e}"))
580 })?;
581 }
582 }
583 other => {
584 return Err(RuntimeError::Internal(format!(
585 "knowledge delete_by_id: unexpected kind {other:?}"
586 )));
587 }
588 }
589
590 Ok(serde_json::json!({
591 "deleted": true,
592 "id": id_str,
593 "kind": kind,
594 "hard": hard,
595 }))
596 }
597}
598
599#[cfg(test)]
600mod tests {
601 use khive_runtime::pack::PackRuntime;
602 use khive_runtime::{KhiveRuntime, Namespace, RuntimeConfig};
603 use lattice_embed::EmbeddingModel;
604
605 use super::KnowledgePack;
606
607 #[tokio::test]
616 async fn knowledge_warm_emits_no_phase_events_when_no_embedder_configured() {
617 let rt = KhiveRuntime::memory().expect("in-memory runtime");
618 let token = rt.authorize(Namespace::local()).expect("authorize local");
619 let event_store = rt.events(&token).expect("event store must be available");
620
621 let pack = KnowledgePack::new(rt.clone());
622 pack.warm().await;
623
624 let page = event_store
625 .query_events(
626 khive_storage::EventFilter::default(),
627 khive_storage::PageRequest {
628 limit: 10,
629 offset: 0,
630 },
631 )
632 .await
633 .expect("query events");
634
635 assert!(
636 page.items.is_empty(),
637 "no embedder configured -> KnowledgePack::warm() must emit zero phase events \
638 (configured-only branch must not fire, and warm_known_snapshots must not \
639 independently emit): {:?}",
640 page.items
641 );
642 }
643
644 #[tokio::test]
645 async fn read_only_knowledge_cache_miss_does_not_start_ann_writer_lifecycle() {
646 let dir = tempfile::tempdir().expect("tempdir");
647 let config = RuntimeConfig {
648 db_path: Some(dir.path().join("read-only-knowledge-ann.db")),
649 embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
650 additional_embedding_models: vec![],
651 ..RuntimeConfig::no_embeddings()
652 };
653 drop(KhiveRuntime::new(config.clone()).expect("migrate snapshot source"));
654
655 #[cfg(unix)]
656 {
657 use std::os::unix::fs::PermissionsExt;
658 let db_path = config.db_path.as_ref().expect("db path");
659 for suffix in ["-wal", "-shm"] {
660 let mut name = db_path.file_name().expect("db file name").to_os_string();
661 name.push(suffix);
662 let sidecar = db_path.parent().expect("db parent dir").join(name);
663 if sidecar.exists() {
664 let mut permissions = std::fs::metadata(&sidecar)
665 .expect("sidecar metadata")
666 .permissions();
667 permissions.set_mode(0o444);
668 std::fs::set_permissions(&sidecar, permissions).expect("freeze sidecar");
669 }
670 }
671 }
672
673 let read_only = KhiveRuntime::new_readonly(config).expect("open snapshot read-only");
674 let token = read_only
675 .authorize(Namespace::local())
676 .expect("authorize local");
677 let pack = KnowledgePack::new(read_only.clone());
678 let key = crate::knowledge::vamana::AnnKey::new(
679 token.namespace().as_str(),
680 read_only.default_embedder_name(),
681 );
682 let before = read_only.backend().pool().writer_acquisition_snapshot();
683
684 crate::knowledge::vamana::ensure_ann_background(&read_only, &token, &pack.ann);
685
686 assert!(
687 !crate::knowledge::vamana::is_warming_not_loaded(&pack.ann, &key),
688 "a read-only search cache miss must not claim or spawn an ANN warm slot"
689 );
690 assert_eq!(
691 read_only.backend().pool().writer_acquisition_snapshot(),
692 before,
693 "read-only ANN admission must not acquire a writer"
694 );
695 }
696}