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    /// feedback to this profile via `brain.feedback`. 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        let brain_profile = runtime.config().brain_profile.clone();
61        Self {
62            runtime,
63            ann: vamana::new_shared(),
64            section_posteriors: Mutex::new(HashMap::new()),
65            brain_profile,
66        }
67    }
68}
69
70struct KnowledgePackFactory;
71
72impl khive_runtime::PackFactory for KnowledgePackFactory {
73    fn name(&self) -> &'static str {
74        "knowledge"
75    }
76
77    fn requires(&self) -> &'static [&'static str] {
78        &["kg"]
79    }
80
81    fn create(&self, runtime: KhiveRuntime) -> Box<dyn khive_runtime::PackRuntime> {
82        Box::new(KnowledgePack::new(runtime))
83    }
84
85    fn create_resolver(
86        &self,
87        runtime: KhiveRuntime,
88    ) -> Option<Box<dyn khive_runtime::PackByIdResolver>> {
89        Some(Box::new(KnowledgePack::new(runtime)))
90    }
91}
92
93inventory::submit! { khive_runtime::PackRegistration(&KnowledgePackFactory) }
94
95#[async_trait]
96impl PackRuntime for KnowledgePack {
97    fn name(&self) -> &str {
98        <KnowledgePack as Pack>::NAME
99    }
100
101    fn note_kinds(&self) -> &'static [&'static str] {
102        <KnowledgePack as Pack>::NOTE_KINDS
103    }
104
105    fn entity_kinds(&self) -> &'static [&'static str] {
106        <KnowledgePack as Pack>::ENTITY_KINDS
107    }
108
109    fn brain_consumer_kinds(&self) -> &'static [&'static str] {
110        <KnowledgePack as Pack>::BRAIN_CONSUMER_KINDS
111    }
112
113    fn handlers(&self) -> &'static [HandlerDef] {
114        &KNOWLEDGE_HANDLERS
115    }
116
117    fn requires(&self) -> &'static [&'static str] {
118        <KnowledgePack as Pack>::REQUIRES
119    }
120
121    fn schema_plan(&self) -> SchemaPlan {
122        SchemaPlan {
123            pack: "knowledge",
124            statements: &KNOWLEDGE_SCHEMA_PLAN_STMTS,
125        }
126    }
127
128    async fn warm(&self) {
129        // Vamana warm may register a missing ANN consumer or publish a rebuilt
130        // checkpoint. A snapshot runtime keeps only the pure embedder warm
131        // below; it must not enter a writer-bearing ANN lifecycle.
132        if !self.runtime.is_read_only() {
133            crate::knowledge::vamana::warm_known_snapshots(&self.runtime, &self.ann).await;
134        }
135        if !self.runtime.default_embedder_name().is_empty() {
136            let runtime = self.runtime.clone();
137            // ADR-103 Amendment 1 Part 2: the phase span brackets ONLY this
138            // configured-embedder branch's spawned embed call, not the
139            // unconditional `warm_known_snapshots` above -- an unconditional
140            // span would record a phase for an embedder warmup that never
141            // ran whenever no embedder is configured. Minted here (before
142            // spawn) rather than inside the task: `authorize` is cheap and
143            // synchronous, and minting outside keeps the same shape as
144            // KgPack::warm's unconditional case.
145            let token = match runtime.authorize(khive_runtime::Namespace::local()) {
146                Ok(token) => Some(token),
147                Err(e) => {
148                    tracing::warn!(
149                        error = %e,
150                        "knowledge_embedder_warm: failed to mint ADR-103 phase-span \
151                         attribution token; warmup proceeds without telemetry"
152                    );
153                    None
154                }
155            };
156            tokio::spawn(async move {
157                if let Some(token) = &token {
158                    khive_runtime::emit_phase_event(
159                        &runtime,
160                        token,
161                        "knowledge.embedder_warm",
162                        EventKind::PhaseStarted,
163                        PhaseStartedPayload {
164                            work_class: "warm".into(),
165                            phase: "knowledge_embedder_warm".into(),
166                            corpus_size: None,
167                        },
168                    )
169                    .await;
170                }
171                let phase_start = std::time::Instant::now();
172                let cpu_start = khive_runtime::process_resource_usage();
173                let result = runtime.embed("__khive_knowledge_warm__").await;
174                if let Some(token) = &token {
175                    let wall_us = phase_start.elapsed().as_micros() as i64;
176                    let cpu_us = khive_runtime::cpu_delta_us(
177                        cpu_start,
178                        khive_runtime::process_resource_usage(),
179                    );
180                    match &result {
181                        Err(e) if khive_runtime::is_benign_shutdown_cancellation(e) => {
182                            khive_runtime::emit_phase_event(
183                                &runtime,
184                                token,
185                                "knowledge.embedder_warm",
186                                EventKind::PhaseCancelled,
187                                PhaseCancelledPayload {
188                                    work_class: "warm".into(),
189                                    phase: "knowledge_embedder_warm".into(),
190                                    wall_us,
191                                    cpu_us,
192                                },
193                            )
194                            .await;
195                        }
196                        _ => {
197                            khive_runtime::emit_phase_event(
198                                &runtime,
199                                token,
200                                "knowledge.embedder_warm",
201                                EventKind::PhaseCompleted,
202                                PhaseCompletedPayload {
203                                    work_class: "warm".into(),
204                                    phase: "knowledge_embedder_warm".into(),
205                                    wall_us,
206                                    cpu_us,
207                                },
208                            )
209                            .await;
210                        }
211                    }
212                }
213                let _ = result;
214            });
215        }
216    }
217
218    async fn dispatch(
219        &self,
220        verb: &str,
221        params: Value,
222        registry: &VerbRegistry,
223        token: &NamespaceToken,
224    ) -> Result<Value, RuntimeError> {
225        match verb {
226            "knowledge.upsert_atoms" => {
227                KnowledgeHandlers::upsert_atoms(&self.runtime, token, params).await
228            }
229            "knowledge.upsert_domains" => {
230                KnowledgeHandlers::upsert_domains(&self.runtime, token, params).await
231            }
232            "knowledge.get" => KnowledgeHandlers::get(&self.runtime, token, params).await,
233            "knowledge.list" => KnowledgeHandlers::list(&self.runtime, token, params).await,
234            "knowledge.delete_atoms" => {
235                KnowledgeHandlers::delete_atoms(&self.runtime, token, params).await
236            }
237            "knowledge.stats" => KnowledgeHandlers::stats(&self.runtime, token, params).await,
238            "knowledge.eval_retrieval" => {
239                KnowledgeHandlers::eval_retrieval(&self.runtime, token, params, &self.ann).await
240            }
241            "knowledge.index" => {
242                KnowledgeHandlers::index(&self.runtime, token, params, &self.ann, None).await
243            }
244            "knowledge.fold" => KnowledgeHandlers::fold(&self.runtime, token, params).await,
245            "knowledge.search" => {
246                KnowledgeHandlers::search(&self.runtime, token, params, &self.ann).await
247            }
248            "knowledge.suggest" => {
249                KnowledgeHandlers::suggest(&self.runtime, token, params, &self.ann).await
250            }
251            "knowledge.compose" => {
252                // Public registry dispatch pre-applies an explicit namespace,
253                // while PackRuntime can also be called directly by embedders.
254                // A direct caller must supply a token already authorized for
255                // the requested namespace; handlers may not mint a stronger
256                // capability from an untrusted business parameter.
257                let effective_token = match params.get("namespace") {
258                    None => token.clone(),
259                    Some(Value::String(ns_str)) => {
260                        let ns = Namespace::parse(ns_str).map_err(|e| {
261                            RuntimeError::InvalidInput(format!("invalid namespace {ns_str:?}: {e}"))
262                        })?;
263                        if &ns != token.namespace() {
264                            return Err(RuntimeError::InvalidInput(
265                                "knowledge.compose namespace does not match authorized token namespace"
266                                    .to_string(),
267                            ));
268                        }
269                        // Equality proves this is capability narrowing, not
270                        // elevation. Replace any broader visible set so every
271                        // compose leg observes exactly the requested arm.
272                        token.with_namespace(ns)
273                    }
274                    Some(_) => {
275                        return Err(RuntimeError::InvalidInput(
276                            "invalid namespace: expected a string".to_string(),
277                        ));
278                    }
279                };
280                let type_weights = self
281                    .resolve_compose_type_weights(registry, &effective_token)
282                    .await;
283                KnowledgeHandlers::compose(
284                    &self.runtime,
285                    &effective_token,
286                    params,
287                    &self.ann,
288                    type_weights,
289                )
290                .await
291            }
292            "knowledge.edit" => {
293                KnowledgeHandlers::edit(&self.runtime, token, params, &self.ann).await
294            }
295            "knowledge.import" => {
296                KnowledgeHandlers::import(&self.runtime, token, params, &self.ann).await
297            }
298            "knowledge.challenge" => {
299                KnowledgeHandlers::challenge(&self.runtime, token, params).await
300            }
301            "knowledge.adjudicate" => {
302                KnowledgeHandlers::adjudicate(&self.runtime, token, params).await
303            }
304            "knowledge.learn" => self.handle_learn(token, params).await,
305            "knowledge.cite" => self.handle_cite(token, params).await,
306            "knowledge.topic" => self.handle_topic(token, params).await,
307            "knowledge.feedback" => self.handle_feedback(token, params, registry).await,
308            _ => Err(RuntimeError::InvalidInput(format!(
309                "knowledge pack does not handle verb {verb:?}"
310            ))),
311        }
312    }
313}
314
315#[async_trait]
316impl PackByIdResolver for KnowledgePack {
317    /// Resolve a live knowledge record by UUID.
318    ///
319    /// Queries `knowledge_domains` first (canonical record), then
320    /// `knowledge_atoms`. The domain mirror atom shares the domain's UUID
321    /// (crud.rs:279/300) so domains must win over the mirror.
322    async fn resolve_by_id(&self, id: Uuid) -> Result<Option<Resolved>, RuntimeError> {
323        let sql = self.runtime.sql();
324        let id_str = id.to_string();
325
326        let mut reader = sql
327            .reader()
328            .await
329            .map_err(|e| RuntimeError::Internal(format!("knowledge resolve_by_id reader: {e}")))?;
330
331        // 1. Check knowledge_domains first (canonical over the mirror atom).
332        let domain_row = reader
333            .query_row(SqlStatement {
334                sql: "SELECT id, namespace, slug, name, description, tags, members, \
335                      created_at, updated_at, deleted_at \
336                      FROM knowledge_domains WHERE id = ?1 AND deleted_at IS NULL LIMIT 1"
337                    .into(),
338                params: vec![SqlValue::Text(id_str.clone())],
339                label: Some("knowledge.resolve_by_id.domain".into()),
340            })
341            .await
342            .map_err(|e| {
343                RuntimeError::Internal(format!("knowledge resolve_by_id domain query: {e}"))
344            })?;
345
346        if let Some(row) = domain_row {
347            if let Some(domain) = domain_from_row(&row) {
348                return Ok(Some(Resolved::PackRecord {
349                    pack: "knowledge".into(),
350                    kind: "domain".into(),
351                    data: domain_to_json(&domain),
352                }));
353            }
354        }
355
356        // 2. Check knowledge_atoms.
357        let atom_row = reader
358            .query_row(SqlStatement {
359                sql: "SELECT id, namespace, slug, name, content, tags, properties, \
360                      status, finalized, source_uri, source_type, created_at, updated_at, deleted_at \
361                      FROM knowledge_atoms WHERE id = ?1 AND deleted_at IS NULL LIMIT 1"
362                    .into(),
363                params: vec![SqlValue::Text(id_str)],
364                label: Some("knowledge.resolve_by_id.atom".into()),
365            })
366            .await
367            .map_err(|e| {
368                RuntimeError::Internal(format!("knowledge resolve_by_id atom query: {e}"))
369            })?;
370
371        if let Some(row) = atom_row {
372            if let Some(atom) = atom_from_row(&row) {
373                return Ok(Some(Resolved::PackRecord {
374                    pack: "knowledge".into(),
375                    kind: "atom".into(),
376                    data: atom_to_json(&atom),
377                }));
378            }
379        }
380
381        Ok(None)
382    }
383
384    /// Resolve a knowledge record including already-soft-deleted records.
385    ///
386    /// Used by the hard-delete path to locate tombstoned records.
387    async fn resolve_by_id_including_deleted(
388        &self,
389        id: Uuid,
390    ) -> Result<Option<Resolved>, RuntimeError> {
391        let sql = self.runtime.sql();
392        let id_str = id.to_string();
393
394        let mut reader = sql.reader().await.map_err(|e| {
395            RuntimeError::Internal(format!(
396                "knowledge resolve_by_id_including_deleted reader: {e}"
397            ))
398        })?;
399
400        let domain_row = reader
401            .query_row(SqlStatement {
402                sql: "SELECT id, namespace, slug, name, description, tags, members, \
403                      created_at, updated_at, deleted_at \
404                      FROM knowledge_domains WHERE id = ?1 LIMIT 1"
405                    .into(),
406                params: vec![SqlValue::Text(id_str.clone())],
407                label: Some("knowledge.resolve_by_id_incl_deleted.domain".into()),
408            })
409            .await
410            .map_err(|e| {
411                RuntimeError::Internal(format!(
412                    "knowledge resolve_by_id_including_deleted domain query: {e}"
413                ))
414            })?;
415
416        if let Some(row) = domain_row {
417            if let Some(domain) = domain_from_row(&row) {
418                return Ok(Some(Resolved::PackRecord {
419                    pack: "knowledge".into(),
420                    kind: "domain".into(),
421                    data: domain_to_json(&domain),
422                }));
423            }
424        }
425
426        let atom_row = reader
427            .query_row(SqlStatement {
428                sql: "SELECT id, namespace, slug, name, content, tags, properties, \
429                      status, finalized, source_uri, source_type, created_at, updated_at, deleted_at \
430                      FROM knowledge_atoms WHERE id = ?1 LIMIT 1"
431                    .into(),
432                params: vec![SqlValue::Text(id_str)],
433                label: Some("knowledge.resolve_by_id_incl_deleted.atom".into()),
434            })
435            .await
436            .map_err(|e| {
437                RuntimeError::Internal(format!(
438                    "knowledge resolve_by_id_including_deleted atom query: {e}"
439                ))
440            })?;
441
442        if let Some(row) = atom_row {
443            if let Some(atom) = atom_from_row(&row) {
444                return Ok(Some(Resolved::PackRecord {
445                    pack: "knowledge".into(),
446                    kind: "atom".into(),
447                    data: atom_to_json(&atom),
448                }));
449            }
450        }
451
452        Ok(None)
453    }
454
455    /// Delete a knowledge domain or atom by UUID.
456    ///
457    /// Soft-delete by default (`hard=false`): sets `deleted_at = now()`.
458    /// For domains, also tombstones the mirror atom in `knowledge_atoms`.
459    /// Hard-delete (`hard=true`): permanently removes rows from the table(s).
460    async fn delete_by_id(&self, id: Uuid, hard: bool) -> Result<serde_json::Value, RuntimeError> {
461        let sql = self.runtime.sql();
462        let id_str = id.to_string();
463
464        // First determine the kind (including deleted rows so hard-delete can find tombstones).
465        let kind = match self.resolve_by_id_including_deleted(id).await? {
466            Some(Resolved::PackRecord { kind, .. }) => kind,
467            _ => {
468                return Err(RuntimeError::NotFound(format!(
469                    "knowledge record not found: {id}"
470                )));
471            }
472        };
473
474        let now_us = std::time::SystemTime::now()
475            .duration_since(std::time::UNIX_EPOCH)
476            .unwrap_or_default()
477            .as_micros() as i64;
478
479        let mut writer = sql
480            .writer()
481            .await
482            .map_err(|e| RuntimeError::Internal(format!("knowledge delete_by_id writer: {e}")))?;
483
484        match kind.as_str() {
485            "domain" => {
486                if hard {
487                    // Hard-delete: sections → mirror atom → domain (all in one transaction).
488                    // knowledge_sections has a FK to knowledge_atoms(id) without ON DELETE
489                    // CASCADE, so sections must go before the atom row.
490                    writer
491                        .execute_batch(vec![
492                            SqlStatement {
493                                sql: "DELETE FROM knowledge_sections WHERE atom_id = ?1".into(),
494                                params: vec![SqlValue::Text(id_str.clone())],
495                                label: Some(
496                                    "knowledge.delete_by_id.domain_mirror_sections.hard".into(),
497                                ),
498                            },
499                            SqlStatement {
500                                sql: "DELETE FROM knowledge_atoms WHERE id = ?1".into(),
501                                params: vec![SqlValue::Text(id_str.clone())],
502                                label: Some("knowledge.delete_by_id.domain_mirror.hard".into()),
503                            },
504                            SqlStatement {
505                                sql: "DELETE FROM knowledge_domains WHERE id = ?1".into(),
506                                params: vec![SqlValue::Text(id_str.clone())],
507                                label: Some("knowledge.delete_by_id.domain.hard".into()),
508                            },
509                        ])
510                        .await
511                        .map_err(|e| {
512                            RuntimeError::Internal(format!(
513                                "knowledge delete_by_id domain hard: {e}"
514                            ))
515                        })?;
516                } else {
517                    writer
518                        .execute(SqlStatement {
519                            sql: "UPDATE knowledge_domains SET deleted_at = ?1 \
520                                  WHERE id = ?2 AND deleted_at IS NULL"
521                                .into(),
522                            params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
523                            label: Some("knowledge.delete_by_id.domain.soft".into()),
524                        })
525                        .await
526                        .map_err(|e| {
527                            RuntimeError::Internal(format!(
528                                "knowledge delete_by_id domain soft: {e}"
529                            ))
530                        })?;
531                    // Tombstone the mirror atom so FTS no longer surfaces it.
532                    writer
533                        .execute(SqlStatement {
534                            sql: "UPDATE knowledge_atoms SET deleted_at = ?1 \
535                                  WHERE id = ?2 AND deleted_at IS NULL"
536                                .into(),
537                            params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
538                            label: Some("knowledge.delete_by_id.domain_mirror.soft".into()),
539                        })
540                        .await
541                        .map_err(|e| {
542                            RuntimeError::Internal(format!(
543                                "knowledge delete_by_id domain mirror soft: {e}"
544                            ))
545                        })?;
546                }
547            }
548            "atom" => {
549                if hard {
550                    // Hard-delete: sections first (FK constraint), then the atom row.
551                    writer
552                        .execute_batch(vec![
553                            SqlStatement {
554                                sql: "DELETE FROM knowledge_sections WHERE atom_id = ?1".into(),
555                                params: vec![SqlValue::Text(id_str.clone())],
556                                label: Some("knowledge.delete_by_id.atom_sections.hard".into()),
557                            },
558                            SqlStatement {
559                                sql: "DELETE FROM knowledge_atoms WHERE id = ?1".into(),
560                                params: vec![SqlValue::Text(id_str.clone())],
561                                label: Some("knowledge.delete_by_id.atom.hard".into()),
562                            },
563                        ])
564                        .await
565                        .map_err(|e| {
566                            RuntimeError::Internal(format!("knowledge delete_by_id atom hard: {e}"))
567                        })?;
568                } else {
569                    writer
570                        .execute(SqlStatement {
571                            sql: "UPDATE knowledge_atoms SET deleted_at = ?1 \
572                                  WHERE id = ?2 AND deleted_at IS NULL"
573                                .into(),
574                            params: vec![SqlValue::Integer(now_us), SqlValue::Text(id_str.clone())],
575                            label: Some("knowledge.delete_by_id.atom.soft".into()),
576                        })
577                        .await
578                        .map_err(|e| {
579                            RuntimeError::Internal(format!("knowledge delete_by_id atom soft: {e}"))
580                        })?;
581                }
582            }
583            other => {
584                return Err(RuntimeError::Internal(format!(
585                    "knowledge delete_by_id: unexpected kind {other:?}"
586                )));
587            }
588        }
589
590        Ok(serde_json::json!({
591            "deleted": true,
592            "id": id_str,
593            "kind": kind,
594            "hard": hard,
595        }))
596    }
597}
598
599#[cfg(test)]
600mod tests {
601    use khive_runtime::pack::PackRuntime;
602    use khive_runtime::{KhiveRuntime, Namespace, RuntimeConfig};
603    use lattice_embed::EmbeddingModel;
604
605    use super::KnowledgePack;
606
607    // ADR-103 Amendment 1 Part 2: knowledge_embedder_warm phase-span events.
608    //
609    // `KhiveRuntime::memory()` builds on `RuntimeConfig::no_embeddings()`
610    // (runtime.rs), so `default_embedder_name()` is empty and the
611    // configured-embedder branch in `KnowledgePack::warm()` never runs. This
612    // pins that gating: the unconditional `vamana::warm_known_snapshots` call
613    // above the branch must never itself emit a phase event, and the
614    // configured-only branch must not fire when unconfigured.
615    #[tokio::test]
616    async fn knowledge_warm_emits_no_phase_events_when_no_embedder_configured() {
617        let rt = KhiveRuntime::memory().expect("in-memory runtime");
618        let token = rt.authorize(Namespace::local()).expect("authorize local");
619        let event_store = rt.events(&token).expect("event store must be available");
620
621        let pack = KnowledgePack::new(rt.clone());
622        pack.warm().await;
623
624        let page = event_store
625            .query_events(
626                khive_storage::EventFilter::default(),
627                khive_storage::PageRequest {
628                    limit: 10,
629                    offset: 0,
630                },
631            )
632            .await
633            .expect("query events");
634
635        assert!(
636            page.items.is_empty(),
637            "no embedder configured -> KnowledgePack::warm() must emit zero phase events \
638             (configured-only branch must not fire, and warm_known_snapshots must not \
639             independently emit): {:?}",
640            page.items
641        );
642    }
643
644    #[tokio::test]
645    async fn read_only_knowledge_cache_miss_does_not_start_ann_writer_lifecycle() {
646        let dir = tempfile::tempdir().expect("tempdir");
647        let config = RuntimeConfig {
648            db_path: Some(dir.path().join("read-only-knowledge-ann.db")),
649            embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
650            additional_embedding_models: vec![],
651            ..RuntimeConfig::no_embeddings()
652        };
653        drop(KhiveRuntime::new(config.clone()).expect("migrate snapshot source"));
654
655        #[cfg(unix)]
656        {
657            use std::os::unix::fs::PermissionsExt;
658            let db_path = config.db_path.as_ref().expect("db path");
659            for suffix in ["-wal", "-shm"] {
660                let mut name = db_path.file_name().expect("db file name").to_os_string();
661                name.push(suffix);
662                let sidecar = db_path.parent().expect("db parent dir").join(name);
663                if sidecar.exists() {
664                    let mut permissions = std::fs::metadata(&sidecar)
665                        .expect("sidecar metadata")
666                        .permissions();
667                    permissions.set_mode(0o444);
668                    std::fs::set_permissions(&sidecar, permissions).expect("freeze sidecar");
669                }
670            }
671        }
672
673        let read_only = KhiveRuntime::new_readonly(config).expect("open snapshot read-only");
674        let token = read_only
675            .authorize(Namespace::local())
676            .expect("authorize local");
677        let pack = KnowledgePack::new(read_only.clone());
678        let key = crate::knowledge::vamana::AnnKey::new(
679            token.namespace().as_str(),
680            read_only.default_embedder_name(),
681        );
682        let before = read_only.backend().pool().writer_acquisition_snapshot();
683
684        crate::knowledge::vamana::ensure_ann_background(&read_only, &token, &pack.ann);
685
686        assert!(
687            !crate::knowledge::vamana::is_warming_not_loaded(&pack.ann, &key),
688            "a read-only search cache miss must not claim or spawn an ANN warm slot"
689        );
690        assert_eq!(
691            read_only.backend().pool().writer_acquisition_snapshot(),
692            before,
693            "read-only ANN admission must not acquire a writer"
694        );
695    }
696}