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.delete_atoms" => {
211                KnowledgeHandlers::delete_atoms(&self.runtime, token, params).await
212            }
213            "knowledge.stats" => KnowledgeHandlers::stats(&self.runtime, token, params).await,
214            "knowledge.eval_retrieval" => {
215                KnowledgeHandlers::eval_retrieval(&self.runtime, token, params, &self.ann).await
216            }
217            "knowledge.index" => {
218                KnowledgeHandlers::index(&self.runtime, token, params, &self.ann, None).await
219            }
220            "knowledge.fold" => KnowledgeHandlers::fold(&self.runtime, token, params).await,
221            "knowledge.search" => {
222                KnowledgeHandlers::search(&self.runtime, token, params, &self.ann).await
223            }
224            "knowledge.suggest" => {
225                KnowledgeHandlers::suggest(&self.runtime, token, params, &self.ann).await
226            }
227            "knowledge.compose" => {
228                // Public registry dispatch pre-applies an explicit namespace,
229                // while PackRuntime can also be called directly by embedders.
230                // A direct caller must supply a token already authorized for
231                // the requested namespace; handlers may not mint a stronger
232                // capability from an untrusted business parameter.
233                let effective_token = match params.get("namespace") {
234                    None => token.clone(),
235                    Some(Value::String(ns_str)) => {
236                        let ns = Namespace::parse(ns_str).map_err(|e| {
237                            RuntimeError::InvalidInput(format!("invalid namespace {ns_str:?}: {e}"))
238                        })?;
239                        if &ns != token.namespace() {
240                            return Err(RuntimeError::InvalidInput(
241                                "knowledge.compose namespace does not match authorized token namespace"
242                                    .to_string(),
243                            ));
244                        }
245                        // Equality proves this is capability narrowing, not
246                        // elevation. Replace any broader visible set so every
247                        // compose leg observes exactly the requested arm.
248                        token.with_namespace(ns)
249                    }
250                    Some(_) => {
251                        return Err(RuntimeError::InvalidInput(
252                            "invalid namespace: expected a string".to_string(),
253                        ));
254                    }
255                };
256                let type_weights = self
257                    .resolve_compose_type_weights(registry, &effective_token)
258                    .await;
259                KnowledgeHandlers::compose(
260                    &self.runtime,
261                    &effective_token,
262                    params,
263                    &self.ann,
264                    type_weights,
265                )
266                .await
267            }
268            "knowledge.edit" => {
269                KnowledgeHandlers::edit(&self.runtime, token, params, &self.ann).await
270            }
271            "knowledge.import" => {
272                KnowledgeHandlers::import(&self.runtime, token, params, &self.ann).await
273            }
274            "knowledge.challenge" => {
275                KnowledgeHandlers::challenge(&self.runtime, token, params).await
276            }
277            "knowledge.adjudicate" => {
278                KnowledgeHandlers::adjudicate(&self.runtime, token, params).await
279            }
280            "knowledge.learn" => self.handle_learn(token, params).await,
281            "knowledge.cite" => self.handle_cite(token, params).await,
282            "knowledge.topic" => self.handle_topic(token, params).await,
283            "knowledge.feedback" => self.handle_feedback(token, params, registry).await,
284            _ => Err(RuntimeError::InvalidInput(format!(
285                "knowledge pack does not handle verb {verb:?}"
286            ))),
287        }
288    }
289}
290
291#[async_trait]
292impl PackByIdResolver for KnowledgePack {
293    /// Resolve a live knowledge record by UUID.
294    ///
295    /// Queries `knowledge_domains` first (canonical record), then
296    /// `knowledge_atoms`. The domain mirror atom shares the domain's UUID
297    /// (crud.rs:279/300) so domains must win over the mirror.
298    async fn resolve_by_id(&self, id: Uuid) -> Result<Option<Resolved>, RuntimeError> {
299        let sql = self.runtime.sql();
300        let id_str = id.to_string();
301
302        let mut reader = sql
303            .reader()
304            .await
305            .map_err(|e| RuntimeError::Internal(format!("knowledge resolve_by_id reader: {e}")))?;
306
307        // 1. Check knowledge_domains first (canonical over the mirror atom).
308        let domain_row = reader
309            .query_row(SqlStatement {
310                sql: khive_runtime::sql!("knowledge_resolver_live_domain").into(),
311                params: vec![SqlValue::Text(id_str.clone())],
312                label: Some("knowledge.resolve_by_id.domain".into()),
313            })
314            .await
315            .map_err(|e| {
316                RuntimeError::Internal(format!("knowledge resolve_by_id domain query: {e}"))
317            })?;
318
319        if let Some(row) = domain_row {
320            if let Some(domain) = domain_from_row(&row) {
321                return Ok(Some(Resolved::PackRecord {
322                    pack: "knowledge".into(),
323                    kind: "domain".into(),
324                    data: domain_to_json(&domain),
325                }));
326            }
327        }
328
329        // 2. Check knowledge_atoms.
330        let atom_row = reader
331            .query_row(SqlStatement {
332                sql: khive_runtime::sql!("knowledge_resolver_live_atom").into(),
333                params: vec![SqlValue::Text(id_str)],
334                label: Some("knowledge.resolve_by_id.atom".into()),
335            })
336            .await
337            .map_err(|e| {
338                RuntimeError::Internal(format!("knowledge resolve_by_id atom query: {e}"))
339            })?;
340
341        if let Some(row) = atom_row {
342            if let Some(atom) = atom_from_row(&row) {
343                return Ok(Some(Resolved::PackRecord {
344                    pack: "knowledge".into(),
345                    kind: "atom".into(),
346                    data: atom_to_json(&atom),
347                }));
348            }
349        }
350
351        Ok(None)
352    }
353
354    /// Resolve a knowledge record including already-soft-deleted records.
355    ///
356    /// Used by the hard-delete path to locate tombstoned records.
357    async fn resolve_by_id_including_deleted(
358        &self,
359        id: Uuid,
360    ) -> Result<Option<Resolved>, RuntimeError> {
361        let sql = self.runtime.sql();
362        let id_str = id.to_string();
363
364        let mut reader = sql.reader().await.map_err(|e| {
365            RuntimeError::Internal(format!(
366                "knowledge resolve_by_id_including_deleted reader: {e}"
367            ))
368        })?;
369
370        let domain_row = reader
371            .query_row(SqlStatement {
372                sql: khive_runtime::sql!("knowledge_resolver_domain_including_deleted").into(),
373                params: vec![SqlValue::Text(id_str.clone())],
374                label: Some("knowledge.resolve_by_id_incl_deleted.domain".into()),
375            })
376            .await
377            .map_err(|e| {
378                RuntimeError::Internal(format!(
379                    "knowledge resolve_by_id_including_deleted domain query: {e}"
380                ))
381            })?;
382
383        if let Some(row) = domain_row {
384            if let Some(domain) = domain_from_row(&row) {
385                return Ok(Some(Resolved::PackRecord {
386                    pack: "knowledge".into(),
387                    kind: "domain".into(),
388                    data: domain_to_json(&domain),
389                }));
390            }
391        }
392
393        let atom_row = reader
394            .query_row(SqlStatement {
395                sql: khive_runtime::sql!("knowledge_resolver_atom_including_deleted").into(),
396                params: vec![SqlValue::Text(id_str)],
397                label: Some("knowledge.resolve_by_id_incl_deleted.atom".into()),
398            })
399            .await
400            .map_err(|e| {
401                RuntimeError::Internal(format!(
402                    "knowledge resolve_by_id_including_deleted atom query: {e}"
403                ))
404            })?;
405
406        if let Some(row) = atom_row {
407            if let Some(atom) = atom_from_row(&row) {
408                return Ok(Some(Resolved::PackRecord {
409                    pack: "knowledge".into(),
410                    kind: "atom".into(),
411                    data: atom_to_json(&atom),
412                }));
413            }
414        }
415
416        Ok(None)
417    }
418
419    fn private_record_verbs(&self) -> &'static [&'static str] {
420        &[
421            "knowledge.upsert_atoms",
422            "knowledge.upsert_domains",
423            "knowledge.edit",
424        ]
425    }
426
427    /// Delete a knowledge domain or atom by UUID.
428    ///
429    /// Soft-delete by default (`hard=false`): sets `deleted_at = now()`.
430    /// For domains, also tombstones the mirror atom in `knowledge_atoms`.
431    /// Hard-delete (`hard=true`): permanently removes rows from the table(s).
432    async fn delete_by_id(&self, id: Uuid, hard: bool) -> Result<serde_json::Value, RuntimeError> {
433        let sql = self.runtime.sql();
434        let id_str = id.to_string();
435
436        // First determine the kind (including deleted rows so hard-delete can find tombstones).
437        let kind = match self.resolve_by_id_including_deleted(id).await? {
438            Some(Resolved::PackRecord { kind, .. }) => kind,
439            _ => {
440                return Err(RuntimeError::NotFound(format!(
441                    "knowledge record not found: {id}"
442                )));
443            }
444        };
445
446        let now_us = std::time::SystemTime::now()
447            .duration_since(std::time::UNIX_EPOCH)
448            .unwrap_or_default()
449            .as_micros() as i64;
450
451        let mut writer = sql
452            .writer()
453            .await
454            .map_err(|e| RuntimeError::Internal(format!("knowledge delete_by_id writer: {e}")))?;
455
456        match kind.as_str() {
457            "domain" => {
458                if hard {
459                    // Hard-delete: sections → mirror atom → domain (all in one transaction).
460                    // knowledge_sections has a FK to knowledge_atoms(id) without ON DELETE
461                    // CASCADE, so sections must go before the atom row.
462                    writer
463                        .execute_batch(vec![
464                            SqlStatement {
465                                sql: khive_runtime::sql!("knowledge_atom_sections_delete").into(),
466                                params: vec![SqlValue::Text(id_str.clone())],
467                                label: Some(
468                                    "knowledge.delete_by_id.domain_mirror_sections.hard".into(),
469                                ),
470                            },
471                            SqlStatement {
472                                sql: khive_runtime::sql!("knowledge_atom_hard_delete").into(),
473                                params: vec![SqlValue::Text(id_str.clone())],
474                                label: Some("knowledge.delete_by_id.domain_mirror.hard".into()),
475                            },
476                            SqlStatement {
477                                sql: khive_runtime::sql!("knowledge_domain_hard_delete").into(),
478                                params: vec![SqlValue::Text(id_str.clone())],
479                                label: Some("knowledge.delete_by_id.domain.hard".into()),
480                            },
481                        ])
482                        .await
483                        .map_err(|e| {
484                            RuntimeError::Internal(format!(
485                                "knowledge delete_by_id domain hard: {e}"
486                            ))
487                        })?;
488                } else {
489                    writer
490                        .execute(SqlStatement {
491                            sql: khive_runtime::sql!("knowledge_domain_soft_delete").into(),
492                            params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
493                            label: Some("knowledge.delete_by_id.domain.soft".into()),
494                        })
495                        .await
496                        .map_err(|e| {
497                            RuntimeError::Internal(format!(
498                                "knowledge delete_by_id domain soft: {e}"
499                            ))
500                        })?;
501                    // Tombstone the mirror atom so FTS no longer surfaces it.
502                    writer
503                        .execute(SqlStatement {
504                            sql: khive_runtime::sql!("knowledge_atom_soft_delete").into(),
505                            params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
506                            label: Some("knowledge.delete_by_id.domain_mirror.soft".into()),
507                        })
508                        .await
509                        .map_err(|e| {
510                            RuntimeError::Internal(format!(
511                                "knowledge delete_by_id domain mirror soft: {e}"
512                            ))
513                        })?;
514                }
515            }
516            "atom" => {
517                if hard {
518                    // Hard-delete: sections first (FK constraint), then the atom row.
519                    writer
520                        .execute_batch(vec![
521                            SqlStatement {
522                                sql: khive_runtime::sql!("knowledge_atom_sections_delete").into(),
523                                params: vec![SqlValue::Text(id_str.clone())],
524                                label: Some("knowledge.delete_by_id.atom_sections.hard".into()),
525                            },
526                            SqlStatement {
527                                sql: khive_runtime::sql!("knowledge_atom_hard_delete").into(),
528                                params: vec![SqlValue::Text(id_str.clone())],
529                                label: Some("knowledge.delete_by_id.atom.hard".into()),
530                            },
531                        ])
532                        .await
533                        .map_err(|e| {
534                            RuntimeError::Internal(format!("knowledge delete_by_id atom hard: {e}"))
535                        })?;
536                } else {
537                    writer
538                        .execute(SqlStatement {
539                            sql: khive_runtime::sql!("knowledge_atom_soft_delete").into(),
540                            params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
541                            label: Some("knowledge.delete_by_id.atom.soft".into()),
542                        })
543                        .await
544                        .map_err(|e| {
545                            RuntimeError::Internal(format!("knowledge delete_by_id atom soft: {e}"))
546                        })?;
547                }
548            }
549            other => {
550                return Err(RuntimeError::Internal(format!(
551                    "knowledge delete_by_id: unexpected kind {other:?}"
552                )));
553            }
554        }
555
556        Ok(serde_json::json!({
557            "deleted": true,
558            "id": id_str,
559            "kind": kind,
560            "hard": hard,
561        }))
562    }
563}
564
565#[cfg(test)]
566mod tests {
567    use khive_runtime::pack::PackRuntime;
568    use khive_runtime::{KhiveRuntime, Namespace, RuntimeConfig};
569    use lattice_embed::EmbeddingModel;
570
571    use super::KnowledgePack;
572
573    // ADR-103 Amendment 1 Part 2: knowledge_embedder_warm phase-span events.
574    //
575    // `KhiveRuntime::memory()` builds on `RuntimeConfig::no_embeddings()`
576    // (runtime.rs), so `default_embedder_name()` is empty and the
577    // configured-embedder branch in `KnowledgePack::warm()` never runs. This
578    // pins that gating: the unconditional `vamana::warm_known_snapshots` call
579    // above the branch must never itself emit a phase event, and the
580    // configured-only branch must not fire when unconfigured.
581    #[tokio::test]
582    async fn knowledge_warm_emits_no_phase_events_when_no_embedder_configured() {
583        let rt = KhiveRuntime::memory().expect("in-memory runtime");
584        let token = rt.authorize(Namespace::local()).expect("authorize local");
585        let event_store = rt.events(&token).expect("event store must be available");
586
587        let pack = KnowledgePack::new(rt.clone());
588        pack.warm().await;
589
590        let page = event_store
591            .query_events(
592                khive_storage::EventFilter::default(),
593                khive_storage::PageRequest {
594                    limit: 10,
595                    offset: 0,
596                },
597            )
598            .await
599            .expect("query events");
600
601        assert!(
602            page.items.is_empty(),
603            "no embedder configured -> KnowledgePack::warm() must emit zero phase events \
604             (configured-only branch must not fire, and warm_known_snapshots must not \
605             independently emit): {:?}",
606            page.items
607        );
608    }
609
610    #[tokio::test]
611    async fn read_only_knowledge_cache_miss_does_not_start_ann_writer_lifecycle() {
612        let dir = tempfile::tempdir().expect("tempdir");
613        let config = RuntimeConfig {
614            db_path: Some(dir.path().join("read-only-knowledge-ann.db")),
615            embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
616            additional_embedding_models: vec![],
617            ..RuntimeConfig::no_embeddings()
618        };
619        drop(KhiveRuntime::new(config.clone()).expect("migrate snapshot source"));
620
621        #[cfg(unix)]
622        {
623            let db_path = config.db_path.as_ref().expect("db path");
624            khive_storage::test_support::freeze_snapshot_sidecars(db_path);
625        }
626
627        let read_only = KhiveRuntime::new_readonly(config).expect("open snapshot read-only");
628        let token = read_only
629            .authorize(Namespace::local())
630            .expect("authorize local");
631        let pack = KnowledgePack::new(read_only.clone());
632        let key = crate::knowledge::vamana::AnnKey::new(
633            token.namespace().as_str(),
634            read_only.default_embedder_name(),
635        );
636        let before = read_only.backend().pool().writer_acquisition_snapshot();
637
638        crate::knowledge::vamana::ensure_ann_background(&read_only, &token, &pack.ann);
639
640        assert!(
641            !crate::knowledge::vamana::is_warming_not_loaded(&pack.ann, &key),
642            "a read-only search cache miss must not claim or spawn an ANN warm slot"
643        );
644        assert_eq!(
645            read_only.backend().pool().writer_acquisition_snapshot(),
646            before,
647            "read-only ANN admission must not acquire a writer"
648        );
649    }
650
651    /// Pack-level lifecycle coverage for `start_rotation_watcher`'s
652    /// production wiring (issue #2340): the rotation tests elsewhere in this
653    /// crate call the private `refresh_rotated_segments_once` test helper
654    /// directly, so nothing previously asserted that a writable `warm()`
655    /// actually starts the tracked watcher, that a repeated `warm()` is
656    /// idempotent, or that the watcher exits once its `AnnState` is dropped.
657    /// Time is paused so the watcher's 5-second tick can be crossed
658    /// deterministically instead of by a real sleep.
659    #[tokio::test(start_paused = true)]
660    #[serial_test::serial(background_tasks)]
661    async fn writable_warm_starts_one_tracked_watcher_idempotently_and_it_exits_on_drop() {
662        let dir = tempfile::tempdir().expect("tempdir");
663        let config = RuntimeConfig {
664            db_path: Some(dir.path().join("rotation-watcher-lifecycle.db")),
665            embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
666            additional_embedding_models: vec![],
667            ..RuntimeConfig::no_embeddings()
668        };
669        let rt = KhiveRuntime::new(config).expect("writable runtime");
670        let pack = KnowledgePack::new(rt);
671
672        let before = khive_runtime::background_task_count();
673        pack.warm().await;
674        assert!(
675            crate::knowledge::vamana::rotation_watch_started_for_test(&pack.ann),
676            "a writable warm must start the rotation watcher"
677        );
678        assert_eq!(
679            khive_runtime::background_task_count(),
680            before + 1,
681            "warm must track exactly one rotation watcher task"
682        );
683
684        // A repeated warm must not start a second tracked watcher.
685        pack.warm().await;
686        assert_eq!(
687            khive_runtime::background_task_count(),
688            before + 1,
689            "a repeated warm must be idempotent and not start a second watcher"
690        );
691
692        // The watcher retains only a Weak<AnnState>; dropping every strong
693        // reference lets its next tick observe the failed upgrade and exit.
694        let ann_weak = std::sync::Arc::downgrade(&pack.ann);
695        drop(pack);
696        assert!(
697            ann_weak.upgrade().is_none(),
698            "dropping the pack must drop its last strong ANN reference"
699        );
700
701        // The watcher builds its interval on its first poll, which can land
702        // after this advance; under paused time `sleep` auto-advances the
703        // clock once every task is idle, so the tick is reached by virtual
704        // time rather than by a fixed yield budget.
705        tokio::time::advance(std::time::Duration::from_secs(6)).await;
706        let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(60);
707        while khive_runtime::background_task_count() != before {
708            assert!(
709                tokio::time::Instant::now() < deadline,
710                "the watcher must exit once its ANN state is dropped"
711            );
712            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
713        }
714        assert_eq!(
715            khive_runtime::background_task_count(),
716            before,
717            "the watcher must exit once its ANN state is dropped"
718        );
719    }
720}