Skip to main content

khive_pack_knowledge/
pack.rs

1//! `KnowledgePack` struct, factory, and `PackRuntime` impl.
2
3use 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
24/// Knowledge corpus pack — atoms, domains, TF-IDF search, fold, import, and KG concept verbs.
25pub struct KnowledgePack {
26    pub(crate) runtime: KhiveRuntime,
27    pub(crate) ann: vamana::SharedAnn,
28    /// Pack-local Tier-3 feedback state, isolated by exact namespace.
29    ///
30    /// This fallback is used only when no configured or bound brain profile
31    /// resolves. Keying it by namespace keeps explicit measurement arms from
32    /// inheriting live/default feedback while preserving existing local behavior.
33    pub(crate) section_posteriors: Mutex<HashMap<String, SectionPosteriorState>>,
34    /// Explicit brain profile ID from config (ADR-035 §Brain profile configuration).
35    ///
36    /// Tier-1 of the 3-tier feedback resolution: when set, `knowledge.feedback` directs
37    /// section feedback through the trusted in-process brain hook. When absent, tier-2
38    /// (namespace-bound profile) and tier-3 (namespace-local prior) are tried in order.
39    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    /// Create a new pack bound to the given runtime, initializing a shared ANN index.
58    pub fn new(runtime: KhiveRuntime) -> Self {
59        Self::new_with_index_role(runtime, true)
60    }
61
62    /// As [`Self::new`], but states whether this process may build the atom
63    /// index from the full corpus. See `MemoryPack::new_with_index_role` for the
64    /// reasoning; the two packs share one index root per model family and the
65    /// same cost.
66    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        // Vamana warm may register a missing ANN consumer or publish a rebuilt
105        // checkpoint. A snapshot runtime keeps only the pure embedder warm
106        // below; it must not enter a writer-bearing ANN lifecycle.
107        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            // ADR-103 Amendment 1 Part 2: the phase span brackets ONLY this
114            // configured-embedder branch's spawned embed call, not the
115            // unconditional `warm_known_snapshots` above -- an unconditional
116            // span would record a phase for an embedder warmup that never
117            // ran whenever no embedder is configured. Minted here (before
118            // spawn) rather than inside the task: `authorize` is cheap and
119            // synchronous, and minting outside keeps the same shape as
120            // KgPack::warm's unconditional case.
121            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                // Public registry dispatch pre-applies an explicit namespace,
230                // while PackRuntime can also be called directly by embedders.
231                // A direct caller must supply a token already authorized for
232                // the requested namespace; handlers may not mint a stronger
233                // capability from an untrusted business parameter.
234                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                        // Equality proves this is capability narrowing, not
247                        // elevation. Replace any broader visible set so every
248                        // compose leg observes exactly the requested arm.
249                        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    /// Resolve a live knowledge record by UUID.
295    ///
296    /// Queries `knowledge_domains` first (canonical record), then
297    /// `knowledge_atoms`. The domain mirror atom shares the domain's UUID
298    /// (crud.rs:279/300) so domains must win over the mirror.
299    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        // 1. Check knowledge_domains first (canonical over the mirror atom).
309        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        // 2. Check knowledge_atoms.
331        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    /// Resolve a knowledge record including already-soft-deleted records.
356    ///
357    /// Used by the hard-delete path to locate tombstoned records.
358    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    /// Delete a knowledge domain or atom by UUID.
429    ///
430    /// Soft-delete by default (`hard=false`): sets `deleted_at = now()`.
431    /// For domains, also tombstones the mirror atom in `knowledge_atoms`.
432    /// Hard-delete (`hard=true`): permanently removes rows from the table(s).
433    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        // First determine the kind (including deleted rows so hard-delete can find tombstones).
438        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                    // Hard-delete: sections → mirror atom → domain (all in one transaction).
461                    // knowledge_sections has a FK to knowledge_atoms(id) without ON DELETE
462                    // CASCADE, so sections must go before the atom row.
463                    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                    // Tombstone the mirror atom so FTS no longer surfaces it.
503                    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                    // Hard-delete: sections first (FK constraint), then the atom row.
520                    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;