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, 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
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    /// feedback to this profile via `brain.feedback`. 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}
51
52impl KnowledgePack {
53    /// Create a new pack bound to the given runtime, initializing a shared ANN index.
54    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            // ADR-103 Amendment 1 Part 2: the phase span brackets ONLY this
121            // configured-embedder branch's spawned embed call, not the
122            // unconditional `warm_known_snapshots` above -- an unconditional
123            // span would record a phase for an embedder warmup that never
124            // ran whenever no embedder is configured. Minted here (before
125            // spawn) rather than inside the task: `authorize` is cheap and
126            // synchronous, and minting outside keeps the same shape as
127            // KgPack::warm's unconditional case.
128            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                // Public registry dispatch pre-applies an explicit namespace,
233                // while PackRuntime can also be called directly by embedders.
234                // A direct caller must supply a token already authorized for
235                // the requested namespace; handlers may not mint a stronger
236                // capability from an untrusted business parameter.
237                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                        // Equality proves this is capability narrowing, not
250                        // elevation. Replace any broader visible set so every
251                        // compose leg observes exactly the requested arm.
252                        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    /// Resolve a live knowledge record by UUID.
298    ///
299    /// Queries `knowledge_domains` first (canonical record), then
300    /// `knowledge_atoms`. The domain mirror atom shares the domain's UUID
301    /// (crud.rs:279/300) so domains must win over the mirror.
302    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        // 1. Check knowledge_domains first (canonical over the mirror atom).
312        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        // 2. Check knowledge_atoms.
337        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    /// Resolve a knowledge record including already-soft-deleted records.
365    ///
366    /// Used by the hard-delete path to locate tombstoned records.
367    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    /// Delete a knowledge domain or atom by UUID.
436    ///
437    /// Soft-delete by default (`hard=false`): sets `deleted_at = now()`.
438    /// For domains, also tombstones the mirror atom in `knowledge_atoms`.
439    /// Hard-delete (`hard=true`): permanently removes rows from the table(s).
440    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        // First determine the kind (including deleted rows so hard-delete can find tombstones).
445        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                    // Hard-delete: sections → mirror atom → domain (all in one transaction).
468                    // knowledge_sections has a FK to knowledge_atoms(id) without ON DELETE
469                    // CASCADE, so sections must go before the atom row.
470                    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                    // Tombstone the mirror atom so FTS no longer surfaces it.
512                    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                    // Hard-delete: sections first (FK constraint), then the atom row.
531                    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    // ADR-103 Amendment 1 Part 2: knowledge_embedder_warm phase-span events.
587    //
588    // `KhiveRuntime::memory()` builds on `RuntimeConfig::no_embeddings()`
589    // (runtime.rs), so `default_embedder_name()` is empty and the
590    // configured-embedder branch in `KnowledgePack::warm()` never runs. This
591    // pins that gating: the unconditional `vamana::warm_known_snapshots` call
592    // above the branch must never itself emit a phase event, and the
593    // configured-only branch must not fire when unconfigured.
594    #[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}