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.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                // Public registry dispatch pre-applies an explicit namespace,
231                // while PackRuntime can also be called directly by embedders.
232                // A direct caller must supply a token already authorized for
233                // the requested namespace; handlers may not mint a stronger
234                // capability from an untrusted business parameter.
235                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                        // Equality proves this is capability narrowing, not
248                        // elevation. Replace any broader visible set so every
249                        // compose leg observes exactly the requested arm.
250                        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    /// Resolve a live knowledge record by UUID.
296    ///
297    /// Queries `knowledge_domains` first (canonical record), then
298    /// `knowledge_atoms`. The domain mirror atom shares the domain's UUID
299    /// (crud.rs:279/300) so domains must win over the mirror.
300    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        // 1. Check knowledge_domains first (canonical over the mirror atom).
310        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        // 2. Check knowledge_atoms.
332        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    /// Resolve a knowledge record including already-soft-deleted records.
357    ///
358    /// Used by the hard-delete path to locate tombstoned records.
359    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    /// Delete a knowledge domain or atom by UUID.
430    ///
431    /// Soft-delete by default (`hard=false`): sets `deleted_at = now()`.
432    /// For domains, also tombstones the mirror atom in `knowledge_atoms`.
433    /// Hard-delete (`hard=true`): permanently removes rows from the table(s).
434    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        // First determine the kind (including deleted rows so hard-delete can find tombstones).
439        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                    // Hard-delete: sections → mirror atom → domain (all in one transaction).
462                    // knowledge_sections has a FK to knowledge_atoms(id) without ON DELETE
463                    // CASCADE, so sections must go before the atom row.
464                    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                    // Tombstone the mirror atom so FTS no longer surfaces it.
504                    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                    // Hard-delete: sections first (FK constraint), then the atom row.
521                    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;