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, 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;
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}
51
52impl KnowledgePack {
53 pub fn new(runtime: KhiveRuntime) -> Self {
55 let brain_profile = runtime.config().brain_profile.clone();
56 Self {
57 runtime,
58 ann: vamana::new_shared(),
59 section_posteriors: Mutex::new(HashMap::new()),
60 brain_profile,
61 }
62 }
63}
64
65struct KnowledgePackFactory;
66
67impl khive_runtime::PackFactory for KnowledgePackFactory {
68 fn name(&self) -> &'static str {
69 "knowledge"
70 }
71
72 fn requires(&self) -> &'static [&'static str] {
73 &["kg"]
74 }
75
76 fn create(&self, runtime: KhiveRuntime) -> Box<dyn khive_runtime::PackRuntime> {
77 Box::new(KnowledgePack::new(runtime))
78 }
79
80 fn create_resolver(
81 &self,
82 runtime: KhiveRuntime,
83 ) -> Option<Box<dyn khive_runtime::PackByIdResolver>> {
84 Some(Box::new(KnowledgePack::new(runtime)))
85 }
86}
87
88inventory::submit! { khive_runtime::PackRegistration(&KnowledgePackFactory) }
89
90#[async_trait]
91impl PackRuntime for KnowledgePack {
92 fn name(&self) -> &str {
93 <KnowledgePack as Pack>::NAME
94 }
95
96 fn note_kinds(&self) -> &'static [&'static str] {
97 <KnowledgePack as Pack>::NOTE_KINDS
98 }
99
100 fn entity_kinds(&self) -> &'static [&'static str] {
101 <KnowledgePack as Pack>::ENTITY_KINDS
102 }
103
104 fn brain_consumer_kinds(&self) -> &'static [&'static str] {
105 <KnowledgePack as Pack>::BRAIN_CONSUMER_KINDS
106 }
107
108 fn handlers(&self) -> &'static [HandlerDef] {
109 &KNOWLEDGE_HANDLERS
110 }
111
112 fn requires(&self) -> &'static [&'static str] {
113 <KnowledgePack as Pack>::REQUIRES
114 }
115
116 async fn warm(&self) {
117 crate::knowledge::vamana::warm_known_snapshots(&self.runtime, &self.ann).await;
118 if !self.runtime.default_embedder_name().is_empty() {
119 let runtime = self.runtime.clone();
120 let token = match runtime.authorize(khive_runtime::Namespace::local()) {
129 Ok(token) => Some(token),
130 Err(e) => {
131 tracing::warn!(
132 error = %e,
133 "knowledge_embedder_warm: failed to mint ADR-103 phase-span \
134 attribution token; warmup proceeds without telemetry"
135 );
136 None
137 }
138 };
139 tokio::spawn(async move {
140 if let Some(token) = &token {
141 khive_runtime::emit_phase_event(
142 &runtime,
143 token,
144 "knowledge.embedder_warm",
145 EventKind::PhaseStarted,
146 PhaseStartedPayload {
147 work_class: "warm".into(),
148 phase: "knowledge_embedder_warm".into(),
149 corpus_size: None,
150 },
151 )
152 .await;
153 }
154 let phase_start = std::time::Instant::now();
155 let cpu_start = khive_runtime::process_resource_usage();
156 let result = runtime.embed("__khive_knowledge_warm__").await;
157 if let Some(token) = &token {
158 let wall_us = phase_start.elapsed().as_micros() as i64;
159 let cpu_us = khive_runtime::cpu_delta_us(
160 cpu_start,
161 khive_runtime::process_resource_usage(),
162 );
163 match &result {
164 Err(e) if khive_runtime::is_benign_shutdown_cancellation(e) => {
165 khive_runtime::emit_phase_event(
166 &runtime,
167 token,
168 "knowledge.embedder_warm",
169 EventKind::PhaseCancelled,
170 PhaseCancelledPayload {
171 work_class: "warm".into(),
172 phase: "knowledge_embedder_warm".into(),
173 wall_us,
174 cpu_us,
175 },
176 )
177 .await;
178 }
179 _ => {
180 khive_runtime::emit_phase_event(
181 &runtime,
182 token,
183 "knowledge.embedder_warm",
184 EventKind::PhaseCompleted,
185 PhaseCompletedPayload {
186 work_class: "warm".into(),
187 phase: "knowledge_embedder_warm".into(),
188 wall_us,
189 cpu_us,
190 },
191 )
192 .await;
193 }
194 }
195 }
196 let _ = result;
197 });
198 }
199 }
200
201 async fn dispatch(
202 &self,
203 verb: &str,
204 params: Value,
205 registry: &VerbRegistry,
206 token: &NamespaceToken,
207 ) -> Result<Value, RuntimeError> {
208 match verb {
209 "knowledge.upsert_atoms" => {
210 KnowledgeHandlers::upsert_atoms(&self.runtime, token, params).await
211 }
212 "knowledge.upsert_domains" => {
213 KnowledgeHandlers::upsert_domains(&self.runtime, token, params).await
214 }
215 "knowledge.get" => KnowledgeHandlers::get(&self.runtime, token, params).await,
216 "knowledge.list" => KnowledgeHandlers::list(&self.runtime, token, params).await,
217 "knowledge.delete_atoms" => {
218 KnowledgeHandlers::delete_atoms(&self.runtime, token, params).await
219 }
220 "knowledge.stats" => KnowledgeHandlers::stats(&self.runtime, token, params).await,
221 "knowledge.index" => {
222 KnowledgeHandlers::index(&self.runtime, token, params, &self.ann, None).await
223 }
224 "knowledge.fold" => KnowledgeHandlers::fold(&self.runtime, token, params).await,
225 "knowledge.search" => {
226 KnowledgeHandlers::search(&self.runtime, token, params, &self.ann).await
227 }
228 "knowledge.suggest" => {
229 KnowledgeHandlers::suggest(&self.runtime, token, params, &self.ann).await
230 }
231 "knowledge.compose" => {
232 let effective_token = match params.get("namespace") {
238 None => token.clone(),
239 Some(Value::String(ns_str)) => {
240 let ns = Namespace::parse(ns_str).map_err(|e| {
241 RuntimeError::InvalidInput(format!("invalid namespace {ns_str:?}: {e}"))
242 })?;
243 if &ns != token.namespace() {
244 return Err(RuntimeError::InvalidInput(
245 "knowledge.compose namespace does not match authorized token namespace"
246 .to_string(),
247 ));
248 }
249 token.with_namespace(ns)
253 }
254 Some(_) => {
255 return Err(RuntimeError::InvalidInput(
256 "invalid namespace: expected a string".to_string(),
257 ));
258 }
259 };
260 let type_weights = self
261 .resolve_compose_type_weights(registry, &effective_token)
262 .await;
263 KnowledgeHandlers::compose(
264 &self.runtime,
265 &effective_token,
266 params,
267 &self.ann,
268 type_weights,
269 )
270 .await
271 }
272 "knowledge.edit" => {
273 KnowledgeHandlers::edit(&self.runtime, token, params, &self.ann).await
274 }
275 "knowledge.import" => {
276 KnowledgeHandlers::import(&self.runtime, token, params, &self.ann).await
277 }
278 "knowledge.challenge" => {
279 KnowledgeHandlers::challenge(&self.runtime, token, params).await
280 }
281 "knowledge.adjudicate" => {
282 KnowledgeHandlers::adjudicate(&self.runtime, token, params).await
283 }
284 "knowledge.learn" => self.handle_learn(token, params).await,
285 "knowledge.cite" => self.handle_cite(token, params).await,
286 "knowledge.topic" => self.handle_topic(token, params).await,
287 "knowledge.feedback" => self.handle_feedback(token, params, registry).await,
288 _ => Err(RuntimeError::InvalidInput(format!(
289 "knowledge pack does not handle verb {verb:?}"
290 ))),
291 }
292 }
293}
294
295#[async_trait]
296impl PackByIdResolver for KnowledgePack {
297 async fn resolve_by_id(&self, id: Uuid) -> Result<Option<Resolved>, RuntimeError> {
303 let sql = self.runtime.sql();
304 let id_str = id.to_string();
305
306 let mut reader = sql
307 .reader()
308 .await
309 .map_err(|e| RuntimeError::Internal(format!("knowledge resolve_by_id reader: {e}")))?;
310
311 let domain_row = reader
313 .query_row(SqlStatement {
314 sql: "SELECT id, namespace, slug, name, description, tags, members, \
315 created_at, updated_at, deleted_at \
316 FROM knowledge_domains WHERE id = ?1 AND deleted_at IS NULL LIMIT 1"
317 .into(),
318 params: vec![SqlValue::Text(id_str.clone())],
319 label: Some("knowledge.resolve_by_id.domain".into()),
320 })
321 .await
322 .map_err(|e| {
323 RuntimeError::Internal(format!("knowledge resolve_by_id domain query: {e}"))
324 })?;
325
326 if let Some(row) = domain_row {
327 if let Some(domain) = domain_from_row(&row) {
328 return Ok(Some(Resolved::PackRecord {
329 pack: "knowledge".into(),
330 kind: "domain".into(),
331 data: domain_to_json(&domain),
332 }));
333 }
334 }
335
336 let atom_row = reader
338 .query_row(SqlStatement {
339 sql: "SELECT id, namespace, slug, name, content, tags, properties, \
340 status, finalized, source_uri, source_type, created_at, updated_at, deleted_at \
341 FROM knowledge_atoms WHERE id = ?1 AND deleted_at IS NULL LIMIT 1"
342 .into(),
343 params: vec![SqlValue::Text(id_str)],
344 label: Some("knowledge.resolve_by_id.atom".into()),
345 })
346 .await
347 .map_err(|e| {
348 RuntimeError::Internal(format!("knowledge resolve_by_id atom query: {e}"))
349 })?;
350
351 if let Some(row) = atom_row {
352 if let Some(atom) = atom_from_row(&row) {
353 return Ok(Some(Resolved::PackRecord {
354 pack: "knowledge".into(),
355 kind: "atom".into(),
356 data: atom_to_json(&atom),
357 }));
358 }
359 }
360
361 Ok(None)
362 }
363
364 async fn resolve_by_id_including_deleted(
368 &self,
369 id: Uuid,
370 ) -> Result<Option<Resolved>, RuntimeError> {
371 let sql = self.runtime.sql();
372 let id_str = id.to_string();
373
374 let mut reader = sql.reader().await.map_err(|e| {
375 RuntimeError::Internal(format!(
376 "knowledge resolve_by_id_including_deleted reader: {e}"
377 ))
378 })?;
379
380 let domain_row = reader
381 .query_row(SqlStatement {
382 sql: "SELECT id, namespace, slug, name, description, tags, members, \
383 created_at, updated_at, deleted_at \
384 FROM knowledge_domains WHERE id = ?1 LIMIT 1"
385 .into(),
386 params: vec![SqlValue::Text(id_str.clone())],
387 label: Some("knowledge.resolve_by_id_incl_deleted.domain".into()),
388 })
389 .await
390 .map_err(|e| {
391 RuntimeError::Internal(format!(
392 "knowledge resolve_by_id_including_deleted domain query: {e}"
393 ))
394 })?;
395
396 if let Some(row) = domain_row {
397 if let Some(domain) = domain_from_row(&row) {
398 return Ok(Some(Resolved::PackRecord {
399 pack: "knowledge".into(),
400 kind: "domain".into(),
401 data: domain_to_json(&domain),
402 }));
403 }
404 }
405
406 let atom_row = reader
407 .query_row(SqlStatement {
408 sql: "SELECT id, namespace, slug, name, content, tags, properties, \
409 status, finalized, source_uri, source_type, created_at, updated_at, deleted_at \
410 FROM knowledge_atoms WHERE id = ?1 LIMIT 1"
411 .into(),
412 params: vec![SqlValue::Text(id_str)],
413 label: Some("knowledge.resolve_by_id_incl_deleted.atom".into()),
414 })
415 .await
416 .map_err(|e| {
417 RuntimeError::Internal(format!(
418 "knowledge resolve_by_id_including_deleted atom query: {e}"
419 ))
420 })?;
421
422 if let Some(row) = atom_row {
423 if let Some(atom) = atom_from_row(&row) {
424 return Ok(Some(Resolved::PackRecord {
425 pack: "knowledge".into(),
426 kind: "atom".into(),
427 data: atom_to_json(&atom),
428 }));
429 }
430 }
431
432 Ok(None)
433 }
434
435 async fn delete_by_id(&self, id: Uuid, hard: bool) -> Result<serde_json::Value, RuntimeError> {
441 let sql = self.runtime.sql();
442 let id_str = id.to_string();
443
444 let kind = match self.resolve_by_id_including_deleted(id).await? {
446 Some(Resolved::PackRecord { kind, .. }) => kind,
447 _ => {
448 return Err(RuntimeError::NotFound(format!(
449 "knowledge record not found: {id}"
450 )));
451 }
452 };
453
454 let now_us = std::time::SystemTime::now()
455 .duration_since(std::time::UNIX_EPOCH)
456 .unwrap_or_default()
457 .as_micros() as i64;
458
459 let mut writer = sql
460 .writer()
461 .await
462 .map_err(|e| RuntimeError::Internal(format!("knowledge delete_by_id writer: {e}")))?;
463
464 match kind.as_str() {
465 "domain" => {
466 if hard {
467 writer
471 .execute_batch(vec![
472 SqlStatement {
473 sql: "DELETE FROM knowledge_sections WHERE atom_id = ?1".into(),
474 params: vec![SqlValue::Text(id_str.clone())],
475 label: Some(
476 "knowledge.delete_by_id.domain_mirror_sections.hard".into(),
477 ),
478 },
479 SqlStatement {
480 sql: "DELETE FROM knowledge_atoms WHERE id = ?1".into(),
481 params: vec![SqlValue::Text(id_str.clone())],
482 label: Some("knowledge.delete_by_id.domain_mirror.hard".into()),
483 },
484 SqlStatement {
485 sql: "DELETE FROM knowledge_domains WHERE id = ?1".into(),
486 params: vec![SqlValue::Text(id_str.clone())],
487 label: Some("knowledge.delete_by_id.domain.hard".into()),
488 },
489 ])
490 .await
491 .map_err(|e| {
492 RuntimeError::Internal(format!(
493 "knowledge delete_by_id domain hard: {e}"
494 ))
495 })?;
496 } else {
497 writer
498 .execute(SqlStatement {
499 sql: "UPDATE knowledge_domains SET deleted_at = ?1 \
500 WHERE id = ?2 AND deleted_at IS NULL"
501 .into(),
502 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
503 label: Some("knowledge.delete_by_id.domain.soft".into()),
504 })
505 .await
506 .map_err(|e| {
507 RuntimeError::Internal(format!(
508 "knowledge delete_by_id domain soft: {e}"
509 ))
510 })?;
511 writer
513 .execute(SqlStatement {
514 sql: "UPDATE knowledge_atoms SET deleted_at = ?1 \
515 WHERE id = ?2 AND deleted_at IS NULL"
516 .into(),
517 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
518 label: Some("knowledge.delete_by_id.domain_mirror.soft".into()),
519 })
520 .await
521 .map_err(|e| {
522 RuntimeError::Internal(format!(
523 "knowledge delete_by_id domain mirror soft: {e}"
524 ))
525 })?;
526 }
527 }
528 "atom" => {
529 if hard {
530 writer
532 .execute_batch(vec![
533 SqlStatement {
534 sql: "DELETE FROM knowledge_sections WHERE atom_id = ?1".into(),
535 params: vec![SqlValue::Text(id_str.clone())],
536 label: Some("knowledge.delete_by_id.atom_sections.hard".into()),
537 },
538 SqlStatement {
539 sql: "DELETE FROM knowledge_atoms WHERE id = ?1".into(),
540 params: vec![SqlValue::Text(id_str.clone())],
541 label: Some("knowledge.delete_by_id.atom.hard".into()),
542 },
543 ])
544 .await
545 .map_err(|e| {
546 RuntimeError::Internal(format!("knowledge delete_by_id atom hard: {e}"))
547 })?;
548 } else {
549 writer
550 .execute(SqlStatement {
551 sql: "UPDATE knowledge_atoms SET deleted_at = ?1 \
552 WHERE id = ?2 AND deleted_at IS NULL"
553 .into(),
554 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
555 label: Some("knowledge.delete_by_id.atom.soft".into()),
556 })
557 .await
558 .map_err(|e| {
559 RuntimeError::Internal(format!("knowledge delete_by_id atom soft: {e}"))
560 })?;
561 }
562 }
563 other => {
564 return Err(RuntimeError::Internal(format!(
565 "knowledge delete_by_id: unexpected kind {other:?}"
566 )));
567 }
568 }
569
570 Ok(serde_json::json!({
571 "deleted": true,
572 "id": id_str,
573 "kind": kind,
574 "hard": hard,
575 }))
576 }
577}
578
579#[cfg(test)]
580mod tests {
581 use khive_runtime::pack::PackRuntime;
582 use khive_runtime::{KhiveRuntime, Namespace};
583
584 use super::KnowledgePack;
585
586 #[tokio::test]
595 async fn knowledge_warm_emits_no_phase_events_when_no_embedder_configured() {
596 let rt = KhiveRuntime::memory().expect("in-memory runtime");
597 let token = rt.authorize(Namespace::local()).expect("authorize local");
598 let event_store = rt.events(&token).expect("event store must be available");
599
600 let pack = KnowledgePack::new(rt.clone());
601 pack.warm().await;
602
603 let page = event_store
604 .query_events(
605 khive_storage::EventFilter::default(),
606 khive_storage::PageRequest {
607 limit: 10,
608 offset: 0,
609 },
610 )
611 .await
612 .expect("query events");
613
614 assert!(
615 page.items.is_empty(),
616 "no embedder configured -> KnowledgePack::warm() must emit zero phase events \
617 (configured-only branch must not fire, and warm_known_snapshots must not \
618 independently emit): {:?}",
619 page.items
620 );
621 }
622}