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.export" => KnowledgeHandlers::export(&self.runtime, token, params).await,
211 "knowledge.delete_atoms" => {
212 KnowledgeHandlers::delete_atoms(&self.runtime, token, params).await
213 }
214 "knowledge.stats" => KnowledgeHandlers::stats(&self.runtime, token, params).await,
215 "knowledge.eval_retrieval" => {
216 KnowledgeHandlers::eval_retrieval(&self.runtime, token, params, &self.ann).await
217 }
218 "knowledge.index" => {
219 KnowledgeHandlers::index(&self.runtime, token, params, &self.ann, None).await
220 }
221 "knowledge.fold" => KnowledgeHandlers::fold(&self.runtime, token, params).await,
222 "knowledge.search" => {
223 KnowledgeHandlers::search(&self.runtime, token, params, &self.ann).await
224 }
225 "knowledge.suggest" => {
226 KnowledgeHandlers::suggest(&self.runtime, token, params, &self.ann).await
227 }
228 "knowledge.compose" => {
229 let effective_token = match params.get("namespace") {
235 None => token.clone(),
236 Some(Value::String(ns_str)) => {
237 let ns = Namespace::parse(ns_str).map_err(|e| {
238 RuntimeError::InvalidInput(format!("invalid namespace {ns_str:?}: {e}"))
239 })?;
240 if &ns != token.namespace() {
241 return Err(RuntimeError::InvalidInput(
242 "knowledge.compose namespace does not match authorized token namespace"
243 .to_string(),
244 ));
245 }
246 token.with_namespace(ns)
250 }
251 Some(_) => {
252 return Err(RuntimeError::InvalidInput(
253 "invalid namespace: expected a string".to_string(),
254 ));
255 }
256 };
257 let type_weights = self
258 .resolve_compose_type_weights(registry, &effective_token)
259 .await;
260 KnowledgeHandlers::compose(
261 &self.runtime,
262 &effective_token,
263 params,
264 &self.ann,
265 type_weights,
266 )
267 .await
268 }
269 "knowledge.edit" => {
270 KnowledgeHandlers::edit(&self.runtime, token, params, &self.ann).await
271 }
272 "knowledge.import" => {
273 KnowledgeHandlers::import(&self.runtime, token, params, &self.ann).await
274 }
275 "knowledge.challenge" => {
276 KnowledgeHandlers::challenge(&self.runtime, token, params).await
277 }
278 "knowledge.adjudicate" => {
279 KnowledgeHandlers::adjudicate(&self.runtime, token, params).await
280 }
281 "knowledge.learn" => self.handle_learn(token, params).await,
282 "knowledge.cite" => self.handle_cite(token, params).await,
283 "knowledge.topic" => self.handle_topic(token, params).await,
284 "knowledge.feedback" => self.handle_feedback(token, params, registry).await,
285 _ => Err(RuntimeError::InvalidInput(format!(
286 "knowledge pack does not handle verb {verb:?}"
287 ))),
288 }
289 }
290}
291
292#[async_trait]
293impl PackByIdResolver for KnowledgePack {
294 async fn resolve_by_id(&self, id: Uuid) -> Result<Option<Resolved>, RuntimeError> {
300 let sql = self.runtime.sql();
301 let id_str = id.to_string();
302
303 let mut reader = sql
304 .reader()
305 .await
306 .map_err(|e| RuntimeError::Internal(format!("knowledge resolve_by_id reader: {e}")))?;
307
308 let domain_row = reader
310 .query_row(SqlStatement {
311 sql: khive_runtime::sql!("knowledge_resolver_live_domain").into(),
312 params: vec![SqlValue::Text(id_str.clone())],
313 label: Some("knowledge.resolve_by_id.domain".into()),
314 })
315 .await
316 .map_err(|e| {
317 RuntimeError::Internal(format!("knowledge resolve_by_id domain query: {e}"))
318 })?;
319
320 if let Some(row) = domain_row {
321 if let Some(domain) = domain_from_row(&row) {
322 return Ok(Some(Resolved::PackRecord {
323 pack: "knowledge".into(),
324 kind: "domain".into(),
325 data: domain_to_json(&domain),
326 }));
327 }
328 }
329
330 let atom_row = reader
332 .query_row(SqlStatement {
333 sql: khive_runtime::sql!("knowledge_resolver_live_atom").into(),
334 params: vec![SqlValue::Text(id_str)],
335 label: Some("knowledge.resolve_by_id.atom".into()),
336 })
337 .await
338 .map_err(|e| {
339 RuntimeError::Internal(format!("knowledge resolve_by_id atom query: {e}"))
340 })?;
341
342 if let Some(row) = atom_row {
343 if let Some(atom) = atom_from_row(&row) {
344 return Ok(Some(Resolved::PackRecord {
345 pack: "knowledge".into(),
346 kind: "atom".into(),
347 data: atom_to_json(&atom),
348 }));
349 }
350 }
351
352 Ok(None)
353 }
354
355 async fn resolve_by_id_including_deleted(
359 &self,
360 id: Uuid,
361 ) -> Result<Option<Resolved>, RuntimeError> {
362 let sql = self.runtime.sql();
363 let id_str = id.to_string();
364
365 let mut reader = sql.reader().await.map_err(|e| {
366 RuntimeError::Internal(format!(
367 "knowledge resolve_by_id_including_deleted reader: {e}"
368 ))
369 })?;
370
371 let domain_row = reader
372 .query_row(SqlStatement {
373 sql: khive_runtime::sql!("knowledge_resolver_domain_including_deleted").into(),
374 params: vec![SqlValue::Text(id_str.clone())],
375 label: Some("knowledge.resolve_by_id_incl_deleted.domain".into()),
376 })
377 .await
378 .map_err(|e| {
379 RuntimeError::Internal(format!(
380 "knowledge resolve_by_id_including_deleted domain query: {e}"
381 ))
382 })?;
383
384 if let Some(row) = domain_row {
385 if let Some(domain) = domain_from_row(&row) {
386 return Ok(Some(Resolved::PackRecord {
387 pack: "knowledge".into(),
388 kind: "domain".into(),
389 data: domain_to_json(&domain),
390 }));
391 }
392 }
393
394 let atom_row = reader
395 .query_row(SqlStatement {
396 sql: khive_runtime::sql!("knowledge_resolver_atom_including_deleted").into(),
397 params: vec![SqlValue::Text(id_str)],
398 label: Some("knowledge.resolve_by_id_incl_deleted.atom".into()),
399 })
400 .await
401 .map_err(|e| {
402 RuntimeError::Internal(format!(
403 "knowledge resolve_by_id_including_deleted atom query: {e}"
404 ))
405 })?;
406
407 if let Some(row) = atom_row {
408 if let Some(atom) = atom_from_row(&row) {
409 return Ok(Some(Resolved::PackRecord {
410 pack: "knowledge".into(),
411 kind: "atom".into(),
412 data: atom_to_json(&atom),
413 }));
414 }
415 }
416
417 Ok(None)
418 }
419
420 fn private_record_verbs(&self) -> &'static [&'static str] {
421 &[
422 "knowledge.upsert_atoms",
423 "knowledge.upsert_domains",
424 "knowledge.edit",
425 ]
426 }
427
428 async fn delete_by_id(&self, id: Uuid, hard: bool) -> Result<serde_json::Value, RuntimeError> {
434 let sql = self.runtime.sql();
435 let id_str = id.to_string();
436
437 let kind = match self.resolve_by_id_including_deleted(id).await? {
439 Some(Resolved::PackRecord { kind, .. }) => kind,
440 _ => {
441 return Err(RuntimeError::NotFound(format!(
442 "knowledge record not found: {id}"
443 )));
444 }
445 };
446
447 let now_us = std::time::SystemTime::now()
448 .duration_since(std::time::UNIX_EPOCH)
449 .unwrap_or_default()
450 .as_micros() as i64;
451
452 let mut writer = sql
453 .writer()
454 .await
455 .map_err(|e| RuntimeError::Internal(format!("knowledge delete_by_id writer: {e}")))?;
456
457 match kind.as_str() {
458 "domain" => {
459 if hard {
460 writer
464 .execute_batch(vec![
465 SqlStatement {
466 sql: khive_runtime::sql!("knowledge_atom_sections_delete").into(),
467 params: vec![SqlValue::Text(id_str.clone())],
468 label: Some(
469 "knowledge.delete_by_id.domain_mirror_sections.hard".into(),
470 ),
471 },
472 SqlStatement {
473 sql: khive_runtime::sql!("knowledge_atom_hard_delete").into(),
474 params: vec![SqlValue::Text(id_str.clone())],
475 label: Some("knowledge.delete_by_id.domain_mirror.hard".into()),
476 },
477 SqlStatement {
478 sql: khive_runtime::sql!("knowledge_domain_hard_delete").into(),
479 params: vec![SqlValue::Text(id_str.clone())],
480 label: Some("knowledge.delete_by_id.domain.hard".into()),
481 },
482 ])
483 .await
484 .map_err(|e| {
485 RuntimeError::Internal(format!(
486 "knowledge delete_by_id domain hard: {e}"
487 ))
488 })?;
489 } else {
490 writer
491 .execute(SqlStatement {
492 sql: khive_runtime::sql!("knowledge_domain_soft_delete").into(),
493 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
494 label: Some("knowledge.delete_by_id.domain.soft".into()),
495 })
496 .await
497 .map_err(|e| {
498 RuntimeError::Internal(format!(
499 "knowledge delete_by_id domain soft: {e}"
500 ))
501 })?;
502 writer
504 .execute(SqlStatement {
505 sql: khive_runtime::sql!("knowledge_atom_soft_delete").into(),
506 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
507 label: Some("knowledge.delete_by_id.domain_mirror.soft".into()),
508 })
509 .await
510 .map_err(|e| {
511 RuntimeError::Internal(format!(
512 "knowledge delete_by_id domain mirror soft: {e}"
513 ))
514 })?;
515 }
516 }
517 "atom" => {
518 if hard {
519 writer
521 .execute_batch(vec![
522 SqlStatement {
523 sql: khive_runtime::sql!("knowledge_atom_sections_delete").into(),
524 params: vec![SqlValue::Text(id_str.clone())],
525 label: Some("knowledge.delete_by_id.atom_sections.hard".into()),
526 },
527 SqlStatement {
528 sql: khive_runtime::sql!("knowledge_atom_hard_delete").into(),
529 params: vec![SqlValue::Text(id_str.clone())],
530 label: Some("knowledge.delete_by_id.atom.hard".into()),
531 },
532 ])
533 .await
534 .map_err(|e| {
535 RuntimeError::Internal(format!("knowledge delete_by_id atom hard: {e}"))
536 })?;
537 } else {
538 writer
539 .execute(SqlStatement {
540 sql: khive_runtime::sql!("knowledge_atom_soft_delete").into(),
541 params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
542 label: Some("knowledge.delete_by_id.atom.soft".into()),
543 })
544 .await
545 .map_err(|e| {
546 RuntimeError::Internal(format!("knowledge delete_by_id atom soft: {e}"))
547 })?;
548 }
549 }
550 other => {
551 return Err(RuntimeError::Internal(format!(
552 "knowledge delete_by_id: unexpected kind {other:?}"
553 )));
554 }
555 }
556
557 Ok(serde_json::json!({
558 "deleted": true,
559 "id": id_str,
560 "kind": kind,
561 "hard": hard,
562 }))
563 }
564}
565
566#[cfg(test)]
567#[path = "pack_tests.rs"]
568mod tests;