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, SchemaPlan,
14    VerbRegistry,
15};
16use khive_storage::types::{SqlStatement, SqlValue};
17use khive_storage::{PhaseCancelledPayload, PhaseCompletedPayload, PhaseStartedPayload};
18use khive_types::{EventKind, HandlerDef, Pack};
19
20use crate::knowledge::util::{atom_from_row, atom_to_json, domain_from_row, domain_to_json};
21use crate::knowledge::vamana;
22use crate::knowledge::KnowledgeHandlers;
23use crate::vocab::{KNOWLEDGE_HANDLERS, KNOWLEDGE_SCHEMA_PLAN_STMTS};
24
25/// Knowledge corpus pack — atoms, domains, TF-IDF search, fold, import, and KG concept verbs.
26pub struct KnowledgePack {
27    pub(crate) runtime: KhiveRuntime,
28    pub(crate) ann: vamana::SharedAnn,
29    /// Pack-local Tier-3 feedback state, isolated by exact namespace.
30    ///
31    /// This fallback is used only when no configured or bound brain profile
32    /// resolves. Keying it by namespace keeps explicit measurement arms from
33    /// inheriting live/default feedback while preserving existing local behavior.
34    pub(crate) section_posteriors: Mutex<HashMap<String, SectionPosteriorState>>,
35    /// Explicit brain profile ID from config (ADR-035 §Brain profile configuration).
36    ///
37    /// Tier-1 of the 3-tier feedback resolution: when set, `knowledge.feedback` directs
38    /// section feedback through the trusted in-process brain hook. When absent, tier-2
39    /// (namespace-bound profile) and tier-3 (namespace-local prior) are tried in order.
40    pub(crate) brain_profile: Option<String>,
41}
42
43impl Pack for KnowledgePack {
44    const NAME: &'static str = "knowledge";
45    const NOTE_KINDS: &'static [&'static str] = &[];
46    const ENTITY_KINDS: &'static [&'static str] = &[];
47    const BRAIN_CONSUMER_KINDS: &'static [&'static str] =
48        &[khive_brain_core::ConsumerKind::KnowledgeCompose.as_str()];
49    const HANDLERS: &'static [HandlerDef] = &KNOWLEDGE_HANDLERS;
50    const REQUIRES: &'static [&'static str] = &["kg"];
51    const SCHEMA_PLAN: Option<PackSchemaPlan> = Some(PackSchemaPlan {
52        pack: "knowledge",
53        statements: &KNOWLEDGE_SCHEMA_PLAN_STMTS,
54    });
55}
56
57impl KnowledgePack {
58    /// Create a new pack bound to the given runtime, initializing a shared ANN index.
59    pub fn new(runtime: KhiveRuntime) -> Self {
60        Self::new_with_index_role(runtime, true)
61    }
62
63    /// As [`Self::new`], but states whether this process may build the atom
64    /// index from the full corpus. See `MemoryPack::new_with_index_role` for the
65    /// reasoning; the two packs share one index root per model family and the
66    /// same cost.
67    pub fn new_with_index_role(runtime: KhiveRuntime, builds_corpus_indexes: bool) -> Self {
68        let brain_profile = runtime.config().brain_profile.clone();
69        Self {
70            runtime,
71            ann: vamana::new_shared_for_role(builds_corpus_indexes),
72            section_posteriors: Mutex::new(HashMap::new()),
73            brain_profile,
74        }
75    }
76}
77
78struct KnowledgePackFactory;
79
80impl khive_runtime::PackFactory for KnowledgePackFactory {
81    fn name(&self) -> &'static str {
82        "knowledge"
83    }
84
85    fn requires(&self) -> &'static [&'static str] {
86        &["kg"]
87    }
88
89    fn create(&self, runtime: KhiveRuntime) -> Box<dyn khive_runtime::PackRuntime> {
90        Box::new(KnowledgePack::new_with_index_role(
91            runtime,
92            khive_runtime::daemon::is_warm_index_host(),
93        ))
94    }
95
96    fn create_resolver(
97        &self,
98        runtime: KhiveRuntime,
99    ) -> Option<Box<dyn khive_runtime::PackByIdResolver>> {
100        Some(Box::new(KnowledgePack::new(runtime)))
101    }
102}
103
104inventory::submit! { khive_runtime::PackRegistration(&KnowledgePackFactory) }
105
106#[async_trait]
107impl PackRuntime for KnowledgePack {
108    fn name(&self) -> &str {
109        <KnowledgePack as Pack>::NAME
110    }
111
112    fn note_kinds(&self) -> &'static [&'static str] {
113        <KnowledgePack as Pack>::NOTE_KINDS
114    }
115
116    fn entity_kinds(&self) -> &'static [&'static str] {
117        <KnowledgePack as Pack>::ENTITY_KINDS
118    }
119
120    fn brain_consumer_kinds(&self) -> &'static [&'static str] {
121        <KnowledgePack as Pack>::BRAIN_CONSUMER_KINDS
122    }
123
124    fn handlers(&self) -> &'static [HandlerDef] {
125        &KNOWLEDGE_HANDLERS
126    }
127
128    fn requires(&self) -> &'static [&'static str] {
129        <KnowledgePack as Pack>::REQUIRES
130    }
131
132    fn schema_plan(&self) -> SchemaPlan {
133        SchemaPlan {
134            pack: "knowledge",
135            statements: &KNOWLEDGE_SCHEMA_PLAN_STMTS,
136        }
137    }
138
139    async fn warm(&self) {
140        // Vamana warm may register a missing ANN consumer or publish a rebuilt
141        // checkpoint. A snapshot runtime keeps only the pure embedder warm
142        // below; it must not enter a writer-bearing ANN lifecycle.
143        if !self.runtime.is_read_only() {
144            crate::knowledge::vamana::warm_known_snapshots(&self.runtime, &self.ann).await;
145            crate::knowledge::vamana::start_rotation_watcher(&self.runtime, &self.ann);
146        }
147        if !self.runtime.default_embedder_name().is_empty() {
148            let runtime = self.runtime.clone();
149            // ADR-103 Amendment 1 Part 2: the phase span brackets ONLY this
150            // configured-embedder branch's spawned embed call, not the
151            // unconditional `warm_known_snapshots` above -- an unconditional
152            // span would record a phase for an embedder warmup that never
153            // ran whenever no embedder is configured. Minted here (before
154            // spawn) rather than inside the task: `authorize` is cheap and
155            // synchronous, and minting outside keeps the same shape as
156            // KgPack::warm's unconditional case.
157            let token = match runtime.authorize(khive_runtime::Namespace::local()) {
158                Ok(token) => Some(token),
159                Err(e) => {
160                    tracing::warn!(
161                        error = %e,
162                        "knowledge_embedder_warm: failed to mint ADR-103 phase-span \
163                         attribution token; warmup proceeds without telemetry"
164                    );
165                    None
166                }
167            };
168            tokio::spawn(async move {
169                if let Some(token) = &token {
170                    khive_runtime::emit_phase_event(
171                        &runtime,
172                        token,
173                        "knowledge.embedder_warm",
174                        EventKind::PhaseStarted,
175                        PhaseStartedPayload {
176                            work_class: "warm".into(),
177                            phase: "knowledge_embedder_warm".into(),
178                            corpus_size: None,
179                        },
180                    )
181                    .await;
182                }
183                let phase_start = std::time::Instant::now();
184                let cpu_start = khive_runtime::process_resource_usage();
185                let result = runtime.embed("__khive_knowledge_warm__").await;
186                if let Some(token) = &token {
187                    let wall_us = phase_start.elapsed().as_micros() as i64;
188                    let cpu_us = khive_runtime::cpu_delta_us(
189                        cpu_start,
190                        khive_runtime::process_resource_usage(),
191                    );
192                    match &result {
193                        Err(e) if khive_runtime::is_benign_shutdown_cancellation(e) => {
194                            khive_runtime::emit_phase_event(
195                                &runtime,
196                                token,
197                                "knowledge.embedder_warm",
198                                EventKind::PhaseCancelled,
199                                PhaseCancelledPayload {
200                                    work_class: "warm".into(),
201                                    phase: "knowledge_embedder_warm".into(),
202                                    wall_us,
203                                    cpu_us,
204                                },
205                            )
206                            .await;
207                        }
208                        _ => {
209                            khive_runtime::emit_phase_event(
210                                &runtime,
211                                token,
212                                "knowledge.embedder_warm",
213                                EventKind::PhaseCompleted,
214                                PhaseCompletedPayload {
215                                    work_class: "warm".into(),
216                                    phase: "knowledge_embedder_warm".into(),
217                                    wall_us,
218                                    cpu_us,
219                                },
220                            )
221                            .await;
222                        }
223                    }
224                }
225                let _ = result;
226            });
227        }
228    }
229
230    async fn dispatch(
231        &self,
232        verb: &str,
233        params: Value,
234        registry: &VerbRegistry,
235        token: &NamespaceToken,
236    ) -> Result<Value, RuntimeError> {
237        match verb {
238            "knowledge.upsert_atoms" => {
239                KnowledgeHandlers::upsert_atoms(&self.runtime, token, params).await
240            }
241            "knowledge.upsert_domains" => {
242                KnowledgeHandlers::upsert_domains(&self.runtime, token, params).await
243            }
244            "knowledge.get" => KnowledgeHandlers::get(&self.runtime, token, params).await,
245            "knowledge.list" => KnowledgeHandlers::list(&self.runtime, token, params).await,
246            "knowledge.delete_atoms" => {
247                KnowledgeHandlers::delete_atoms(&self.runtime, token, params).await
248            }
249            "knowledge.stats" => KnowledgeHandlers::stats(&self.runtime, token, params).await,
250            "knowledge.eval_retrieval" => {
251                KnowledgeHandlers::eval_retrieval(&self.runtime, token, params, &self.ann).await
252            }
253            "knowledge.index" => {
254                KnowledgeHandlers::index(&self.runtime, token, params, &self.ann, None).await
255            }
256            "knowledge.fold" => KnowledgeHandlers::fold(&self.runtime, token, params).await,
257            "knowledge.search" => {
258                KnowledgeHandlers::search(&self.runtime, token, params, &self.ann).await
259            }
260            "knowledge.suggest" => {
261                KnowledgeHandlers::suggest(&self.runtime, token, params, &self.ann).await
262            }
263            "knowledge.compose" => {
264                // Public registry dispatch pre-applies an explicit namespace,
265                // while PackRuntime can also be called directly by embedders.
266                // A direct caller must supply a token already authorized for
267                // the requested namespace; handlers may not mint a stronger
268                // capability from an untrusted business parameter.
269                let effective_token = match params.get("namespace") {
270                    None => token.clone(),
271                    Some(Value::String(ns_str)) => {
272                        let ns = Namespace::parse(ns_str).map_err(|e| {
273                            RuntimeError::InvalidInput(format!("invalid namespace {ns_str:?}: {e}"))
274                        })?;
275                        if &ns != token.namespace() {
276                            return Err(RuntimeError::InvalidInput(
277                                "knowledge.compose namespace does not match authorized token namespace"
278                                    .to_string(),
279                            ));
280                        }
281                        // Equality proves this is capability narrowing, not
282                        // elevation. Replace any broader visible set so every
283                        // compose leg observes exactly the requested arm.
284                        token.with_namespace(ns)
285                    }
286                    Some(_) => {
287                        return Err(RuntimeError::InvalidInput(
288                            "invalid namespace: expected a string".to_string(),
289                        ));
290                    }
291                };
292                let type_weights = self
293                    .resolve_compose_type_weights(registry, &effective_token)
294                    .await;
295                KnowledgeHandlers::compose(
296                    &self.runtime,
297                    &effective_token,
298                    params,
299                    &self.ann,
300                    type_weights,
301                )
302                .await
303            }
304            "knowledge.edit" => {
305                KnowledgeHandlers::edit(&self.runtime, token, params, &self.ann).await
306            }
307            "knowledge.import" => {
308                KnowledgeHandlers::import(&self.runtime, token, params, &self.ann).await
309            }
310            "knowledge.challenge" => {
311                KnowledgeHandlers::challenge(&self.runtime, token, params).await
312            }
313            "knowledge.adjudicate" => {
314                KnowledgeHandlers::adjudicate(&self.runtime, token, params).await
315            }
316            "knowledge.learn" => self.handle_learn(token, params).await,
317            "knowledge.cite" => self.handle_cite(token, params).await,
318            "knowledge.topic" => self.handle_topic(token, params).await,
319            "knowledge.feedback" => self.handle_feedback(token, params, registry).await,
320            _ => Err(RuntimeError::InvalidInput(format!(
321                "knowledge pack does not handle verb {verb:?}"
322            ))),
323        }
324    }
325}
326
327#[async_trait]
328impl PackByIdResolver for KnowledgePack {
329    /// Resolve a live knowledge record by UUID.
330    ///
331    /// Queries `knowledge_domains` first (canonical record), then
332    /// `knowledge_atoms`. The domain mirror atom shares the domain's UUID
333    /// (crud.rs:279/300) so domains must win over the mirror.
334    async fn resolve_by_id(&self, id: Uuid) -> Result<Option<Resolved>, RuntimeError> {
335        let sql = self.runtime.sql();
336        let id_str = id.to_string();
337
338        let mut reader = sql
339            .reader()
340            .await
341            .map_err(|e| RuntimeError::Internal(format!("knowledge resolve_by_id reader: {e}")))?;
342
343        // 1. Check knowledge_domains first (canonical over the mirror atom).
344        let domain_row = reader
345            .query_row(SqlStatement {
346                sql: "SELECT id, namespace, slug, name, description, tags, members, \
347                      created_at, updated_at, deleted_at \
348                      FROM knowledge_domains WHERE id = ?1 AND deleted_at IS NULL LIMIT 1"
349                    .into(),
350                params: vec![SqlValue::Text(id_str.clone())],
351                label: Some("knowledge.resolve_by_id.domain".into()),
352            })
353            .await
354            .map_err(|e| {
355                RuntimeError::Internal(format!("knowledge resolve_by_id domain query: {e}"))
356            })?;
357
358        if let Some(row) = domain_row {
359            if let Some(domain) = domain_from_row(&row) {
360                return Ok(Some(Resolved::PackRecord {
361                    pack: "knowledge".into(),
362                    kind: "domain".into(),
363                    data: domain_to_json(&domain),
364                }));
365            }
366        }
367
368        // 2. Check knowledge_atoms.
369        let atom_row = reader
370            .query_row(SqlStatement {
371                sql: "SELECT id, namespace, slug, name, content, tags, properties, \
372                      status, finalized, source_uri, source_type, created_at, updated_at, deleted_at \
373                      FROM knowledge_atoms WHERE id = ?1 AND deleted_at IS NULL LIMIT 1"
374                    .into(),
375                params: vec![SqlValue::Text(id_str)],
376                label: Some("knowledge.resolve_by_id.atom".into()),
377            })
378            .await
379            .map_err(|e| {
380                RuntimeError::Internal(format!("knowledge resolve_by_id atom query: {e}"))
381            })?;
382
383        if let Some(row) = atom_row {
384            if let Some(atom) = atom_from_row(&row) {
385                return Ok(Some(Resolved::PackRecord {
386                    pack: "knowledge".into(),
387                    kind: "atom".into(),
388                    data: atom_to_json(&atom),
389                }));
390            }
391        }
392
393        Ok(None)
394    }
395
396    /// Resolve a knowledge record including already-soft-deleted records.
397    ///
398    /// Used by the hard-delete path to locate tombstoned records.
399    async fn resolve_by_id_including_deleted(
400        &self,
401        id: Uuid,
402    ) -> Result<Option<Resolved>, RuntimeError> {
403        let sql = self.runtime.sql();
404        let id_str = id.to_string();
405
406        let mut reader = sql.reader().await.map_err(|e| {
407            RuntimeError::Internal(format!(
408                "knowledge resolve_by_id_including_deleted reader: {e}"
409            ))
410        })?;
411
412        let domain_row = reader
413            .query_row(SqlStatement {
414                sql: "SELECT id, namespace, slug, name, description, tags, members, \
415                      created_at, updated_at, deleted_at \
416                      FROM knowledge_domains WHERE id = ?1 LIMIT 1"
417                    .into(),
418                params: vec![SqlValue::Text(id_str.clone())],
419                label: Some("knowledge.resolve_by_id_incl_deleted.domain".into()),
420            })
421            .await
422            .map_err(|e| {
423                RuntimeError::Internal(format!(
424                    "knowledge resolve_by_id_including_deleted domain query: {e}"
425                ))
426            })?;
427
428        if let Some(row) = domain_row {
429            if let Some(domain) = domain_from_row(&row) {
430                return Ok(Some(Resolved::PackRecord {
431                    pack: "knowledge".into(),
432                    kind: "domain".into(),
433                    data: domain_to_json(&domain),
434                }));
435            }
436        }
437
438        let atom_row = reader
439            .query_row(SqlStatement {
440                sql: "SELECT id, namespace, slug, name, content, tags, properties, \
441                      status, finalized, source_uri, source_type, created_at, updated_at, deleted_at \
442                      FROM knowledge_atoms WHERE id = ?1 LIMIT 1"
443                    .into(),
444                params: vec![SqlValue::Text(id_str)],
445                label: Some("knowledge.resolve_by_id_incl_deleted.atom".into()),
446            })
447            .await
448            .map_err(|e| {
449                RuntimeError::Internal(format!(
450                    "knowledge resolve_by_id_including_deleted atom query: {e}"
451                ))
452            })?;
453
454        if let Some(row) = atom_row {
455            if let Some(atom) = atom_from_row(&row) {
456                return Ok(Some(Resolved::PackRecord {
457                    pack: "knowledge".into(),
458                    kind: "atom".into(),
459                    data: atom_to_json(&atom),
460                }));
461            }
462        }
463
464        Ok(None)
465    }
466
467    fn private_record_verbs(&self) -> &'static [&'static str] {
468        &[
469            "knowledge.upsert_atoms",
470            "knowledge.upsert_domains",
471            "knowledge.edit",
472        ]
473    }
474
475    /// Delete a knowledge domain or atom by UUID.
476    ///
477    /// Soft-delete by default (`hard=false`): sets `deleted_at = now()`.
478    /// For domains, also tombstones the mirror atom in `knowledge_atoms`.
479    /// Hard-delete (`hard=true`): permanently removes rows from the table(s).
480    async fn delete_by_id(&self, id: Uuid, hard: bool) -> Result<serde_json::Value, RuntimeError> {
481        let sql = self.runtime.sql();
482        let id_str = id.to_string();
483
484        // First determine the kind (including deleted rows so hard-delete can find tombstones).
485        let kind = match self.resolve_by_id_including_deleted(id).await? {
486            Some(Resolved::PackRecord { kind, .. }) => kind,
487            _ => {
488                return Err(RuntimeError::NotFound(format!(
489                    "knowledge record not found: {id}"
490                )));
491            }
492        };
493
494        let now_us = std::time::SystemTime::now()
495            .duration_since(std::time::UNIX_EPOCH)
496            .unwrap_or_default()
497            .as_micros() as i64;
498
499        let mut writer = sql
500            .writer()
501            .await
502            .map_err(|e| RuntimeError::Internal(format!("knowledge delete_by_id writer: {e}")))?;
503
504        match kind.as_str() {
505            "domain" => {
506                if hard {
507                    // Hard-delete: sections → mirror atom → domain (all in one transaction).
508                    // knowledge_sections has a FK to knowledge_atoms(id) without ON DELETE
509                    // CASCADE, so sections must go before the atom row.
510                    writer
511                        .execute_batch(vec![
512                            SqlStatement {
513                                sql: "DELETE FROM knowledge_sections WHERE atom_id = ?1".into(),
514                                params: vec![SqlValue::Text(id_str.clone())],
515                                label: Some(
516                                    "knowledge.delete_by_id.domain_mirror_sections.hard".into(),
517                                ),
518                            },
519                            SqlStatement {
520                                sql: "DELETE FROM knowledge_atoms WHERE id = ?1".into(),
521                                params: vec![SqlValue::Text(id_str.clone())],
522                                label: Some("knowledge.delete_by_id.domain_mirror.hard".into()),
523                            },
524                            SqlStatement {
525                                sql: "DELETE FROM knowledge_domains WHERE id = ?1".into(),
526                                params: vec![SqlValue::Text(id_str.clone())],
527                                label: Some("knowledge.delete_by_id.domain.hard".into()),
528                            },
529                        ])
530                        .await
531                        .map_err(|e| {
532                            RuntimeError::Internal(format!(
533                                "knowledge delete_by_id domain hard: {e}"
534                            ))
535                        })?;
536                } else {
537                    writer
538                        .execute(SqlStatement {
539                            sql: "UPDATE knowledge_domains SET deleted_at = ?1 \
540                                  WHERE id = ?2 AND deleted_at IS NULL"
541                                .into(),
542                            params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
543                            label: Some("knowledge.delete_by_id.domain.soft".into()),
544                        })
545                        .await
546                        .map_err(|e| {
547                            RuntimeError::Internal(format!(
548                                "knowledge delete_by_id domain soft: {e}"
549                            ))
550                        })?;
551                    // Tombstone the mirror atom so FTS no longer surfaces it.
552                    writer
553                        .execute(SqlStatement {
554                            sql: "UPDATE knowledge_atoms SET deleted_at = ?1 \
555                                  WHERE id = ?2 AND deleted_at IS NULL"
556                                .into(),
557                            params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
558                            label: Some("knowledge.delete_by_id.domain_mirror.soft".into()),
559                        })
560                        .await
561                        .map_err(|e| {
562                            RuntimeError::Internal(format!(
563                                "knowledge delete_by_id domain mirror soft: {e}"
564                            ))
565                        })?;
566                }
567            }
568            "atom" => {
569                if hard {
570                    // Hard-delete: sections first (FK constraint), then the atom row.
571                    writer
572                        .execute_batch(vec![
573                            SqlStatement {
574                                sql: "DELETE FROM knowledge_sections WHERE atom_id = ?1".into(),
575                                params: vec![SqlValue::Text(id_str.clone())],
576                                label: Some("knowledge.delete_by_id.atom_sections.hard".into()),
577                            },
578                            SqlStatement {
579                                sql: "DELETE FROM knowledge_atoms WHERE id = ?1".into(),
580                                params: vec![SqlValue::Text(id_str.clone())],
581                                label: Some("knowledge.delete_by_id.atom.hard".into()),
582                            },
583                        ])
584                        .await
585                        .map_err(|e| {
586                            RuntimeError::Internal(format!("knowledge delete_by_id atom hard: {e}"))
587                        })?;
588                } else {
589                    writer
590                        .execute(SqlStatement {
591                            sql: "UPDATE knowledge_atoms SET deleted_at = ?1 \
592                                  WHERE id = ?2 AND deleted_at IS NULL"
593                                .into(),
594                            params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
595                            label: Some("knowledge.delete_by_id.atom.soft".into()),
596                        })
597                        .await
598                        .map_err(|e| {
599                            RuntimeError::Internal(format!("knowledge delete_by_id atom soft: {e}"))
600                        })?;
601                }
602            }
603            other => {
604                return Err(RuntimeError::Internal(format!(
605                    "knowledge delete_by_id: unexpected kind {other:?}"
606                )));
607            }
608        }
609
610        Ok(serde_json::json!({
611            "deleted": true,
612            "id": id_str,
613            "kind": kind,
614            "hard": hard,
615        }))
616    }
617}
618
619#[cfg(test)]
620mod tests {
621    use khive_runtime::pack::PackRuntime;
622    use khive_runtime::{KhiveRuntime, Namespace, RuntimeConfig};
623    use lattice_embed::EmbeddingModel;
624
625    use super::KnowledgePack;
626
627    // ADR-103 Amendment 1 Part 2: knowledge_embedder_warm phase-span events.
628    //
629    // `KhiveRuntime::memory()` builds on `RuntimeConfig::no_embeddings()`
630    // (runtime.rs), so `default_embedder_name()` is empty and the
631    // configured-embedder branch in `KnowledgePack::warm()` never runs. This
632    // pins that gating: the unconditional `vamana::warm_known_snapshots` call
633    // above the branch must never itself emit a phase event, and the
634    // configured-only branch must not fire when unconfigured.
635    #[tokio::test]
636    async fn knowledge_warm_emits_no_phase_events_when_no_embedder_configured() {
637        let rt = KhiveRuntime::memory().expect("in-memory runtime");
638        let token = rt.authorize(Namespace::local()).expect("authorize local");
639        let event_store = rt.events(&token).expect("event store must be available");
640
641        let pack = KnowledgePack::new(rt.clone());
642        pack.warm().await;
643
644        let page = event_store
645            .query_events(
646                khive_storage::EventFilter::default(),
647                khive_storage::PageRequest {
648                    limit: 10,
649                    offset: 0,
650                },
651            )
652            .await
653            .expect("query events");
654
655        assert!(
656            page.items.is_empty(),
657            "no embedder configured -> KnowledgePack::warm() must emit zero phase events \
658             (configured-only branch must not fire, and warm_known_snapshots must not \
659             independently emit): {:?}",
660            page.items
661        );
662    }
663
664    #[tokio::test]
665    async fn read_only_knowledge_cache_miss_does_not_start_ann_writer_lifecycle() {
666        let dir = tempfile::tempdir().expect("tempdir");
667        let config = RuntimeConfig {
668            db_path: Some(dir.path().join("read-only-knowledge-ann.db")),
669            embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
670            additional_embedding_models: vec![],
671            ..RuntimeConfig::no_embeddings()
672        };
673        drop(KhiveRuntime::new(config.clone()).expect("migrate snapshot source"));
674
675        #[cfg(unix)]
676        {
677            let db_path = config.db_path.as_ref().expect("db path");
678            khive_storage::test_support::freeze_snapshot_sidecars(db_path);
679        }
680
681        let read_only = KhiveRuntime::new_readonly(config).expect("open snapshot read-only");
682        let token = read_only
683            .authorize(Namespace::local())
684            .expect("authorize local");
685        let pack = KnowledgePack::new(read_only.clone());
686        let key = crate::knowledge::vamana::AnnKey::new(
687            token.namespace().as_str(),
688            read_only.default_embedder_name(),
689        );
690        let before = read_only.backend().pool().writer_acquisition_snapshot();
691
692        crate::knowledge::vamana::ensure_ann_background(&read_only, &token, &pack.ann);
693
694        assert!(
695            !crate::knowledge::vamana::is_warming_not_loaded(&pack.ann, &key),
696            "a read-only search cache miss must not claim or spawn an ANN warm slot"
697        );
698        assert_eq!(
699            read_only.backend().pool().writer_acquisition_snapshot(),
700            before,
701            "read-only ANN admission must not acquire a writer"
702        );
703    }
704
705    /// Pack-level lifecycle coverage for `start_rotation_watcher`'s
706    /// production wiring (issue #2340): the rotation tests elsewhere in this
707    /// crate call the private `refresh_rotated_segments_once` test helper
708    /// directly, so nothing previously asserted that a writable `warm()`
709    /// actually starts the tracked watcher, that a repeated `warm()` is
710    /// idempotent, or that the watcher exits once its `AnnState` is dropped.
711    /// Time is paused so the watcher's 5-second tick can be crossed
712    /// deterministically instead of by a real sleep.
713    #[tokio::test(start_paused = true)]
714    #[serial_test::serial(background_tasks)]
715    async fn writable_warm_starts_one_tracked_watcher_idempotently_and_it_exits_on_drop() {
716        let dir = tempfile::tempdir().expect("tempdir");
717        let config = RuntimeConfig {
718            db_path: Some(dir.path().join("rotation-watcher-lifecycle.db")),
719            embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
720            additional_embedding_models: vec![],
721            ..RuntimeConfig::no_embeddings()
722        };
723        let rt = KhiveRuntime::new(config).expect("writable runtime");
724        let pack = KnowledgePack::new(rt);
725
726        let before = khive_runtime::background_task_count();
727        pack.warm().await;
728        assert!(
729            crate::knowledge::vamana::rotation_watch_started_for_test(&pack.ann),
730            "a writable warm must start the rotation watcher"
731        );
732        assert_eq!(
733            khive_runtime::background_task_count(),
734            before + 1,
735            "warm must track exactly one rotation watcher task"
736        );
737
738        // A repeated warm must not start a second tracked watcher.
739        pack.warm().await;
740        assert_eq!(
741            khive_runtime::background_task_count(),
742            before + 1,
743            "a repeated warm must be idempotent and not start a second watcher"
744        );
745
746        // The watcher retains only a Weak<AnnState>; dropping every strong
747        // reference lets its next tick observe the failed upgrade and exit.
748        let ann_weak = std::sync::Arc::downgrade(&pack.ann);
749        drop(pack);
750        assert!(
751            ann_weak.upgrade().is_none(),
752            "dropping the pack must drop its last strong ANN reference"
753        );
754
755        // The watcher builds its interval on its first poll, which can land
756        // after this advance; under paused time `sleep` auto-advances the
757        // clock once every task is idle, so the tick is reached by virtual
758        // time rather than by a fixed yield budget.
759        tokio::time::advance(std::time::Duration::from_secs(6)).await;
760        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(60);
761        while khive_runtime::background_task_count() != before {
762            assert!(
763                tokio::time::Instant::now() < deadline,
764                "the watcher must exit once its ANN state is dropped"
765            );
766            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
767        }
768        assert_eq!(
769            khive_runtime::background_task_count(),
770            before,
771            "the watcher must exit once its ANN state is dropped"
772        );
773    }
774}