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