Skip to main content

khive_runtime/
runtime.rs

1//! KhiveRuntime — composable handle to all storage capabilities.
2//!
3//! `RuntimeConfig`, `BackendId`, `NamespaceToken`, and embedding model helpers
4//! live in `super::config` and are re-exported from here.
5
6use std::collections::{HashMap, HashSet};
7use std::future::Future;
8use std::path::PathBuf;
9use std::sync::{Arc, Mutex, OnceLock, RwLock, Weak};
10
11use khive_db::{ConnectionPool, StorageBackend};
12#[cfg(test)]
13use khive_gate::AllowAllGate;
14use khive_gate::GateRequest;
15use khive_storage::types::{SqlStatement, SqlValue};
16use khive_storage::{
17    AttachmentStore, EntityStore, Event, EventStore, GraphStore, NoteStore, SqlAccess, VectorStore,
18};
19use khive_types::{EdgeEndpointRule, EventKind, Namespace, SubstrateKind};
20use lattice_embed::{EmbeddingModel, EmbeddingService};
21
22#[cfg(test)]
23use crate::config::vec_model_key;
24use crate::config::{
25    build_embedder_registry, parse_embedding_model_alias, register_configured_embedding_models,
26    sanitize_key,
27};
28use crate::error::{RuntimeError, RuntimeResult};
29use crate::note_search_ann::NoteSearchAnnProvider;
30use crate::pack::KindHook;
31
32mod close;
33#[path = "runtime/config_access.rs"]
34mod config_access;
35pub use close::{
36    RuntimeCloseError, RuntimeCloseHostTasks, RuntimeCloseOwner, RuntimeClosePhase,
37    RuntimeCloseRoot, RuntimeCloseRootKind,
38};
39mod embedder_init;
40mod engine_binding;
41mod events_disk_policy;
42mod serving_policy;
43
44#[cfg(all(test, target_os = "macos"))]
45const IN_PROCESS_TEST_NOFILE_LIMIT: libc::rlim_t = 4096;
46#[cfg(all(test, target_os = "macos"))]
47static IN_PROCESS_TEST_NOFILE_INIT: std::sync::Once = std::sync::Once::new();
48
49#[cfg(all(test, target_os = "macos"))]
50fn ensure_in_process_test_nofile_limit() {
51    IN_PROCESS_TEST_NOFILE_INIT.call_once(|| {
52        let mut limits = libc::rlimit {
53            rlim_cur: 0,
54            rlim_max: 0,
55        };
56        // SAFETY: `limits` is writable, and only this test binary's soft
57        // limit may change; the inherited hard limit is preserved.
58        assert_eq!(unsafe { libc::getrlimit(libc::RLIMIT_NOFILE, &mut limits) }, 0);
59        assert!(
60            limits.rlim_max >= IN_PROCESS_TEST_NOFILE_LIMIT,
61            "in-process SQLite tests require a hard open-file limit of at least {IN_PROCESS_TEST_NOFILE_LIMIT}"
62        );
63        if limits.rlim_cur < IN_PROCESS_TEST_NOFILE_LIMIT {
64            limits.rlim_cur = IN_PROCESS_TEST_NOFILE_LIMIT;
65            // SAFETY: the new soft limit does not exceed the observed hard
66            // limit, which is left unchanged.
67            assert_eq!(unsafe { libc::setrlimit(libc::RLIMIT_NOFILE, &limits) }, 0);
68        }
69    });
70}
71
72tokio::task_local! {
73    static REQUEST_EMBEDDER_EXCLUSIONS: Arc<HashSet<String>>;
74}
75
76/// Run one request with daemon-only embedding models excluded from registry access.
77pub fn scope_request_embedder_exclusions<F>(
78    excluded: Vec<String>,
79    future: F,
80) -> impl Future<Output = F::Output>
81where
82    F: Future,
83{
84    REQUEST_EMBEDDER_EXCLUSIONS.scope(Arc::new(excluded.into_iter().collect()), future)
85}
86
87/// Carry the current request's embedder exclusions into a spawned task.
88pub fn inherit_request_embedder_scope<F>(future: F) -> impl Future<Output = F::Output>
89where
90    F: Future,
91{
92    let exclusions = REQUEST_EMBEDDER_EXCLUSIONS.try_with(Arc::clone).ok();
93    async move {
94        match exclusions {
95            Some(exclusions) => REQUEST_EMBEDDER_EXCLUSIONS.scope(exclusions, future).await,
96            None => future.await,
97        }
98    }
99}
100
101fn request_excludes_embedder(name: &str) -> bool {
102    let canonical = parse_embedding_model_alias(name)
103        .map(|model| model.to_string())
104        .unwrap_or_else(|| name.to_string());
105    REQUEST_EMBEDDER_EXCLUSIONS
106        .try_with(|excluded| excluded.contains(&canonical))
107        .unwrap_or(false)
108}
109
110/// Callback type for pack-installed entity-type validators.
111///
112/// Receives `(kind, entity_type)` and returns the normalised type string,
113/// or `RuntimeError::InvalidInput` if the type is not registered for that kind.
114/// When `entity_type` is `None`, the implementation must return `Ok(None)`.
115pub type EntityTypeValidatorFn =
116    Arc<dyn Fn(&str, Option<&str>) -> Result<Option<String>, RuntimeError> + Send + Sync>;
117
118/// Pack-aggregated entity-kind update hooks: `(entity kind, hook)` for every
119/// kind whose owning pack both declares it and registers a `KindHook`.
120///
121/// Named rather than written inline because the runtime stores it behind an
122/// `Arc<RwLock<..>>` and passes it across the transport boundary, so the bare
123/// form appears three times and reads as noise at each one.
124pub type EntityKindHooks = Vec<(String, Arc<dyn KindHook>)>;
125
126#[derive(Clone, Debug)]
127pub(crate) struct EntityOwnerHookLookup {
128    hooks: Arc<RwLock<EntityKindHooks>>,
129}
130
131fn find_entity_owner_hook(
132    hooks: &RwLock<EntityKindHooks>,
133    kind: &str,
134) -> Option<Arc<dyn KindHook>> {
135    hooks.read().ok().and_then(|guard| {
136        guard
137            .iter()
138            .find(|(candidate, _)| candidate == kind)
139            .map(|(_, hook)| hook.clone())
140    })
141}
142
143impl EntityOwnerHookLookup {
144    pub(crate) fn has_hook(&self, kind: &str) -> bool {
145        find_entity_owner_hook(&self.hooks, kind).is_some()
146    }
147}
148
149/// Callback type for a pack-installed note-mutation hook.
150///
151/// Invoked by `update_note` (when the note's text/embedding actually
152/// changed) and `delete_note` (soft or hard) with `(note_kind, note_id)`,
153/// after the mutation has been durably applied. Returns a boxed future so
154/// the hook can await async cache-invalidation work (e.g.
155/// `khive-pack-memory`'s ANN warm-cache generation bump) without
156/// `khive-runtime` depending on any pack crate: dependencies point the
157/// other way, so the runtime exposes an extension point and the pack
158/// installs into it, same shape as `EntityTypeValidatorFn`, just async.
159pub type NoteMutationHookFn = Arc<
160    dyn Fn(String, uuid::Uuid) -> std::pin::Pin<Box<dyn std::future::Future<Output = ()> + Send>>
161        + Send
162        + Sync,
163>;
164
165/// Callback type for a pack-installed note-write validator.
166///
167/// The pack that owns a note kind carrying derivable identity installs one so
168/// that the identity is a function of the authorization token rather than of
169/// caller input, on every write path including direct callers that bypass the
170/// handler layer — same rationale as [`EntityTypeValidatorFn`], which exists
171/// for exactly that reason on the entity side.
172///
173/// Kinds the installing pack does not own must be returned unchanged: the slot
174/// is single-occupancy (like `note_mutation_hook`), so a validator that
175/// rewrote foreign kinds would silently govern every other pack's notes.
176pub type NoteWriteValidatorFn = Arc<
177    dyn Fn(&str, &str, Option<serde_json::Value>) -> Result<Option<serde_json::Value>, RuntimeError>
178        + Send
179        + Sync,
180>;
181
182/// Immutable identity for a non-text vector store owned by a pack consumer.
183///
184/// This does not register an [`crate::EmbedderProvider`]. It gives a pack that
185/// performs its own governed inference a narrow path to a namespace-scoped
186/// Khive vector table while keeping model-key and dimension validation at the
187/// runtime boundary.
188#[derive(Clone, Debug, Eq, PartialEq)]
189pub struct NamedVectorIdentity {
190    model_key: String,
191    model_name: String,
192    dimensions: usize,
193}
194
195struct CachedNamedVectorStores {
196    identity: NamedVectorIdentity,
197    by_namespace: HashMap<String, Arc<dyn VectorStore>>,
198}
199
200fn check_cached_named_vector_identity(
201    cached: &NamedVectorIdentity,
202    requested: &NamedVectorIdentity,
203) -> RuntimeResult<()> {
204    if cached.dimensions() != requested.dimensions() {
205        return Err(RuntimeError::InvalidInput(format!(
206            "named vector model_key {:?} is already bound to {} dimensions, expected {}",
207            requested.model_key(),
208            cached.dimensions(),
209            requested.dimensions()
210        )));
211    }
212    if cached.model_name() != requested.model_name() {
213        return Err(RuntimeError::InvalidInput(format!(
214            "named vector model_key {:?} is already bound to a different active model identity",
215            requested.model_key()
216        )));
217    }
218    Ok(())
219}
220
221impl NamedVectorIdentity {
222    const MAX_MODEL_KEY_BYTES: usize = 128;
223    const MAX_MODEL_NAME_BYTES: usize = 512;
224
225    /// Validate and construct a named vector identity.
226    pub fn new(
227        model_key: impl Into<String>,
228        model_name: impl Into<String>,
229        dimensions: usize,
230    ) -> RuntimeResult<Self> {
231        let model_key = model_key.into();
232        let model_name = model_name.into();
233        if model_key.is_empty()
234            || model_key.len() > Self::MAX_MODEL_KEY_BYTES
235            || !model_key
236                .chars()
237                .all(|c| c.is_ascii_alphanumeric() || c == '_')
238        {
239            return Err(RuntimeError::InvalidInput(format!(
240                "named vector model_key must be 1..={} bytes of ASCII alphanumeric/underscore",
241                Self::MAX_MODEL_KEY_BYTES
242            )));
243        }
244        if model_name.trim().is_empty()
245            || model_name.trim() != model_name
246            || model_name.len() > Self::MAX_MODEL_NAME_BYTES
247        {
248            return Err(RuntimeError::InvalidInput(format!(
249                "named vector model_name must be 1..={} bytes with no surrounding whitespace",
250                Self::MAX_MODEL_NAME_BYTES
251            )));
252        }
253        if !(1..=8192).contains(&dimensions) {
254            return Err(RuntimeError::InvalidInput(format!(
255                "named vector dimensions must be in 1..=8192, got {dimensions}"
256            )));
257        }
258        Ok(Self {
259            model_key,
260            model_name,
261            dimensions,
262        })
263    }
264
265    pub fn model_key(&self) -> &str {
266        &self.model_key
267    }
268
269    pub fn model_name(&self) -> &str {
270        &self.model_name
271    }
272
273    pub fn dimensions(&self) -> usize {
274        self.dimensions
275    }
276}
277
278pub use crate::config::{
279    assert_captured_db_anchor_consistent, assert_db_anchor_consistent, expand_tilde,
280    parse_pack_list, resolve_db_anchor, resolve_project_actor_id,
281    resolve_project_requires_attributed_actor, runtime_config_from_khive_config, BackendId,
282    BackendIdError, NamespaceToken, RuntimeConfig,
283};
284
285// ---- KhiveRuntime ----
286
287/// Composable runtime handle used by the MCP server.
288///
289/// Wraps a `StorageBackend` and provides namespace-scoped accessor methods
290/// Snapshot of the main runtime's embedder wiring (registry handle, default
291/// name, and the config model fields the default-resolution path reads).
292/// Carried by secondary-pack runtimes; consumed by [`KhiveRuntime::core`].
293#[derive(Clone)]
294struct CoreEmbedderState {
295    registry: Arc<std::sync::RwLock<crate::embedder_registry::EmbedderRegistry>>,
296    default_embedder_name: Arc<str>,
297    engines: Option<Vec<crate::engine_config::EngineConfig>>,
298    embedding_model: Option<EmbeddingModel>,
299    additional_embedding_models: Vec<EmbeddingModel>,
300}
301
302#[derive(Clone)]
303struct NoteKindEntry {
304    name: String,
305    embedding_policy: crate::NoteEmbeddingPolicy,
306    registered: bool,
307}
308
309/// An already-open serving backend eligible for operator diagnostics.
310/// Aliases of the same canonical database file share one entry.
311#[derive(Clone)]
312pub struct OpenedDiagnosticBackend {
313    pub backend_names: Vec<String>,
314    pub canonical_path: Option<PathBuf>,
315    pub pool: Arc<ConnectionPool>,
316}
317
318struct LateOpenedDiagnosticBackend {
319    backend_names: Vec<&'static str>,
320    pool: Weak<ConnectionPool>,
321}
322
323fn same_diagnostic_database(a: &OpenedDiagnosticBackend, b: &OpenedDiagnosticBackend) -> bool {
324    match (a.pool.canonical_path(), b.pool.canonical_path()) {
325        (Some(a), Some(b)) => a == b,
326        (None, None) => Arc::ptr_eq(&a.pool, &b.pool),
327        _ => false,
328    }
329}
330
331/// for each storage capability, plus a lazily-loaded embedder.
332#[derive(Clone)]
333pub struct KhiveRuntime {
334    pub(crate) visibility_receipts: Arc<crate::visibility_receipts::ReceiptCapability>,
335    pub(crate) visibility_cutover: Arc<crate::visibility_receipts::ReceiptCutover>,
336    core_visibility_cutover: Arc<crate::visibility_receipts::ReceiptCutover>,
337    backend: Arc<StorageBackend>,
338    /// Successful named-vector bindings and their namespace-scoped stores.
339    /// Shared by runtime clones so repeated reads do not enter the writer or
340    /// rescan the vector table after the first verified binding.
341    named_vector_stores: Arc<RwLock<HashMap<String, CachedNamedVectorStores>>>,
342    /// The main backend's cache, used when a secondary runtime creates a
343    /// `core()` handle. It must never reuse a secondary backend's store.
344    core_named_vector_stores: Option<Arc<RwLock<HashMap<String, CachedNamedVectorStores>>>>,
345    /// When `Some`, holds the main backend so that `core()` can return a
346    /// main-bound runtime handle without constructing a new connection.
347    /// `None` when this runtime is already bound to the main backend.
348    core_backend: Option<Arc<StorageBackend>>,
349    /// Observations belonging to this runtime construction and its clones.
350    config_lock_ledger: Arc<crate::config_ledger::ConfigLockLedger>,
351    /// A core ledger belongs to this runtime's exact backend-Arc binding.
352    /// Clones and old core handles retain the binding they already hold.
353    core_config_lock_ledger: Option<(
354        Arc<StorageBackend>,
355        Arc<crate::config_ledger::ConfigLockLedger>,
356    )>,
357    /// Admission identity shared by every view of this host's runtime.
358    background_domain: crate::resource_admission::BackgroundDomainHandle,
359    /// External lifetime ownership; absent only on background job views.
360    background_root: Option<crate::resource_admission::BackgroundRoot>,
361    config: RuntimeConfig,
362    pub(crate) code_map_registry: Arc<crate::CodeMapRegistry>,
363    outbound_email_policy: std::sync::Arc<crate::OutboundEmailPolicy>,
364    /// All SQLite backends declared by the host process, including those
365    /// assigned to other packs. The code pack fences these from ingest.
366    declared_backend_db_paths: Arc<[PathBuf]>,
367    /// Pools opened during serving host composition, grouped by canonical
368    /// database file.
369    diagnostic_backends: Arc<[OpenedDiagnosticBackend]>,
370    /// Pools opened later by this serving runtime and its pack handles.
371    /// Weak references keep diagnostics from extending their lifetime.
372    late_diagnostic_backends: Arc<Mutex<Vec<LateOpenedDiagnosticBackend>>>,
373    /// ADR-118 exact-leg policy, sampled once at runtime construction.
374    /// Request-time memory/knowledge serving must never re-read the process
375    /// environment because tests and embedded runtimes share one process.
376    ann_fresh_tail_enabled: bool,
377    /// Pack-extensible embedder registry.
378    ///
379    /// Shared across clones via `Arc<RwLock<_>>` so that
380    /// [`register_embedder`](Self::register_embedder) after clone is visible
381    /// to all handles. Built-in lattice models are pre-registered during
382    /// construction; packs may add more via [`PackRuntime::register_embedders`].
383    embedder_registry: Arc<std::sync::RwLock<crate::embedder_registry::EmbedderRegistry>>,
384    default_embedder_name: Arc<str>,
385    /// The MAIN runtime's embedder wiring, carried by secondary-backend
386    /// runtimes so that `core()`-routed writes embed with the main runtime's
387    /// models even when this pack's own registry is empty (`no_embed`).
388    /// `None` on the main runtime, and on secondaries wired before the boot
389    /// path calls [`with_core_embedders_from`](Self::with_core_embedders_from)
390    /// — `core()` then falls back to this runtime's own embedder state.
391    core_embedders: Option<CoreEmbedderState>,
392    /// Pack-extensible edge endpoint rules. Shared across clones
393    /// via `Arc<RwLock<_>>`; installed once by the transport after the
394    /// `VerbRegistry` is built. Empty until installed
395    edge_rules: Arc<RwLock<Vec<EdgeEndpointRule>>>,
396    /// Pack-aggregated valid entity kinds and note-kind policy entries.
397    ///
398    /// Installed by the transport layer after building the `VerbRegistry`.
399    /// When non-empty, `create_entity`, `create_note_inner`, and `import_kg`
400    /// reject kinds not in these sets. When empty (no packs loaded, e.g.
401    /// bare runtime in unit tests), kind validation is skipped — the pack
402    /// handler layer is the primary enforcement point.
403    valid_entity_kinds: Arc<RwLock<Vec<String>>>,
404    valid_note_kinds: Arc<RwLock<Vec<NoteKindEntry>>>,
405    /// Pack-installed entity-type validator.
406    ///
407    /// When `Some`, `create_many` calls this function to validate and normalise
408    /// each `(kind, entity_type)` pair before writing. When `None` (bare runtime
409    /// without packs), entity-type validation is skipped — the pack handler layer
410    /// is the primary enforcement point, same as for `valid_entity_kinds`.
411    entity_type_validator: Arc<RwLock<Option<EntityTypeValidatorFn>>>,
412    /// Pack-installed note-mutation hook.
413    ///
414    /// When `Some`, `update_note` (on text change) and `delete_note` (soft
415    /// or hard) call this after the mutation is durably applied, so a pack
416    /// that caches derived state keyed by note content (e.g. `khive-pack-memory`'s
417    /// warm ANN index) can invalidate/advance its own generation counter even
418    /// when the mutation arrived through a different pack's verb (e.g. KG's
419    /// `update`/`delete` on a `kind="memory"` note) that has no dependency on
420    /// the reacting pack. `None` when no pack installs one (bare runtime, or
421    /// no pack cares about note-mutation notifications) — the call becomes a
422    /// no-op check of an `Option`.
423    note_mutation_hook: Arc<RwLock<Option<NoteMutationHookFn>>>,
424    /// Backend-matched, pack-installed ANN source for note search. Absent on a
425    /// bare runtime or when no memory graph provider serves this backend.
426    note_search_ann_provider: Arc<RwLock<Option<Arc<dyn NoteSearchAnnProvider>>>>,
427    /// Pack-installed note-write validator.
428    ///
429    /// When `Some`, every runtime note-materialisation site that accepts
430    /// caller-supplied `properties` routes them through this function before
431    /// the `Note` is built, so a pack-owned identity property is derived from
432    /// the authorization token instead of trusted from caller input. `None`
433    /// on a bare runtime (no packs) — the properties pass through unchanged.
434    note_write_validator: Arc<RwLock<Option<NoteWriteValidatorFn>>>,
435    /// Pack-installed entity-kind update-validation hooks (issue #2943).
436    ///
437    /// Every `(entity kind, hook)` pair for which an owning pack declares
438    /// the entity kind and registers a `KindHook`, aggregated once by
439    /// `VerbRegistry::entity_kind_hooks` and installed by the transport
440    /// after the registry is built — same timing and rationale as
441    /// `entity_type_validator`: `khive-runtime` does not hold a
442    /// `VerbRegistry`, so this is the extension point that lets
443    /// `prepare_guarded_entity_update` reach a pack's `KindHook` on the
444    /// generic entity `update` path, the counterpart to
445    /// `prepare_note_update_hook` on the note side. Empty until installed
446    /// (bare runtime, or no pack registers an entity-kind hook), which
447    /// leaves the dispatch a no-op.
448    entity_kind_hooks: Arc<RwLock<EntityKindHooks>>,
449    /// Pack-owned note kinds — every note kind declared by a pack other than
450    /// the generic-CRUD pack, installed by the transport from the registry
451    /// (see `VerbRegistry::pack_owned_note_kinds`). Records of these kinds are
452    /// maintained by their owning pack's own verbs, so `update`'s `properties`
453    /// patch is refused on them at the runtime layer and their owned identity
454    /// properties survive a `merge` unchanged. Empty until installed (bare
455    /// runtime), which leaves both rules inert.
456    pack_owned_note_kinds: Arc<RwLock<Vec<String>>>,
457    /// The immutable runtime-owned store/hydration pair (ADR-160 D3).
458    ///
459    /// Boot resolves one store and constructs exactly one shared hydrator,
460    /// then installs that same `Arc` on every runtime handle. The one-shot
461    /// slot rejects replacement so pack runtimes cannot silently split the
462    /// aggregate byte budget after startup. Bare runtimes leave it unset.
463    blob_hydrator: Arc<OnceLock<Arc<crate::blob::BlobHydrator>>>,
464    /// Pack-registered custom fusion executors (ADR-012), keyed by the name
465    /// carried in `FusionStrategy::Custom { name, .. }`.
466    ///
467    /// Unlike `entity_type_validator`/`note_mutation_hook` (single-occupancy —
468    /// one pack owns the slot), multiple packs each register their own named
469    /// strategy under this shared map, so it is keyed rather than a bare
470    /// `Option`. Empty until a pack calls
471    /// [`register_fusion_strategy`](Self::register_fusion_strategy); an
472    /// unregistered `Custom` name at dispatch time is
473    /// `RuntimeError::UnknownFusionStrategy`, never a silent fallback.
474    fusion_executors: Arc<RwLock<HashMap<String, Arc<dyn crate::fusion::FusionExecutor>>>>,
475}
476
477impl KhiveRuntime {
478    /// Observe a resolved config value once for this runtime construction.
479    ///
480    /// The lazy value runs outside the ledger mutex. A name already recorded
481    /// does not evaluate its lazy value. Concurrent first observers of one name
482    /// may each evaluate their closure, so value closures must have no side effects.
483    /// Only the first to insert the name after evaluation queues an observation.
484    pub fn record_config_locked<F>(&self, key: &'static str, value: F)
485    where
486        F: FnOnce() -> String,
487    {
488        self.config_lock_ledger.record_config_locked(key, value);
489    }
490
491    #[cfg(test)]
492    pub(crate) fn install_config_lock_test_hook(
493        &self,
494        point: crate::config_ledger::TestRecordPoint,
495        hook: Arc<dyn Fn() + Send + Sync>,
496    ) {
497        self.config_lock_ledger.install_test_hook(point, hook);
498    }
499
500    /// Take this runtime's pending observations for its bound audit registry.
501    pub(crate) fn drain_config_locked(&self) -> Vec<(&'static str, String)> {
502        self.config_lock_ledger.drain_config_locked()
503    }
504
505    /// Return the code maps accepted from the configuration used to construct this runtime.
506    pub fn code_map_registry(&self) -> &crate::CodeMapRegistry {
507        self.code_map_registry.as_ref()
508    }
509
510    /// Create a new runtime with the given config.
511    ///
512    /// The config's `db_path` is used to open or create the SQLite backend.
513    /// This direct constructor is intended for fresh/current single-backend
514    /// databases and tests. Production and multi-backend hosts must use the
515    /// async khive-mcp/kkernel builders so secondary inventory and any
516    /// application-assisted V21 cutover complete before serving. The
517    /// [`from_backend`](Self::from_backend) seam is likewise only for an
518    /// already-prepared backend.
519    pub fn new(mut config: RuntimeConfig) -> RuntimeResult<Self> {
520        let wal_ceiling = config.resolve_wal_ceiling_policy(false)?;
521        let disk_guard = config.resolve_disk_guard_policy(false)?;
522        // Refuse a missing lock directory before the constructor below creates
523        // the database's parent directory.
524        let volume_lock_dir = if config.db_path.is_some() {
525            let configured = config.volume_lock_dir.clone();
526            Some(khive_db::require_volume_lock_dir(configured)?)
527        } else {
528            None
529        };
530        Self::new_with_file_backend(config, true, |path| {
531            StorageBackend::sqlite_with_max_readers_and_policies(
532                path,
533                None,
534                wal_ceiling,
535                disk_guard.expect("file-backed disk policy"),
536                volume_lock_dir.expect("file-backed volume-lock directory"),
537            )
538        })
539    }
540
541    /// Construct a fixture runtime with a small concurrent reader pool.
542    #[cfg(any(test, feature = "test-internals"))]
543    pub fn new_for_test(mut config: RuntimeConfig) -> RuntimeResult<Self> {
544        let wal_ceiling = config.resolve_wal_ceiling_policy(false)?;
545        let disk_guard = config.resolve_disk_guard_policy(false)?;
546        Self::new_with_file_backend(config, true, |path| {
547            StorageBackend::sqlite_for_test_with_policies(
548                path,
549                wal_ceiling,
550                disk_guard.expect("file-backed disk policy"),
551            )
552        })
553    }
554
555    pub(crate) fn new_with_file_backend(
556        mut config: RuntimeConfig,
557        create_parent: bool,
558        open_file: impl FnOnce(&std::path::Path) -> Result<StorageBackend, khive_db::SqliteError>,
559    ) -> RuntimeResult<Self> {
560        let background_limits = Self::validated_background_limits(&config)?;
561        config.prepare_engines()?;
562        #[cfg(unix)]
563        crate::events_split::socket_path::validate_configured_events_socket(&config)?;
564        #[cfg(all(test, target_os = "macos"))]
565        ensure_in_process_test_nofile_limit();
566        let backend = match &config.db_path {
567            Some(path) => {
568                if let Some(parent) = path.parent().filter(|_| create_parent) {
569                    std::fs::create_dir_all(parent).ok();
570                }
571                open_file(path)?
572            }
573            None => {
574                if config.wal_ceiling_configured_bytes != 0 || config.wal_ceiling_bytes != 0 {
575                    return Err(khive_db::SqliteError::InvalidConfig(
576                        "nonzero wal_ceiling_bytes requires a file-backed SQLite backend".into(),
577                    )
578                    .into());
579                }
580                StorageBackend::memory()?
581            }
582        };
583        // Writable backends migrate before handlers touch the DB. A detected
584        // read-only snapshot is validated at the current schema version without
585        // attempting migration DDL.
586        let schema_version = backend.prepare_core_schema()?;
587        if schema_version < khive_db::migrations::ATTACHMENT_CUTOVER_VERSION {
588            return Err(khive_db::SqliteError::InvalidData(
589                "database requires the host application-assisted V21 attachment cutover; \
590                 start through khive-mcp/kkernel boot instead of constructing KhiveRuntime \
591                 directly"
592                    .into(),
593            )
594            .into());
595        }
596        if !backend.is_read_only() {
597            register_configured_embedding_models(&backend, &config)?;
598        }
599        let background = Self::start_background_root(background_limits)?;
600        Ok(Self::assemble_from_backend(
601            Arc::new(backend),
602            config,
603            false,
604            background,
605        ))
606    }
607
608    /// Open a runtime for read-only inspection (no model registration, no DB creation).
609    ///
610    /// File-backed databases are opened with SQLite read-only/query-only flags
611    /// and must already be at this build's current schema version. No migrations
612    /// or configured-model registration writes are attempted. A `None` path
613    /// retains the historical ephemeral in-memory behavior for tests.
614    pub fn new_readonly(mut config: RuntimeConfig) -> RuntimeResult<Self> {
615        let wal_ceiling = config.resolve_wal_ceiling_policy(true)?;
616        Self::new_readonly_with_file_backend(config, |path| {
617            StorageBackend::sqlite_read_only_with_max_readers_and_wal_ceiling(
618                path,
619                None,
620                wal_ceiling,
621            )
622        })
623    }
624
625    /// Open an existing live database for read-only planning.
626    ///
627    /// Committed WAL frames remain visible while a writer holds the database
628    /// open. Schema compatibility is checked without migrations, configured-model
629    /// registration or application-assisted cutover writes. A file-backed path
630    /// is required.
631    pub fn new_readonly_live(mut config: RuntimeConfig) -> RuntimeResult<Self> {
632        if config.db_path.is_none() {
633            return Err(khive_db::SqliteError::InvalidConfig(
634                "live read-only planning requires a file-backed database path".into(),
635            )
636            .into());
637        }
638        let wal_ceiling = config.resolve_wal_ceiling_policy(true)?;
639        Self::new_readonly_with_file_backend(config, |path| {
640            StorageBackend::sqlite_read_only_live_with_max_readers_and_wal_ceiling(
641                path,
642                None,
643                wal_ceiling,
644            )
645        })
646    }
647
648    /// Construct a read-only fixture runtime with a small reader pool.
649    #[cfg(any(test, feature = "test-internals"))]
650    pub fn new_readonly_for_test(mut config: RuntimeConfig) -> RuntimeResult<Self> {
651        let wal_ceiling = config.resolve_wal_ceiling_policy(true)?;
652        Self::new_readonly_with_file_backend(config, |path| {
653            StorageBackend::sqlite_read_only_with_max_readers_and_wal_ceiling(
654                path,
655                Some(2),
656                wal_ceiling,
657            )
658        })
659    }
660
661    fn new_readonly_with_file_backend(
662        mut config: RuntimeConfig,
663        open_file: impl FnOnce(&std::path::Path) -> Result<StorageBackend, khive_db::SqliteError>,
664    ) -> RuntimeResult<Self> {
665        let background_limits = Self::validated_background_limits(&config)?;
666        config.prepare_engines()?;
667        #[cfg(unix)]
668        crate::events_split::socket_path::validate_configured_events_socket(&config)?;
669        #[cfg(all(test, target_os = "macos"))]
670        ensure_in_process_test_nofile_limit();
671        let backend = match &config.db_path {
672            Some(path) => open_file(path)?,
673            None => {
674                if config.wal_ceiling_configured_bytes != 0 || config.wal_ceiling_bytes != 0 {
675                    return Err(khive_db::SqliteError::InvalidConfig(
676                        "nonzero wal_ceiling_bytes requires a file-backed SQLite backend".into(),
677                    )
678                    .into());
679                }
680                StorageBackend::memory()?
681            }
682        };
683        backend.prepare_core_schema()?;
684        let background = Self::start_background_root(background_limits)?;
685        Ok(Self::assemble_from_backend(
686            Arc::new(backend),
687            config,
688            false,
689            background,
690        ))
691    }
692
693    /// Construct a runtime from an already-opened backend.
694    ///
695    /// This is a low-level, infallible assembly seam for already-prepared
696    /// multi-backend deployments. It does not migrate or require completion of
697    /// the V21 attachment cutover, and it does not read the backend: receipt
698    /// admission is checked by the first receipt operation and cached once it
699    /// succeeds. Production hosts must first run the async kkernel/khive-mcp
700    /// coordinator and must not expose a server over a pending or incomplete
701    /// backend. Prefer [`Self::from_prepared_backend`] when constructing one
702    /// fallible host runtime.
703    ///
704    /// All storage access is through the provided `backend`; the config's
705    /// ordered embedding peers are prepared before assembly.
706    ///
707    /// # Panics
708    ///
709    /// Panics if the engine configuration is invalid. Use
710    /// [`Self::try_from_backend`] to handle configuration errors at startup.
711    pub fn from_backend(backend: Arc<StorageBackend>, config: RuntimeConfig) -> Self {
712        Self::try_from_backend(backend, config)
713            .expect("from_backend requires a valid embedding engine configuration")
714    }
715
716    /// Assemble an already-opened backend after validating its engine config.
717    ///
718    /// This retains [`Self::from_backend`]'s warning-only storage-model
719    /// registration policy; use [`Self::from_prepared_backend`] when those
720    /// registration failures must also abort startup.
721    pub fn try_from_backend(
722        backend: Arc<StorageBackend>,
723        config: RuntimeConfig,
724    ) -> RuntimeResult<Self> {
725        Self::try_from_backend_with_background(backend, config, None)
726    }
727
728    /// Assemble a backend in the main runtime's existing admission domain.
729    ///
730    /// Panics on invalid configuration, matching [`Self::from_backend`].
731    pub fn from_backend_in_domain(
732        backend: Arc<StorageBackend>,
733        config: RuntimeConfig,
734        background: crate::resource_admission::BackgroundRoot,
735    ) -> Self {
736        Self::try_from_backend_in_domain(backend, config, background)
737            .expect("from_backend_in_domain requires matching valid background limits")
738    }
739
740    /// Validate limits and reuse a host domain without creating another worker.
741    pub fn try_from_backend_in_domain(
742        backend: Arc<StorageBackend>,
743        config: RuntimeConfig,
744        background: crate::resource_admission::BackgroundRoot,
745    ) -> RuntimeResult<Self> {
746        Self::try_from_backend_with_background(backend, config, Some(background))
747    }
748
749    fn try_from_backend_with_background(
750        backend: Arc<StorageBackend>,
751        mut config: RuntimeConfig,
752        background: Option<crate::resource_admission::BackgroundRoot>,
753    ) -> RuntimeResult<Self> {
754        let limits = Self::validated_background_limits(&config)?;
755        if background
756            .as_ref()
757            .is_some_and(|root| root.limits() != limits)
758        {
759            return Err(RuntimeError::InvalidInput(
760                "runtime background limits must match the host admission domain".into(),
761            ));
762        }
763        config.prepare_engines()?;
764        if !backend.is_read_only() {
765            if let Err(err) = register_configured_embedding_models(&backend, &config) {
766                tracing::warn!(error = %err, "failed to register configured embedding models");
767            }
768        }
769        let background = match background {
770            Some(root) => root,
771            None => Self::start_background_root(limits)?,
772        };
773        Ok(Self::assemble_from_backend(
774            backend, config, false, background,
775        ))
776    }
777
778    /// Construct a single-backend runtime after a host boot coordinator has
779    /// completed schema preparation and any application-assisted cutover.
780    ///
781    /// Unlike [`Self::from_backend`], configured embedding-model registration
782    /// is fallible here, preserving [`Self::new`]'s single-backend startup
783    /// semantics. This method never runs migrations itself.
784    pub fn from_prepared_backend(
785        backend: Arc<StorageBackend>,
786        mut config: RuntimeConfig,
787    ) -> RuntimeResult<Self> {
788        let background_limits = Self::validated_background_limits(&config)?;
789        config.prepare_engines()?;
790        if backend.attachment_cutover_status()?
791            != khive_db::migrations::AttachmentCutoverStatus::Complete
792        {
793            return Err(khive_db::SqliteError::InvalidData(
794                "from_prepared_backend requires a complete V21 attachment cutover".into(),
795            )
796            .into());
797        }
798        backend.validate_memory_visibility_cutover()?;
799        if !backend.is_read_only() {
800            register_configured_embedding_models(&backend, &config)?;
801        }
802        let background = Self::start_background_root(background_limits)?;
803        Ok(Self::assemble_from_backend(
804            backend, config, true, background,
805        ))
806    }
807
808    /// Validate raw host admission limits before preparing engines or opening storage.
809    /// This pure check starts no worker and performs no filesystem or boot work.
810    pub fn validated_background_limits(
811        config: &RuntimeConfig,
812    ) -> RuntimeResult<crate::resource_admission::WorkClassLimits> {
813        crate::resource_admission::WorkClassLimits::validate(
814            config.warm_concurrency,
815            config.maintenance_concurrency,
816        )
817        .map_err(|error| RuntimeError::InvalidInput(error.to_string()))
818    }
819
820    fn start_background_root(
821        limits: crate::resource_admission::WorkClassLimits,
822    ) -> RuntimeResult<crate::resource_admission::BackgroundRoot> {
823        crate::resource_admission::BackgroundRoot::start(
824            limits,
825            crate::resource_admission::CleanupPolicy::new(crate::daemon::drain_timeout()),
826        )
827        .map_err(|error| {
828            RuntimeError::Internal(format!("background runtime startup failed: {error}"))
829        })
830    }
831
832    fn assemble_from_backend(
833        backend: Arc<StorageBackend>,
834        config: RuntimeConfig,
835        cutover_validated: bool,
836        background: crate::resource_admission::BackgroundRoot,
837    ) -> Self {
838        if config.backend_id.as_str() == BackendId::MAIN {
839            backend.pool().main_pool_generation();
840        }
841        let ann_fresh_tail_enabled = crate::config::ann_fresh_tail_enabled_from_env();
842        let (registry, default_embedder_name) = build_embedder_registry(&config);
843        let runtime_db_path = backend.pool().canonical_path().map(PathBuf::from);
844        let code_map_registry = Arc::new(crate::CodeMapRegistry::load_for_runtime(
845            &config,
846            runtime_db_path,
847        ));
848        let visibility_receipts = Arc::new(
849            crate::visibility_receipts::ReceiptCapability::from_config(&config),
850        );
851        let visibility_cutover = Arc::new(crate::visibility_receipts::ReceiptCutover::new(
852            backend.clone(),
853            cutover_validated,
854        ));
855        Self {
856            visibility_receipts,
857            core_visibility_cutover: visibility_cutover.clone(),
858            visibility_cutover,
859            backend,
860            named_vector_stores: Arc::new(RwLock::new(HashMap::new())),
861            core_named_vector_stores: None,
862            core_backend: None,
863            config_lock_ledger: Arc::new(crate::config_ledger::ConfigLockLedger::default()),
864            core_config_lock_ledger: None,
865            background_domain: background.handle(),
866            background_root: Some(background),
867            config,
868            code_map_registry,
869            outbound_email_policy: Default::default(),
870            declared_backend_db_paths: Vec::new().into(),
871            diagnostic_backends: Vec::new().into(),
872            late_diagnostic_backends: Arc::new(Mutex::new(Vec::new())),
873            ann_fresh_tail_enabled,
874            embedder_registry: Arc::new(std::sync::RwLock::new(registry)),
875            default_embedder_name,
876            core_embedders: None,
877            edge_rules: Arc::new(RwLock::new(Vec::new())),
878            valid_entity_kinds: Arc::new(RwLock::new(Vec::new())),
879            valid_note_kinds: Arc::new(RwLock::new(Vec::new())),
880            entity_type_validator: Arc::new(RwLock::new(None)),
881            note_mutation_hook: Arc::new(RwLock::new(None)),
882            note_search_ann_provider: Arc::new(RwLock::new(None)),
883            note_write_validator: Arc::new(RwLock::new(None)),
884            entity_kind_hooks: Arc::new(RwLock::new(Vec::new())),
885            pack_owned_note_kinds: Arc::new(RwLock::new(Vec::new())),
886            blob_hydrator: Arc::new(OnceLock::new()),
887            fusion_executors: Arc::new(RwLock::new(HashMap::new())),
888        }
889    }
890
891    /// Wire this runtime as a secondary-backend runtime pointing at `core`.
892    ///
893    /// After this call, `self.core()` returns a handle to `core` rather than
894    /// cloning `self`. The caller (the boot path, not pack code) is responsible
895    /// for passing the correct main backend.
896    /// Binding a different core clears its named-vector cache and prior main
897    /// embedder wiring. Call [`Self::with_core_embedders_from`] with the new main
898    /// runtime after rebinding when core-routed writes require its embedders.
899    ///
900    /// Panics in debug builds if `self.config.backend_id == BackendId::MAIN`,
901    /// because the main runtime does not need a core pointer.
902    pub fn with_core_backend(mut self, core: Arc<StorageBackend>) -> Self {
903        debug_assert_ne!(
904            self.config.backend_id.as_str(),
905            BackendId::MAIN,
906            "with_core_backend must not be called on the main runtime"
907        );
908        core.pool().main_pool_generation();
909        if !self
910            .core_config_lock_ledger
911            .as_ref()
912            .is_some_and(|(bound, _)| Arc::ptr_eq(bound, &core))
913        {
914            self.core_config_lock_ledger = Some((
915                core.clone(),
916                Arc::new(crate::config_ledger::ConfigLockLedger::default()),
917            ));
918        }
919        if self.visibility_cutover.is_bound_to(&core) {
920            self.core_visibility_cutover = self.visibility_cutover.clone();
921        } else if !self.core_visibility_cutover.is_bound_to(&core) {
922            self.core_visibility_cutover = Arc::new(
923                crate::visibility_receipts::ReceiptCutover::new(core.clone(), false),
924            );
925        }
926        if self
927            .core_backend
928            .as_ref()
929            .is_some_and(|previous| !Arc::ptr_eq(previous, &core))
930        {
931            self.core_named_vector_stores = None;
932            self.core_embedders = None;
933        }
934        if self.core_named_vector_stores.is_none() {
935            self.core_named_vector_stores = Some(Arc::new(RwLock::new(HashMap::new())));
936        }
937        self.core_backend = Some(core);
938        self
939    }
940
941    /// Carry the main runtime's embedder wiring for `core()`-routed writes.
942    ///
943    /// Boot-path companion to [`with_core_backend`](Self::with_core_backend).
944    /// Without it, `core()` shares this pack runtime's own embedder registry —
945    /// which under `[packs.<name>] no_embed = true` is empty, so core-routed
946    /// concept writes would silently skip embedding on the shared graph.
947    pub fn with_core_embedders_from(mut self, main: &KhiveRuntime) -> Self {
948        debug_assert!(
949            main.core_backend.is_none(),
950            "with_core_embedders_from takes the MAIN runtime"
951        );
952        self.core_embedders = Some(CoreEmbedderState {
953            registry: main.embedder_registry.clone(),
954            default_embedder_name: main.default_embedder_name.clone(),
955            engines: main.config.engines.clone(),
956            embedding_model: main.config.embedding_model,
957            additional_embedding_models: main.config.additional_embedding_models.clone(),
958        });
959        self.core_named_vector_stores = Some(main.named_vector_stores.clone());
960        if Arc::ptr_eq(&self.backend, &main.backend) {
961            self.named_vector_stores = main.named_vector_stores.clone();
962        }
963        self
964    }
965
966    /// Share the main runtime's validated code-map registrations.
967    pub fn with_code_map_registry_from(mut self, main: &KhiveRuntime) -> Self {
968        debug_assert!(
969            main.core_backend.is_none(),
970            "with_code_map_registry_from takes the MAIN runtime"
971        );
972        self.code_map_registry = main.code_map_registry.clone();
973        self
974    }
975
976    /// Return a runtime handle bound to the main (shared-graph) backend.
977    ///
978    /// When `self` is already the main runtime (`core_backend` is `None`),
979    /// this returns a clone of `self` — no new backend reference is acquired.
980    ///
981    /// When `self` is a secondary-backend runtime (`core_backend` is `Some`),
982    /// this returns a new `KhiveRuntime` backed by the main
983    /// `Arc<StorageBackend>` and sharing all registry state (`embedder_registry`,
984    /// `edge_rules`, `valid_entity_kinds`, `valid_note_kinds`,
985    /// `entity_type_validator`, `note_mutation_hook`, `entity_kind_hooks`) with `self`.
986    /// No database I/O occurs; no embedding models are reloaded.
987    ///
988    /// Use `core()` for notes and entities that must reside in the shared graph
989    /// so that `memory.recall`, cross-pack search, and `annotates` edges work.
990    /// Use `self` (or `self.sql()`) for pack-auxiliary bulk tables.
991    ///
992    /// Handlers that call `core()` more than once per request or loop should bind
993    /// `let core = self.core();` once and reuse it, since each call clones
994    /// `RuntimeConfig` (a heap-allocated struct containing `Vec<String>` fields).
995    pub fn core(&self) -> KhiveRuntime {
996        match &self.core_backend {
997            // A main-assigned pack runtime has no core pointer, but may still
998            // carry main's embedder wiring: with `no_embed` its OWN registry
999            // is empty, and core-routed concept writes must embed regardless
1000            // of which backend the pack was assigned to.
1001            None => match &self.core_embedders {
1002                None => self.clone(),
1003                Some(core_embedders) => {
1004                    let mut core = self.clone();
1005                    core.config.engines = core_embedders.engines.clone();
1006                    core.config.embedding_model = core_embedders.embedding_model;
1007                    core.config.additional_embedding_models =
1008                        core_embedders.additional_embedding_models.clone();
1009                    core.embedder_registry = core_embedders.registry.clone();
1010                    core.default_embedder_name = core_embedders.default_embedder_name.clone();
1011                    core.core_embedders = None;
1012                    core
1013                }
1014            },
1015            Some(main_arc) => {
1016                let mut core_config = self.config.clone();
1017                core_config.backend_id = BackendId::main();
1018                // Core-routed writes embed with the MAIN runtime's wiring when
1019                // the boot path supplied it (see `with_core_embedders_from`);
1020                // both the registry handle and the config model fields must
1021                // come from main, since default-model resolution reads
1022                // `config.embedding_model` (`resolve_embedding_model`).
1023                let (embedder_registry, default_embedder_name) = match &self.core_embedders {
1024                    Some(core_embedders) => {
1025                        core_config.engines = core_embedders.engines.clone();
1026                        core_config.embedding_model = core_embedders.embedding_model;
1027                        core_config.additional_embedding_models =
1028                            core_embedders.additional_embedding_models.clone();
1029                        (
1030                            core_embedders.registry.clone(),
1031                            core_embedders.default_embedder_name.clone(),
1032                        )
1033                    }
1034                    None => (
1035                        self.embedder_registry.clone(),
1036                        self.default_embedder_name.clone(),
1037                    ),
1038                };
1039                KhiveRuntime {
1040                    visibility_receipts: self.visibility_receipts.clone(),
1041                    visibility_cutover: self.core_visibility_cutover.clone(),
1042                    core_visibility_cutover: self.core_visibility_cutover.clone(),
1043                    backend: main_arc.clone(),
1044                    named_vector_stores: self
1045                        .core_named_vector_stores
1046                        .clone()
1047                        .unwrap_or_else(|| Arc::new(RwLock::new(HashMap::new()))),
1048                    core_named_vector_stores: None,
1049                    core_backend: None,
1050                    config_lock_ledger: self
1051                        .core_config_lock_ledger
1052                        .as_ref()
1053                        .filter(|(bound, _)| Arc::ptr_eq(bound, main_arc))
1054                        .map(|(_, ledger)| ledger.clone())
1055                        .expect("core backend binding must retain its config-lock ledger"),
1056                    core_config_lock_ledger: None,
1057                    background_domain: self.background_domain.clone(),
1058                    background_root: self.background_root.clone(),
1059                    config: core_config,
1060                    code_map_registry: self.code_map_registry.clone(),
1061                    outbound_email_policy: self.outbound_email_policy.clone(),
1062                    declared_backend_db_paths: self.declared_backend_db_paths.clone(),
1063                    diagnostic_backends: self.diagnostic_backends.clone(),
1064                    late_diagnostic_backends: self.late_diagnostic_backends.clone(),
1065                    ann_fresh_tail_enabled: self.ann_fresh_tail_enabled,
1066                    embedder_registry,
1067                    default_embedder_name,
1068                    core_embedders: None,
1069                    edge_rules: self.edge_rules.clone(),
1070                    valid_entity_kinds: self.valid_entity_kinds.clone(),
1071                    valid_note_kinds: self.valid_note_kinds.clone(),
1072                    entity_type_validator: self.entity_type_validator.clone(),
1073                    note_mutation_hook: self.note_mutation_hook.clone(),
1074                    note_search_ann_provider: self.note_search_ann_provider.clone(),
1075                    note_write_validator: self.note_write_validator.clone(),
1076                    entity_kind_hooks: self.entity_kind_hooks.clone(),
1077                    pack_owned_note_kinds: self.pack_owned_note_kinds.clone(),
1078                    blob_hydrator: self.blob_hydrator.clone(),
1079                    fusion_executors: self.fusion_executors.clone(),
1080                }
1081            }
1082        }
1083    }
1084
1085    /// Create an in-memory runtime (for tests and ephemeral use).
1086    pub fn memory() -> RuntimeResult<Self> {
1087        Self::new(RuntimeConfig {
1088            db_path: None,
1089            packs: vec!["kg".to_string()],
1090            brain_profile: None,
1091            actor_id: None,
1092            ..RuntimeConfig::no_embeddings()
1093        })
1094    }
1095
1096    /// Return the [`BackendId`] for this runtime's backend.
1097    ///
1098    /// Used by `SubstrateCoordinator` in `kkernel`
1099    /// to identify which backend owns a given node, and to detect cross-backend merges.
1100    pub fn backend_id(&self) -> &BackendId {
1101        &self.config.backend_id
1102    }
1103
1104    /// Whether two runtime handles share one opened physical store. The host
1105    /// deduplicates same-path aliases; separately opened hard-link aliases
1106    /// compare the identity pinned when SQLite opened each file.
1107    pub fn shares_backend_storage_with(&self, other: &Self) -> bool {
1108        if Arc::ptr_eq(&self.backend, &other.backend) {
1109            return true;
1110        }
1111        #[cfg(any(unix, windows))]
1112        {
1113            matches!(
1114                (
1115                    self.backend.pool().opened_file_identity_record(),
1116                    other.backend.pool().opened_file_identity_record()
1117                ),
1118                (Some(left), Some(right)) if left == right
1119            )
1120        }
1121        #[cfg(not(any(unix, windows)))]
1122        {
1123            false
1124        }
1125    }
1126
1127    /// Install only pools the host actually opened. A bare runtime defaults
1128    /// to its already-open main pool without opening or creating another file.
1129    pub fn with_diagnostic_backends(mut self, backends: Arc<[OpenedDiagnosticBackend]>) -> Self {
1130        self.diagnostic_backends = backends;
1131        self
1132    }
1133
1134    /// Share late-opened diagnostics with pack runtimes from the same serving
1135    /// host. Independent runtimes retain independent observers.
1136    pub fn with_diagnostic_observer_from(mut self, main: &KhiveRuntime) -> Self {
1137        self.late_diagnostic_backends = Arc::clone(&main.late_diagnostic_backends);
1138        self
1139    }
1140
1141    fn register_late_diagnostic_pool(
1142        &self,
1143        backend_name: &'static str,
1144        pool: &Arc<ConnectionPool>,
1145    ) {
1146        let mut backends = self
1147            .late_diagnostic_backends
1148            .lock()
1149            .unwrap_or_else(std::sync::PoisonError::into_inner);
1150        backends.retain(|entry| entry.pool.strong_count() > 0);
1151        if let Some(existing) = backends.iter_mut().find(|entry| {
1152            entry
1153                .pool
1154                .upgrade()
1155                .is_some_and(|live| Arc::ptr_eq(&live, pool))
1156        }) {
1157            if !existing.backend_names.contains(&backend_name) {
1158                existing.backend_names.push(backend_name);
1159            }
1160            return;
1161        }
1162        backends.push(LateOpenedDiagnosticBackend {
1163            backend_names: vec![backend_name],
1164            pool: Arc::downgrade(pool),
1165        });
1166    }
1167
1168    fn live_late_diagnostic_backends(&self) -> Vec<OpenedDiagnosticBackend> {
1169        let mut backends = self
1170            .late_diagnostic_backends
1171            .lock()
1172            .unwrap_or_else(std::sync::PoisonError::into_inner);
1173        let mut live = Vec::new();
1174        backends.retain(|entry| {
1175            let Some(pool) = entry.pool.upgrade() else {
1176                return false;
1177            };
1178            live.push(OpenedDiagnosticBackend {
1179                backend_names: entry
1180                    .backend_names
1181                    .iter()
1182                    .map(|name| name.to_string())
1183                    .collect(),
1184                canonical_path: pool.canonical_path().map(PathBuf::from),
1185                pool,
1186            });
1187            true
1188        });
1189        live
1190    }
1191
1192    pub fn diagnostic_backends(&self) -> Arc<[OpenedDiagnosticBackend]> {
1193        let mut opened: Vec<OpenedDiagnosticBackend> = if self.diagnostic_backends.is_empty() {
1194            let main = self.core().backend.pool_arc();
1195            vec![OpenedDiagnosticBackend {
1196                backend_names: vec![BackendId::MAIN.to_string()],
1197                canonical_path: main.canonical_path().map(PathBuf::from),
1198                pool: main,
1199            }]
1200        } else {
1201            self.diagnostic_backends.iter().cloned().collect()
1202        };
1203        for late in self.live_late_diagnostic_backends() {
1204            if let Some(existing) = opened
1205                .iter_mut()
1206                .find(|existing| same_diagnostic_database(existing, &late))
1207            {
1208                for name in late.backend_names {
1209                    if !existing.backend_names.contains(&name) {
1210                        existing.backend_names.push(name);
1211                    }
1212                }
1213            } else {
1214                opened.push(late);
1215            }
1216        }
1217        opened.into()
1218    }
1219
1220    /// Whether this runtime selects the vector arm for a hybrid search —
1221    /// true exactly when a default embedding model is configured. Single
1222    /// source of truth for the policy every fan-out and single-backend
1223    /// dispatch path uses to report `arm_participation`/`vector_selected`.
1224    pub fn vector_arm_selected(&self) -> bool {
1225        !self.default_embedder_name().is_empty()
1226    }
1227
1228    /// Return a reference to the underlying storage backend.
1229    ///
1230    /// This is an embedder/infrastructure surface (connection pools, schema
1231    /// plans, diagnostics). Stores obtained from it are NOT wrapped by the
1232    /// message-evidence policy that [`Self::notes`] enforces: an embedder
1233    /// holding the backend already holds root-equivalent access to the
1234    /// database file, so the policy boundary sits at the typed accessors
1235    /// pack code uses, not here. Pack code must not take note stores from
1236    /// this surface.
1237    pub fn backend(&self) -> &StorageBackend {
1238        &self.backend
1239    }
1240
1241    /// Whether this runtime's bound backend is explicitly or filesystem-mode
1242    /// detected read-only.
1243    pub fn is_read_only(&self) -> bool {
1244        self.backend.is_read_only()
1245    }
1246
1247    /// Return the directory containing the backend's database file, or `None`
1248    /// for an in-memory backend.
1249    pub fn backend_data_dir(&self) -> Option<std::path::PathBuf> {
1250        self.backend.data_dir()
1251    }
1252
1253    /// Root directory for this database's ANN segment tree (`<db-file>.ann/`
1254    /// beside the file), or `None` for an in-memory backend. Scoped to the
1255    /// database file itself so two databases sharing a parent directory can
1256    /// never adopt each other's segments.
1257    pub fn backend_ann_root(&self) -> Option<std::path::PathBuf> {
1258        self.backend.ann_root()
1259    }
1260
1261    /// Writer-contention, graph-edge integrity, and WAL/checkpoint diagnostics
1262    /// (ADR-091/ADR-135 operator surface): pooled writer and audit-failure
1263    /// counters, build identity, duplicate edge-ID and list-ledger counts,
1264    /// checkpoint counters, a PASSIVE checkpoint probe, WAL file size, and
1265    /// explicitly qualified WAL-pin census. Not write-free: the
1266    /// PASSIVE probe may backfill WAL frames into the database (normal
1267    /// checkpoint I/O). It never changes logical state, escalates to TRUNCATE,
1268    /// creates a missing database file, or deletes sidecar evidence — see
1269    /// `khive_db::diagnostics` for the narrowings that make those claims hold.
1270    ///
1271    /// Always targets the *main* backend via [`Self::core`], regardless of
1272    /// which backend this runtime handle is bound to, so a report never
1273    /// describes a database this handle is not the canonical owner of.
1274    pub async fn db_diagnostics(&self) -> RuntimeResult<khive_db::diagnostics::DbDiagnostics> {
1275        // No `VerbRegistry` handle is reachable from a bare `KhiveRuntime`
1276        // (the audit-batch seam is owned by whichever registry was built
1277        // over this runtime's `EventStore`, not by the runtime itself), so
1278        // the batch-health fields report unavailable with a reason here.
1279        // Callers that hold the registry — e.g. the `db_diagnostics` verb
1280        // handler — use `Self::db_diagnostics_with_audit_metrics` with
1281        // `VerbRegistry::audit_batch_metrics()` instead.
1282        self.db_diagnostics_with_audit_metrics(None).await
1283    }
1284
1285    /// As [`Self::db_diagnostics`], but with the caller supplying the
1286    /// ADR-133 audit-batch health counters from whichever `VerbRegistry`
1287    /// owns the seam over this runtime's `EventStore` (typically
1288    /// `VerbRegistry::audit_batch_metrics()`). `None` behaves identically to
1289    /// [`Self::db_diagnostics`].
1290    pub async fn db_diagnostics_with_audit_metrics(
1291        &self,
1292        runtime_audit_batch_metrics: Option<khive_db::diagnostics::RuntimeAuditBatchMetrics>,
1293    ) -> RuntimeResult<khive_db::diagnostics::DbDiagnostics> {
1294        let pool = self.core().backend.pool_arc();
1295        // Match housekeeping's compiled legacy-record fallback (ADR-091
1296        // Amendment 6), independent of checkpoint or local sweep overrides.
1297        let legacy_sweep_interval = khive_db::SessionSweepConfig::default().interval;
1298        let build_hash = crate::build_info::BUILD_INFO
1299            .is_stamped()
1300            .then_some(crate::build_info::BUILD_INFO.source_revision);
1301        let build = khive_db::diagnostics::BuildIdentity::from_env(
1302            crate::build_info::PACKAGE_VERSION,
1303            build_hash,
1304        );
1305
1306        let mut report = khive_db::diagnostics::collect_with_runtime_audit_metrics_interruptibly(
1307            pool,
1308            build,
1309            legacy_sweep_interval,
1310            crate::pack::audit_append_failure_count(),
1311            runtime_audit_batch_metrics,
1312        )
1313        .await
1314        .map_err(RuntimeError::from)?;
1315        report.writer_contention.audit_obligation_append_failures =
1316            Some(crate::pack::audit_obligation_append_failure_count());
1317        report
1318            .writer_contention
1319            .audit_obligation_append_failures_unavailable_reason = None;
1320        let (ann_routes, fallback_routes) = crate::note_search_ann::route_totals();
1321        report.note_search_ann_route_total = ann_routes;
1322        report.note_search_fallback_route_total = fallback_routes;
1323        Ok(report)
1324    }
1325
1326    /// Collect the same per-file report as the primary diagnostic surface for
1327    /// one opened backend. The process identity comes from main; invoking
1328    /// `ProcessIdentity::current` on a secondary would miscount main generations.
1329    /// `collect_size_composition = false` skips the `dbstat` walk (see
1330    /// `khive_db::diagnostics::collect_with_runtime_audit_metrics_for_process_interruptibly`).
1331    pub async fn db_diagnostics_for_opened_backend_with_audit_metrics(
1332        &self,
1333        backend: &OpenedDiagnosticBackend,
1334        runtime_audit_batch_metrics: Option<khive_db::diagnostics::RuntimeAuditBatchMetrics>,
1335        collect_size_composition: bool,
1336    ) -> RuntimeResult<khive_db::diagnostics::DbDiagnostics> {
1337        let main_pool = self.core().backend.pool_arc();
1338        let process = khive_db::diagnostics::ProcessIdentity::current(&main_pool);
1339        let build_hash = crate::build_info::BUILD_INFO
1340            .is_stamped()
1341            .then_some(crate::build_info::BUILD_INFO.source_revision);
1342        let build = khive_db::diagnostics::BuildIdentity::from_env(
1343            crate::build_info::PACKAGE_VERSION,
1344            build_hash,
1345        );
1346        let mut report =
1347            khive_db::diagnostics::collect_with_runtime_audit_metrics_for_process_interruptibly(
1348                Arc::clone(&backend.pool),
1349                build,
1350                process,
1351                khive_db::SessionSweepConfig::default().interval,
1352                crate::pack::audit_append_failure_count(),
1353                runtime_audit_batch_metrics,
1354                collect_size_composition,
1355            )
1356            .await
1357            .map_err(RuntimeError::from)?;
1358        report.writer_contention.audit_obligation_append_failures =
1359            Some(crate::pack::audit_obligation_append_failure_count());
1360        report
1361            .writer_contention
1362            .audit_obligation_append_failures_unavailable_reason = None;
1363        let (ann_routes, fallback_routes) = crate::note_search_ann::route_totals();
1364        report.note_search_ann_route_total = ann_routes;
1365        report.note_search_fallback_route_total = fallback_routes;
1366        Ok(report)
1367    }
1368
1369    // ---- Store accessors (token-scoped) ----
1370
1371    /// Get an EntityStore scoped to the token's namespace.
1372    pub fn entities(&self, token: &NamespaceToken) -> RuntimeResult<Arc<dyn EntityStore>> {
1373        Ok(self
1374            .backend
1375            .entities_for_namespace(token.namespace().as_str())?)
1376    }
1377
1378    /// Get a GraphStore scoped to the token's namespace.
1379    pub fn graph(&self, token: &NamespaceToken) -> RuntimeResult<Arc<dyn GraphStore>> {
1380        Ok(self
1381            .backend
1382            .graph_for_namespace(token.namespace().as_str())?)
1383    }
1384
1385    /// Get a NoteStore scoped to the token's namespace.
1386    ///
1387    /// Wrapped in `note_store_guard::PolicyEnforcingNoteStore`, which
1388    /// refuses any insert/upsert of a `kind = "message"` note carrying
1389    /// `quarantined` / `channel_kind` / `channel_slug` — the transport-owned
1390    /// evidence `comm.health` trusts at face value — and refuses patching
1391    /// those keys through the property-mutation seams on any note kind, so
1392    /// the guard cannot be sidestepped by inserting a clean message note and
1393    /// patching the evidence onto it afterward. Full-row writes also preserve
1394    /// existing channel-health coordinates while allowing heartbeat metadata to
1395    /// change. The trusted channel-ingest path does not go through this accessor; see
1396    /// `Self::raw_notes` and [`Self::try_create_note_as_trusted_ingest`].
1397    pub fn notes(&self, token: &NamespaceToken) -> RuntimeResult<Arc<dyn NoteStore>> {
1398        Ok(crate::note_store_guard::PolicyEnforcingNoteStore::wrap(
1399            self.raw_notes(token)?,
1400        ))
1401    }
1402
1403    /// Get the unwrapped, policy-free NoteStore scoped to the token's namespace.
1404    ///
1405    /// Bypasses `note_store_guard::PolicyEnforcingNoteStore`. Callers
1406    /// within this crate that have already enforced the reserved-transport-
1407    /// property policy themselves (namely `try_create_note_impl`, which
1408    /// applies it conditionally based on whether the caller presented a
1409    /// [`crate::pack::ChannelIngestCapability`]) use this to reach storage
1410    /// directly rather than run a redundant, less-informed check. Not exposed
1411    /// outside this crate — every other caller must use [`Self::notes`].
1412    pub(crate) fn raw_notes(&self, token: &NamespaceToken) -> RuntimeResult<Arc<dyn NoteStore>> {
1413        Ok(self
1414            .backend
1415            .notes_for_namespace(token.namespace().as_str())?)
1416    }
1417
1418    /// Return the role-keyed attachment substrate on the canonical main backend.
1419    ///
1420    /// Attachment rows are the process-shared BlobStore's sole SQL liveness
1421    /// authority. A runtime bound directly to a secondary pack backend must call
1422    /// [`Self::core`] first; accepting a secondary mutation here would create a
1423    /// reference that the main-database GC sweep cannot see or fence.
1424    pub fn attachments(&self) -> RuntimeResult<Arc<dyn AttachmentStore>> {
1425        if self.config.backend_id.as_str() != BackendId::MAIN {
1426            return Err(RuntimeError::InvalidInput(format!(
1427                "attachments are owned by the canonical main backend; runtime backend {:?} must route through KhiveRuntime::core()",
1428                self.config.backend_id.as_str()
1429            )));
1430        }
1431        Ok(self.backend.attachments()?)
1432    }
1433
1434    /// Get an EventStore scoped to the token's namespace.
1435    ///
1436    /// When the events-daemon split (ADR-170) is configured, the store routes
1437    /// by append class: the ADR-133 idempotent audit-batch lane — the
1438    /// measured bulk of event write volume — persists to the events database
1439    /// (forwarded over the events daemon socket in daemon deployments, or
1440    /// opened directly in embedded/one-shot contexts), while plain appends
1441    /// stay on this runtime's backend, keeping every raw-SQL consumer of the
1442    /// legacy `events` table (schedule provenance, kg projection guards,
1443    /// GraphQuery's substrate union) correct by construction. Reads merge
1444    /// both stores. Unconfigured runtimes (tests, in-memory) keep the legacy
1445    /// main-store behavior. Every returned store is decorated at this typed
1446    /// accessor boundary so append callers cannot override the namespace or
1447    /// actor resolved into the sealed authorization token.
1448    pub fn events(&self, token: &NamespaceToken) -> RuntimeResult<Arc<dyn EventStore>> {
1449        Ok(crate::event_store_guard::AttributedEventStore::wrap(
1450            self.raw_events_for_namespace(token.namespace().as_str())?,
1451            token,
1452        ))
1453    }
1454
1455    /// The event sidecar inherits the already-open MAIN pool's WAL policy.
1456    /// A secondary pack's config or pool does not govern this shared file.
1457    fn events_wal_ceiling_policy(&self) -> khive_db::WalCeilingPolicy {
1458        self.core_backend
1459            .as_ref()
1460            .unwrap_or(&self.backend)
1461            .pool()
1462            .config()
1463            .wal_ceiling
1464    }
1465
1466    /// Build the undecorated event store used only by the registry's trusted
1467    /// audit composer, which stamps from each resolved `GateRequest` before
1468    /// enqueueing. Pack/runtime call sites must use [`Self::events`] instead.
1469    pub(crate) fn raw_events_for_namespace(
1470        &self,
1471        namespace: &str,
1472    ) -> RuntimeResult<Arc<dyn EventStore>> {
1473        let legacy = self.backend.events_for_namespace(namespace)?;
1474        match &self.config.events_split {
1475            None => Ok(legacy),
1476            Some(split) => {
1477                // Read-only is decided before the transport question: a
1478                // read-only runtime must neither create nor schema-initialize
1479                // an events database, and it must not forward writes to the
1480                // events daemon either — a socket in the config describes the
1481                // deployment, not this process's authority. Serve merged
1482                // reads from a read-only open of the sidecar when it exists
1483                // (the storage-layer read-only binding refuses any write that
1484                // slips through), and the legacy store alone otherwise: no
1485                // sidecar on disk means no lane rows exist, so minting the
1486                // file just to read nothing from it would be a write in
1487                // disguise.
1488                if self.backend.is_read_only() {
1489                    if !split.db_path.exists() {
1490                        return Ok(legacy);
1491                    }
1492                    let lane_backend = crate::events_split::direct_backend_with_policies(
1493                        &split.db_path,
1494                        true,
1495                        Some(self.backend.pool().config().max_readers),
1496                        self.events_wal_ceiling_policy(),
1497                        None,
1498                        self.events_volume_lock_dir(),
1499                    )?;
1500                    self.register_late_diagnostic_pool("events", &lane_backend.pool_arc());
1501                    let lane = lane_backend.events_for_namespace(namespace)?;
1502                    return Ok(Arc::new(crate::events_split::SplitEventStore::new(
1503                        legacy, lane,
1504                    )));
1505                }
1506                let lane: Arc<dyn EventStore> = match &split.socket_path {
1507                    #[cfg(unix)]
1508                    Some(socket) => {
1509                        let client = crate::events_split::client_for(socket)?;
1510                        Arc::new(crate::events_split::ForwardingEventStore::new(
1511                            namespace, client,
1512                        ))
1513                    }
1514                    #[cfg(not(unix))]
1515                    Some(_socket) => {
1516                        return Err(RuntimeError::InvalidInput(
1517                            "events-daemon socket forwarding requires a Unix platform; \
1518                             configure the events split in direct mode here"
1519                                .to_string(),
1520                        ));
1521                    }
1522                    None => {
1523                        let lane_backend = crate::events_split::direct_backend_with_policies(
1524                            &split.db_path,
1525                            false,
1526                            Some(self.backend.pool().config().max_readers),
1527                            self.events_wal_ceiling_policy(),
1528                            Some(self.events_disk_guard_policy()?),
1529                            self.events_volume_lock_dir(),
1530                        )?;
1531                        self.register_late_diagnostic_pool("events", &lane_backend.pool_arc());
1532                        lane_backend.events_for_namespace(namespace)?
1533                    }
1534                };
1535                Ok(Arc::new(crate::events_split::SplitEventStore::new(
1536                    legacy, lane,
1537                )))
1538            }
1539        }
1540    }
1541
1542    /// Get the raw SQL access capability (for ad-hoc queries).
1543    pub fn sql(&self) -> Arc<dyn SqlAccess> {
1544        self.backend.sql()
1545    }
1546
1547    /// SQL access to the events-split sidecar database for read purposes,
1548    /// when the split (ADR-170) is configured and the sidecar exists on
1549    /// disk. `None` means every event row lives in the legacy `events`
1550    /// table, so a raw-SQL consumer needs no second lookup. Consumers that
1551    /// resolve an event by id or hex prefix against `self.sql()` must also
1552    /// consult this store on a miss: the audit-batch lane's rows live only
1553    /// in the sidecar.
1554    ///
1555    /// A writable runtime opens the sidecar through the ordinary writable
1556    /// binding: WAL supports one-writer-many-readers, and the read-only
1557    /// binding's frozen-snapshot guard refuses any sidecar with a live
1558    /// writer's `-shm` beside it — exactly the live-deployment case these
1559    /// reads exist for. A read-only runtime keeps the read-only open (it
1560    /// must neither create nor schema-initialize a sidecar), which serves
1561    /// genuinely frozen snapshots and refuses live ones, matching the
1562    /// read-only arm of `events()`. Never creates a sidecar as a side
1563    /// effect of a read.
1564    pub fn events_sidecar_sql_read_only(&self) -> RuntimeResult<Option<Arc<dyn SqlAccess>>> {
1565        match &self.config.events_split {
1566            None => Ok(None),
1567            Some(split) => {
1568                if !split.db_path.exists() {
1569                    return Ok(None);
1570                }
1571                let backend = if self.backend.is_read_only() {
1572                    crate::events_split::direct_backend_with_policies(
1573                        &split.db_path,
1574                        true,
1575                        Some(self.backend.pool().config().max_readers),
1576                        self.events_wal_ceiling_policy(),
1577                        None,
1578                        self.events_volume_lock_dir(),
1579                    )?
1580                } else {
1581                    crate::events_split::direct_backend_with_policies(
1582                        &split.db_path,
1583                        false,
1584                        Some(self.backend.pool().config().max_readers),
1585                        self.events_wal_ceiling_policy(),
1586                        Some(self.events_disk_guard_policy()?),
1587                        self.events_volume_lock_dir(),
1588                    )?
1589                };
1590                self.register_late_diagnostic_pool("events", &backend.pool_arc());
1591                Ok(Some(backend.sql()))
1592            }
1593        }
1594    }
1595
1596    /// Get a VectorStore for the configured embedding model, scoped to the token's namespace.
1597    ///
1598    /// Returns `Unconfigured("embedding_model")` if no model is set.
1599    pub fn vectors(
1600        &self,
1601        token: &NamespaceToken,
1602    ) -> RuntimeResult<Arc<dyn khive_storage::VectorStore>> {
1603        let name = self.default_embedder_name();
1604        if name.is_empty() {
1605            return Err(RuntimeError::Unconfigured("embedding_model".into()));
1606        }
1607        self.vectors_for_model(token, name)
1608    }
1609
1610    /// Get a VectorStore for a specific named embedding model, scoped to the token's namespace.
1611    ///
1612    /// Accepts both built-in lattice model names/aliases and custom provider names
1613    /// registered via [`register_embedder`](Self::register_embedder). Lattice names
1614    /// are routed through the enum-backed path; custom provider names use the
1615    /// provider's declared `dimensions()` directly so that the vector store key
1616    /// is consistent with how vectors were written during `remember`/`recall`.
1617    pub fn vectors_for_model(
1618        &self,
1619        token: &NamespaceToken,
1620        model_name: &str,
1621    ) -> RuntimeResult<Arc<dyn khive_storage::VectorStore>> {
1622        let (model_name, dims) = self.vector_model_metadata(model_name)?;
1623        Ok(self.backend.vectors_for_namespace(
1624            &sanitize_key(&model_name),
1625            &model_name,
1626            dims,
1627            token.namespace().as_str(),
1628        )?)
1629    }
1630
1631    /// Resolve the storage identity and declared dimensions together so guarded
1632    /// SQL publication agrees with VectorStore, including built-in aliases.
1633    pub(crate) fn vector_model_metadata(&self, model_name: &str) -> RuntimeResult<(String, usize)> {
1634        if request_excludes_embedder(model_name) {
1635            return Err(crate::RuntimeError::UnknownModel(model_name.to_string()));
1636        }
1637        let registry = self
1638            .embedder_registry
1639            .read()
1640            .map_err(|_| crate::RuntimeError::Internal("embedder registry lock poisoned".into()))?;
1641        if let Some(model) = parse_embedding_model_alias(model_name) {
1642            // Only proceed via the lattice path if this model is actually in the
1643            // registry; otherwise fall through to the custom-provider path.
1644            let key = model.to_string();
1645            if registry.contains(&key) {
1646                return Ok((key, model.dimensions()));
1647            }
1648        }
1649        registry
1650            .get_provider(model_name)
1651            .map(|provider| (model_name.to_owned(), provider.dimensions()))
1652            .ok_or_else(|| crate::RuntimeError::UnknownModel(model_name.to_string()))
1653    }
1654
1655    /// Get a namespace-scoped vector store for a pack-owned immutable identity.
1656    ///
1657    /// The table key is syntactically validated by [`NamedVectorIdentity`]. This
1658    /// accessor additionally verifies the table's actual sqlite-vec dimension
1659    /// declaration and every persisted `embedding_model` value before returning
1660    /// the store, so reusing one key for incompatible descriptor geometry or
1661    /// semantics fails before a caller can replace rows.
1662    pub async fn vectors_for_named_identity(
1663        &self,
1664        token: &NamespaceToken,
1665        identity: &NamedVectorIdentity,
1666    ) -> RuntimeResult<Arc<dyn VectorStore>> {
1667        let namespace = token.namespace().as_str();
1668        {
1669            let cached = self.named_vector_stores.read().map_err(|_| {
1670                RuntimeError::Internal("named vector store cache lock poisoned".into())
1671            })?;
1672            if let Some(entry) = cached.get(identity.model_key()) {
1673                check_cached_named_vector_identity(&entry.identity, identity)?;
1674                if let Some(store) = entry.by_namespace.get(namespace) {
1675                    return Ok(Arc::clone(store));
1676                }
1677            }
1678        }
1679        let store = self.backend.vectors_for_namespace(
1680            identity.model_key(),
1681            identity.model_name(),
1682            identity.dimensions(),
1683            namespace,
1684        )?;
1685
1686        let table = format!("vec_{}", identity.model_key());
1687        let mut reader = self.sql().reader().await?;
1688        let dimension_row = reader
1689            .query_row(SqlStatement {
1690                sql: "SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = ?1".to_string(),
1691                params: vec![SqlValue::Text(table.clone())],
1692                label: Some("runtime_named_vector_dimension".to_string()),
1693            })
1694            .await?
1695            .ok_or_else(|| {
1696                RuntimeError::Internal(format!(
1697                    "named vector table {table} has no sqlite_schema declaration"
1698                ))
1699            })?;
1700        let table_ddl = match dimension_row.get("sql") {
1701            Some(SqlValue::Text(value)) => value,
1702            other => {
1703                return Err(RuntimeError::Internal(format!(
1704                    "named vector table {table} returned invalid schema metadata: {other:?}"
1705                )))
1706            }
1707        };
1708        let declared_dimensions = vector_dimensions_from_ddl(table_ddl).ok_or_else(|| {
1709            RuntimeError::Internal(format!(
1710                "named vector table {table} has no parseable embedding dimension"
1711            ))
1712        })?;
1713        if declared_dimensions != identity.dimensions() {
1714            return Err(RuntimeError::InvalidInput(format!(
1715                "named vector model_key {:?} is already bound to {declared_dimensions} dimensions, expected {}",
1716                identity.model_key(),
1717                identity.dimensions()
1718            )));
1719        }
1720
1721        let stored_models = reader
1722            .query_all(SqlStatement {
1723                sql: format!(
1724                    "SELECT DISTINCT embedding_model FROM {table} ORDER BY embedding_model LIMIT 2"
1725                ),
1726                params: vec![],
1727                label: Some("runtime_named_vector_model_identity".to_string()),
1728            })
1729            .await?;
1730        for row in stored_models {
1731            let stored = match row.get("embedding_model") {
1732                Some(SqlValue::Text(value)) => value,
1733                other => {
1734                    return Err(RuntimeError::Internal(format!(
1735                        "named vector table {table} returned invalid model identity metadata: {other:?}"
1736                    )))
1737                }
1738            };
1739            if stored != identity.model_name() {
1740                return Err(RuntimeError::InvalidInput(format!(
1741                    "named vector model_key {:?} already contains model {stored:?}, cannot bind it to {:?}",
1742                    identity.model_key(),
1743                    identity.model_name()
1744                )));
1745            }
1746        }
1747
1748        self.backend
1749            .register_embedding_model(
1750                identity.model_key(),
1751                identity.model_name(),
1752                identity.model_key(),
1753                identity.dimensions() as u32,
1754            )
1755            .map_err(|error| {
1756                if matches!(
1757                    &error,
1758                    khive_db::SqliteError::Rusqlite(rusqlite::Error::SqliteFailure(code, _))
1759                    | khive_db::SqliteError::Write { source: rusqlite::Error::SqliteFailure(code, _), .. }
1760                        if code.code == rusqlite::ErrorCode::ConstraintViolation
1761                ) {
1762                    RuntimeError::InvalidInput(format!(
1763                        "named vector model_key {:?} is already bound to a different active model identity",
1764                        identity.model_key()
1765                    ))
1766                } else {
1767                    RuntimeError::from(error)
1768                }
1769            })?;
1770
1771        let mut cached = self
1772            .named_vector_stores
1773            .write()
1774            .map_err(|_| RuntimeError::Internal("named vector store cache lock poisoned".into()))?;
1775        let entry = cached
1776            .entry(identity.model_key().to_owned())
1777            .or_insert_with(|| CachedNamedVectorStores {
1778                identity: identity.clone(),
1779                by_namespace: HashMap::new(),
1780            });
1781        check_cached_named_vector_identity(&entry.identity, identity)?;
1782        entry
1783            .by_namespace
1784            .insert(namespace.to_owned(), Arc::clone(&store));
1785        Ok(store)
1786    }
1787
1788    /// Output dimensions for a named embedding model, resolved from the
1789    /// embedder registry alone — no storage access. Mirrors
1790    /// [`vectors_for_model`](Self::vectors_for_model)'s resolution order:
1791    /// lattice aliases route through the enum when registered, otherwise the
1792    /// custom provider's declared `dimensions()`. `None` when no such model
1793    /// is registered.
1794    pub fn embedder_dimensions(&self, model_name: &str) -> Option<usize> {
1795        if request_excludes_embedder(model_name) {
1796            return None;
1797        }
1798        if let Some(model) = parse_embedding_model_alias(model_name) {
1799            let key = model.to_string();
1800            let in_registry = self
1801                .embedder_registry
1802                .read()
1803                .map(|reg| reg.contains(&key))
1804                .unwrap_or(false);
1805            if in_registry {
1806                return Some(model.dimensions());
1807            }
1808        }
1809        self.embedder_registry
1810            .read()
1811            .ok()?
1812            .get_provider(model_name)
1813            .map(|p| p.dimensions())
1814    }
1815
1816    /// Get a TextSearch index for the entity corpus (single shared table).
1817    pub fn text(
1818        &self,
1819        token: &NamespaceToken,
1820    ) -> RuntimeResult<Arc<dyn khive_storage::TextSearch>> {
1821        let _ = token;
1822        Ok(self.backend.text("entities")?)
1823    }
1824
1825    /// Get a TextSearch index for the notes corpus (single shared table).
1826    pub fn text_for_notes(
1827        &self,
1828        token: &NamespaceToken,
1829    ) -> RuntimeResult<Arc<dyn khive_storage::TextSearch>> {
1830        let _ = token;
1831        Ok(self.backend.text("notes")?)
1832    }
1833
1834    /// Mint an authorization token for the given namespace.
1835    ///
1836    /// Consults the configured [`crate::Gate`] before minting. With the default
1837    /// `AllowAllGate` this always succeeds. When a real policy-backed gate is
1838    /// installed, this method enforces it and returns `PermissionDenied` on
1839    /// denial.
1840    ///
1841    /// The returned token's read visibility set defaults to `[ns]` — identical
1842    /// to the pre-visibility-set behaviour. Use [`Self::authorize_with_visibility`]
1843    /// to mint a token that can read additional namespaces.
1844    ///
1845    /// When `actor_id` is configured in `RuntimeConfig`, the token carries that
1846    /// actor label so that `comm.inbox` filters by `to_actor`. When
1847    /// unconfigured, the token carries `ActorRef::anonymous()` and inbox falls
1848    /// back to party-line behavior.
1849    pub fn authorize(&self, ns: Namespace) -> RuntimeResult<NamespaceToken> {
1850        let actor = crate::actor_identity::resolve_actor(self.config.actor_id.as_deref());
1851        let req = GateRequest::new(
1852            actor.clone(),
1853            ns.clone(),
1854            "authorize",
1855            serde_json::Value::Null,
1856        );
1857        match self.config.gate.check(&req) {
1858            Ok(ref decision) if decision.is_allow() => {
1859                if let khive_gate::GateDecision::Allow { ref obligations } = decision {
1860                    if !obligations.is_empty() {
1861                        tracing::debug!(
1862                            namespace = %ns.as_str(),
1863                            "authorize: obligations={:?}",
1864                            obligations
1865                        );
1866                    }
1867                }
1868                Ok(NamespaceToken::mint_authorized(ns, actor))
1869            }
1870            Ok(khive_gate::GateDecision::Deny { reason }) => {
1871                Err(crate::RuntimeError::permission_denied("authorize", reason))
1872            }
1873            Ok(_) => Err(crate::RuntimeError::permission_denied(
1874                "authorize",
1875                "gate denied",
1876            )),
1877            Err(e) => {
1878                tracing::warn!(
1879                    namespace = %ns.as_str(),
1880                    error = %crate::secret_gate::bounded_masked_log_text(&e.to_string()),
1881                    "authorize: gate check failed (fail-closed)"
1882                );
1883                Err(crate::RuntimeError::Internal(format!(
1884                    "gate error: {}",
1885                    e.wire_reason()
1886                )))
1887            }
1888        }
1889    }
1890
1891    /// Mint an authorization token with an explicit read-visibility set.
1892    ///
1893    /// `primary` is the **write namespace** — all records created via the
1894    /// returned token land there. `extra_visible` lists additional namespaces
1895    /// the token may read. The primary is always included in the visible set
1896    /// regardless of `extra_visible`.
1897    ///
1898    /// Usage (lambda:leo reading both leo and khive namespaces):
1899    /// ```rust,ignore
1900    /// let tok = rt.authorize_with_visibility(
1901    ///     Namespace::parse("lambda:leo").unwrap(),
1902    ///     vec![Namespace::parse("lambda:khive").unwrap()],
1903    /// )?;
1904    /// ```
1905    pub fn authorize_with_visibility(
1906        &self,
1907        primary: Namespace,
1908        extra_visible: Vec<Namespace>,
1909    ) -> RuntimeResult<NamespaceToken> {
1910        let actor = crate::actor_identity::resolve_actor(self.config.actor_id.as_deref());
1911        let req = GateRequest::new(
1912            actor.clone(),
1913            primary.clone(),
1914            "authorize",
1915            serde_json::Value::Null,
1916        );
1917        match self.config.gate.check(&req) {
1918            Ok(ref decision) if decision.is_allow() => {
1919                if let khive_gate::GateDecision::Allow { ref obligations } = decision {
1920                    if !obligations.is_empty() {
1921                        tracing::debug!(
1922                            namespace = %primary.as_str(),
1923                            "authorize_with_visibility: obligations={:?}",
1924                            obligations
1925                        );
1926                    }
1927                }
1928                // The primary check authorizes writes to `primary` only. Each
1929                // extra namespace grants read visibility, so each one takes
1930                // its own Read-classified gate check before it may enter the
1931                // minted set — a token must never carry visibility the gate
1932                // was not asked about. Any deny or gate error refuses the
1933                // whole mint, naming the offending namespace (fail-closed).
1934                for extra in &extra_visible {
1935                    let extra_req = GateRequest::new(
1936                        actor.clone(),
1937                        extra.clone(),
1938                        "authorize.visible",
1939                        serde_json::Value::Null,
1940                    );
1941                    match self.config.gate.check(&extra_req) {
1942                        Ok(ref extra_decision) if extra_decision.is_allow() => {}
1943                        Ok(khive_gate::GateDecision::Deny { reason }) => {
1944                            return Err(crate::RuntimeError::permission_denied(
1945                                "authorize",
1946                                format!(
1947                                    "visibility namespace {:?} denied: {reason}",
1948                                    extra.as_str()
1949                                ),
1950                            ));
1951                        }
1952                        Ok(_) => {
1953                            return Err(crate::RuntimeError::permission_denied(
1954                                "authorize",
1955                                format!("visibility namespace {:?} denied by gate", extra.as_str()),
1956                            ));
1957                        }
1958                        Err(e) => {
1959                            tracing::warn!(
1960                                namespace = %extra.as_str(),
1961                                error = %crate::secret_gate::bounded_masked_log_text(&e.to_string()),
1962                                "authorize_with_visibility: extra-namespace gate check failed (fail-closed)"
1963                            );
1964                            return Err(crate::RuntimeError::Internal(format!(
1965                                "gate error: {}",
1966                                e.wire_reason()
1967                            )));
1968                        }
1969                    }
1970                }
1971                Ok(NamespaceToken::mint_with_visibility(
1972                    primary,
1973                    extra_visible,
1974                    actor,
1975                ))
1976            }
1977            Ok(khive_gate::GateDecision::Deny { reason }) => {
1978                Err(crate::RuntimeError::permission_denied("authorize", reason))
1979            }
1980            Ok(_) => Err(crate::RuntimeError::permission_denied(
1981                "authorize",
1982                "gate denied",
1983            )),
1984            Err(e) => {
1985                tracing::warn!(
1986                    namespace = %primary.as_str(),
1987                    error = %crate::secret_gate::bounded_masked_log_text(&e.to_string()),
1988                    "authorize_with_visibility: gate check failed (fail-closed)"
1989                );
1990                Err(crate::RuntimeError::Internal(format!(
1991                    "gate error: {}",
1992                    e.wire_reason()
1993                )))
1994            }
1995        }
1996    }
1997
1998    /// Install the pack-aggregated edge endpoint rules.
1999    ///
2000    /// Called by the transport layer after the `VerbRegistry` is built so
2001    /// that runtime-layer edge validation can consult pack rules. Idempotent:
2002    /// later calls overwrite the previous rule set.
2003    pub fn install_edge_rules(&self, rules: Vec<EdgeEndpointRule>) {
2004        if let Ok(mut guard) = self.edge_rules.write() {
2005            *guard = rules;
2006        }
2007    }
2008
2009    /// Install an already-paired blob hydrator into this runtime.
2010    ///
2011    /// Reinstalling the exact same `Arc` is idempotent. A different pair is
2012    /// rejected: replacing it would split or reset the aggregate admission
2013    /// budget while requests may still hold leases.
2014    pub fn install_blob_hydrator(
2015        &self,
2016        hydrator: Arc<crate::blob::BlobHydrator>,
2017    ) -> RuntimeResult<()> {
2018        if hydrator.budget_bytes() != self.config.blob_hydration_bytes {
2019            return Err(RuntimeError::InvalidInput(format!(
2020                "blob hydrator budget {} does not match this runtime's resolved budget {}",
2021                hydrator.budget_bytes(),
2022                self.config.blob_hydration_bytes
2023            )));
2024        }
2025        // The mode gate must sit on THIS seam, not only on `install_blob_store`:
2026        // `BlobHydrator::new` is public, so without it a caller pairs a writable
2027        // store, installs it here, and `blob_store()` hands mutating pack paths
2028        // a writable store on a runtime whose declared mode is read-only.
2029        // Boot paths installing one hydrator across handles of MIXED modes —
2030        // where the blob pack's own backend mode, not each receiving
2031        // handle's, governs mutability — go through
2032        // [`Self::install_shared_blob_hydrator`] instead.
2033        if self.is_read_only() && !hydrator.enforces_read_only() {
2034            return Err(RuntimeError::InvalidInput(
2035                "this runtime is read-only: install the raw store with install_blob_store, \
2036                 which wraps it so every physical mutator refuses"
2037                    .to_string(),
2038            ));
2039        }
2040        self.install_blob_hydrator_slot(hydrator)
2041    }
2042
2043    /// Install a boot-shared hydrator whose mutability is governed by the
2044    /// blob runtime's own mode, not this handle's domain-store mode.
2045    ///
2046    /// ADR-160 D3 installs one hydrator `Arc` on every runtime handle a boot
2047    /// produces, and the documented multi-backend matrix includes a writable
2048    /// blob secondary beside a read-only main: there the shared hydrator is
2049    /// legitimately writable on a read-only domain handle. The mode decision
2050    /// must therefore already be encoded in the hydrator, and it must have
2051    /// been DERIVED, not declared: only hydrators built through
2052    /// [`crate::BlobHydrator::resolve_for_governing_backend`] — whose mode
2053    /// comes from the governing backend's own access mode — are accepted
2054    /// here. A hand-paired hydrator (`BlobHydrator::new` / `for_mode`) is
2055    /// refused so a safe downstream caller cannot use this seam to put a
2056    /// writable store on a read-only runtime; such callers use
2057    /// [`Self::install_blob_hydrator`], which holds hydrator mode against
2058    /// this runtime's own.
2059    ///
2060    /// This gate is a wrong-wiring guard, not an in-process sandbox: which
2061    /// backend governs is the boot host's topology assertion, and a caller
2062    /// who deliberately selects an unrelated writable backend as governing
2063    /// is outside what any runtime seam can enforce (see the trust-model
2064    /// note on [`crate::BlobHydrator::resolve_for_governing_backend`]).
2065    pub fn install_shared_blob_hydrator(
2066        &self,
2067        hydrator: Arc<crate::blob::BlobHydrator>,
2068    ) -> RuntimeResult<()> {
2069        if !hydrator.is_governed() {
2070            return Err(RuntimeError::InvalidInput(
2071                "the shared install seam accepts only hydrators whose mode was derived from a \
2072                 governing backend (BlobHydrator::resolve_for_governing_backend); use \
2073                 install_blob_hydrator for a hand-paired hydrator"
2074                    .to_string(),
2075            ));
2076        }
2077        if hydrator.budget_bytes() != self.config.blob_hydration_bytes {
2078            return Err(RuntimeError::InvalidInput(format!(
2079                "blob hydrator budget {} does not match this runtime's resolved budget {}",
2080                hydrator.budget_bytes(),
2081                self.config.blob_hydration_bytes
2082            )));
2083        }
2084        self.install_blob_hydrator_slot(hydrator)
2085    }
2086
2087    /// Whether `candidate` is the same pairing as the installed `current`:
2088    /// the exact `Arc`, or a distinct hydrator allocation over the same raw
2089    /// store with the same budget and mode. The latter arises when two
2090    /// concurrent first installs each construct a hydrator from one raw
2091    /// store — the `OnceLock` loser must read as idempotent, not as a
2092    /// conflicting install.
2093    fn is_same_blob_pairing(
2094        current: &Arc<crate::blob::BlobHydrator>,
2095        candidate: &Arc<crate::blob::BlobHydrator>,
2096    ) -> bool {
2097        Arc::ptr_eq(current, candidate)
2098            || (Arc::ptr_eq(&current.raw_store(), &candidate.raw_store())
2099                && current.budget_bytes() == candidate.budget_bytes()
2100                && current.enforces_read_only() == candidate.enforces_read_only())
2101    }
2102
2103    /// One-shot slot semantics shared by both install seams: first install
2104    /// wins, an equivalent pairing is idempotent, a different pairing is
2105    /// refused (replacing it would split or reset the aggregate admission
2106    /// budget while requests may still hold leases).
2107    fn install_blob_hydrator_slot(
2108        &self,
2109        hydrator: Arc<crate::blob::BlobHydrator>,
2110    ) -> RuntimeResult<()> {
2111        if let Some(current) = self.blob_hydrator.get() {
2112            return if Self::is_same_blob_pairing(current, &hydrator) {
2113                Ok(())
2114            } else {
2115                Err(RuntimeError::InvalidInput(
2116                    "a different blob hydrator is already installed".to_string(),
2117                ))
2118            };
2119        }
2120
2121        match self.blob_hydrator.set(hydrator) {
2122            Ok(()) => Ok(()),
2123            Err(candidate) => {
2124                let current = self.blob_hydrator.get().ok_or_else(|| {
2125                    RuntimeError::Internal(
2126                        "blob hydrator install raced without a visible winner".to_string(),
2127                    )
2128                })?;
2129                if Self::is_same_blob_pairing(current, &candidate) {
2130                    Ok(())
2131                } else {
2132                    Err(RuntimeError::InvalidInput(
2133                        "a different blob hydrator is already installed".to_string(),
2134                    ))
2135                }
2136            }
2137        }
2138    }
2139
2140    /// Pair and install a store using this runtime's resolved hydration budget.
2141    ///
2142    /// Boot paths that own multiple runtimes should instead construct one
2143    /// [`crate::BlobHydrator`] and call [`Self::install_blob_hydrator`] with
2144    /// the same `Arc` on every handle.
2145    pub fn install_blob_store(
2146        &self,
2147        store: Arc<dyn khive_storage::BlobStore>,
2148    ) -> RuntimeResult<()> {
2149        if let Some(current) = self.blob_hydrator.get() {
2150            // Reinstalling the same raw store is idempotent in BOTH modes:
2151            // on a read-only runtime the installed hydrator wraps the raw
2152            // store, so identity is checked against the raw handle the
2153            // hydrator remembers, not only the (possibly wrapped) paired one.
2154            let current_store = current.store();
2155            if Arc::ptr_eq(&current_store, &store) || Arc::ptr_eq(&current.raw_store(), &store) {
2156                return Ok(());
2157            }
2158        }
2159        // A read-only runtime holds its mode at this seam, not only during
2160        // boot resolution: an arbitrary store installed after launch is
2161        // wrapped so every physical mutator refuses while the bounded read
2162        // surface stays available. Without this, post-boot installation is a
2163        // writable bypass of the runtime's declared mode.
2164        let hydrator = if self.is_read_only() {
2165            crate::blob::BlobHydrator::new_read_only(store, self.config.blob_hydration_bytes)?
2166        } else {
2167            crate::blob::BlobHydrator::new(store, self.config.blob_hydration_bytes)?
2168        };
2169        self.install_blob_hydrator(Arc::new(hydrator))
2170    }
2171
2172    /// Return the installed shared blob hydrator, if boot configured one.
2173    pub fn blob_hydrator(&self) -> Option<Arc<crate::blob::BlobHydrator>> {
2174        self.blob_hydrator.get().cloned()
2175    }
2176
2177    /// Return the installed `BlobStore`, if the boot path resolved and
2178    /// installed one. `None` when no `[storage.blob]` selection was ever
2179    /// installed — e.g. a bare/test runtime constructed without going
2180    /// through the `khive-mcp` boot path.
2181    pub fn blob_store(&self) -> Option<Arc<dyn khive_storage::BlobStore>> {
2182        self.blob_hydrator.get().map(|hydrator| hydrator.store())
2183    }
2184
2185    /// Return the installed `BlobStore`, or `RuntimeError::Unconfigured` with
2186    /// the operator-facing message when none is installed.
2187    ///
2188    /// Packs share this conversion so an operator sees one error wherever the
2189    /// missing `[storage.blob]` configuration is first hit.
2190    pub fn require_blob_store(&self) -> RuntimeResult<Arc<dyn khive_storage::BlobStore>> {
2191        self.blob_store().ok_or_else(Self::no_blob_store)
2192    }
2193
2194    /// Return the installed shared blob hydrator, or `RuntimeError::Unconfigured`
2195    /// with the same message as [`Self::require_blob_store`] when none is
2196    /// installed. The store is read from the hydrator, so both accessors are
2197    /// unset under the same condition.
2198    pub fn require_blob_hydrator(&self) -> RuntimeResult<Arc<crate::blob::BlobHydrator>> {
2199        self.blob_hydrator().ok_or_else(Self::no_blob_store)
2200    }
2201
2202    fn no_blob_store() -> RuntimeError {
2203        RuntimeError::Unconfigured(
2204            "no BlobStore installed on this server (configure [storage.blob] in khive.toml, or \
2205             KHIVE_BLOB_ROOT)"
2206                .to_string(),
2207        )
2208    }
2209
2210    /// Install the pack-aggregated valid entity and note kinds.
2211    ///
2212    /// Called by the transport layer after the `VerbRegistry` is built so that
2213    /// runtime-layer entity/note creation and import validate kind strings against
2214    /// the merged pack vocabulary. Idempotent: later calls overwrite previous sets.
2215    ///
2216    /// When no kinds are installed (empty lists), kind validation is skipped at
2217    /// the runtime layer. The pack handler layer remains the primary enforcement
2218    /// point; this provides defense-in-depth for direct Rust callers and import.
2219    pub fn install_kind_registry(&self, entity_kinds: Vec<String>, note_kinds: Vec<String>) {
2220        if let Ok(mut guard) = self.valid_entity_kinds.write() {
2221            *guard = entity_kinds;
2222        }
2223        if let Ok(mut guard) = self.valid_note_kinds.write() {
2224            let prior = std::mem::take(&mut *guard);
2225            *guard = note_kinds
2226                .into_iter()
2227                .map(|name| NoteKindEntry {
2228                    embedding_policy: prior
2229                        .iter()
2230                        .find(|entry| entry.name == name)
2231                        .map(|entry| entry.embedding_policy)
2232                        .unwrap_or_default(),
2233                    name,
2234                    registered: true,
2235                })
2236                .collect();
2237        }
2238    }
2239
2240    /// Install pack-declared embedding policy on the note-kind registry.
2241    /// The transport calls this for every runtime after pack registration.
2242    pub fn install_note_embedding_policies(&self, policies: &[crate::NoteEmbeddingPolicySpec]) {
2243        if let Ok(mut guard) = self.valid_note_kinds.write() {
2244            for spec in policies {
2245                if let Some(entry) = guard.iter_mut().find(|entry| entry.name == spec.kind) {
2246                    entry.embedding_policy = spec.policy;
2247                } else {
2248                    guard.push(NoteKindEntry {
2249                        name: spec.kind.to_owned(),
2250                        embedding_policy: spec.policy,
2251                        registered: false,
2252                    });
2253                }
2254            }
2255        }
2256    }
2257
2258    /// Registered models selected by the installed embedding policy for a note kind.
2259    /// Unknown kinds retain the all-models default.
2260    pub fn embedding_models_for_note_kind(&self, kind: &str) -> Vec<String> {
2261        let policy = self
2262            .valid_note_kinds
2263            .read()
2264            .ok()
2265            .and_then(|guard| {
2266                guard
2267                    .iter()
2268                    .find(|entry| entry.name == kind)
2269                    .map(|entry| entry.embedding_policy)
2270            })
2271            .unwrap_or_default();
2272        let models = self.registered_embedding_model_names();
2273        match policy {
2274            crate::NoteEmbeddingPolicy::AllModels => models,
2275            crate::NoteEmbeddingPolicy::DefaultModel => {
2276                let default = self.default_embedder_name();
2277                models
2278                    .into_iter()
2279                    .filter(|name| name.as_str() == default)
2280                    .collect()
2281            }
2282        }
2283    }
2284
2285    /// Install the pack-owned note kinds aggregated from the pack registry.
2286    ///
2287    /// Called by the transport after the `VerbRegistry` is built, same timing
2288    /// as [`install_kind_registry`](Self::install_kind_registry).
2289    pub fn install_pack_owned_note_kinds(&self, kinds: Vec<String>) {
2290        if let Ok(mut guard) = self.pack_owned_note_kinds.write() {
2291            *guard = kinds;
2292        }
2293    }
2294
2295    /// Whether `kind` is a note kind owned by a pack (see
2296    /// [`install_pack_owned_note_kinds`](Self::install_pack_owned_note_kinds)).
2297    ///
2298    /// Always `false` before the transport installs the list — a bare runtime
2299    /// has no packs, so no kind is pack-owned there.
2300    pub fn is_pack_owned_note_kind(&self, kind: &str) -> bool {
2301        self.pack_owned_note_kinds
2302            .read()
2303            .map(|g| g.iter().any(|k| k == kind))
2304            .unwrap_or(false)
2305    }
2306
2307    /// Validate that `kind` is a pack-registered entity kind.
2308    ///
2309    /// Returns `Ok(())` when no kinds are installed (bare runtime without packs).
2310    /// Returns `InvalidInput` when kinds are installed and `kind` is not among them.
2311    pub(crate) fn validate_entity_kind(&self, kind: &str) -> crate::RuntimeResult<()> {
2312        let guard = self.valid_entity_kinds.read().map_err(|_| {
2313            crate::RuntimeError::Internal("entity kind registry lock poisoned".into())
2314        })?;
2315        if guard.is_empty() {
2316            return Ok(());
2317        }
2318        if guard.iter().any(|k| k == kind) {
2319            Ok(())
2320        } else {
2321            Err(crate::RuntimeError::InvalidInput(format!(
2322                "unknown entity kind {kind:?}; valid: {}",
2323                guard.join(", ")
2324            )))
2325        }
2326    }
2327
2328    /// Validate that `kind` is a pack-registered note kind.
2329    ///
2330    /// Returns `Ok(())` when no kinds are installed (bare runtime without packs).
2331    /// Returns `InvalidInput` when kinds are installed and `kind` is not among them.
2332    pub(crate) fn validate_note_kind(&self, kind: &str) -> crate::RuntimeResult<()> {
2333        let guard = self.valid_note_kinds.read().map_err(|_| {
2334            crate::RuntimeError::Internal("note kind registry lock poisoned".into())
2335        })?;
2336        if !guard.iter().any(|entry| entry.registered) {
2337            return Ok(());
2338        }
2339        if guard
2340            .iter()
2341            .any(|entry| entry.registered && entry.name == kind)
2342        {
2343            Ok(())
2344        } else {
2345            let valid = guard
2346                .iter()
2347                .filter(|entry| entry.registered)
2348                .map(|entry| entry.name.as_str())
2349                .collect::<Vec<_>>()
2350                .join(", ");
2351            Err(crate::RuntimeError::InvalidInput(format!(
2352                "unknown note kind {kind:?}; valid: {}",
2353                valid
2354            )))
2355        }
2356    }
2357
2358    /// Install a pack-supplied entity-type validator.
2359    ///
2360    /// Called by the `KgPack` during registration so that `create_many` can validate
2361    /// `entity_type` values at the runtime layer, closing the hole where direct Rust
2362    /// callers bypass the handler-layer `validate_entity_type` check.
2363    ///
2364    /// The callback receives `(kind, entity_type)` and returns the normalised type
2365    /// string, or `RuntimeError::InvalidInput` if the type is not registered for that
2366    /// kind. Passing `entity_type = None` must return `Ok(None)`.
2367    pub fn install_entity_type_validator(&self, f: EntityTypeValidatorFn) {
2368        if let Ok(mut guard) = self.entity_type_validator.write() {
2369            *guard = Some(f);
2370        }
2371    }
2372
2373    /// Validate and normalise `entity_type` through the pack-installed validator.
2374    ///
2375    /// Returns `Ok(entity_type)` when no validator is installed (bare runtime).
2376    /// Returns `InvalidInput` when a validator is installed and rejects the type.
2377    pub(crate) fn validate_entity_type_for_kind(
2378        &self,
2379        kind: &str,
2380        entity_type: Option<&str>,
2381    ) -> crate::RuntimeResult<Option<String>> {
2382        let guard = self.entity_type_validator.read().map_err(|_| {
2383            crate::RuntimeError::Internal("entity type validator lock poisoned".into())
2384        })?;
2385        match guard.as_ref() {
2386            None => Ok(entity_type.map(str::to_string)),
2387            Some(validate) => validate(kind, entity_type),
2388        }
2389    }
2390
2391    /// Install a pack-owned note-mutation hook.
2392    ///
2393    /// Overwrites any previously-installed hook, same single-slot semantics
2394    /// as [`install_entity_type_validator`](Self::install_entity_type_validator).
2395    /// In practice only one pack (`khive-pack-memory`) installs one today;
2396    /// if a second pack ever needs this, the slot should be widened to a
2397    /// `Vec` at that point rather than silently overwritten.
2398    pub fn install_note_mutation_hook(&self, f: NoteMutationHookFn) {
2399        if let Ok(mut guard) = self.note_mutation_hook.write() {
2400            *guard = Some(f);
2401        }
2402    }
2403
2404    /// Clone read-side backend and embedder handles without retaining this
2405    /// runtime's pack callback slots. Providers stored in one of those slots
2406    /// must not hold a clone that points back to their own installation Arc,
2407    /// including indirectly through another hook's captured runtime.
2408    pub fn detached_for_note_search_ann_provider(&self) -> Self {
2409        let mut detached = self.clone();
2410        detached.note_search_ann_provider = Arc::new(RwLock::new(None));
2411        detached.note_mutation_hook = Arc::new(RwLock::new(None));
2412        detached.entity_type_validator = Arc::new(RwLock::new(None));
2413        detached.note_write_validator = Arc::new(RwLock::new(None));
2414        detached.entity_kind_hooks = Arc::new(RwLock::new(Vec::new()));
2415        detached.fusion_executors = Arc::new(RwLock::new(HashMap::new()));
2416        detached
2417    }
2418
2419    /// Borrow the shared host domain without extending its external lifetime.
2420    pub fn background_domain(&self) -> crate::resource_admission::BackgroundDomainHandle {
2421        self.background_domain.clone()
2422    }
2423
2424    /// Retain external ownership when composing another host backend.
2425    pub fn background_root(&self) -> RuntimeResult<crate::resource_admission::BackgroundRoot> {
2426        self.background_root.clone().ok_or_else(|| {
2427            RuntimeError::Internal("a background view cannot own a new host runtime".into())
2428        })
2429    }
2430
2431    /// Close or observe this host's domain, without retaining its external owner.
2432    pub fn background_resources_control(
2433        &self,
2434    ) -> crate::resource_admission::BackgroundDomainControl {
2435        self.background_domain.control()
2436    }
2437
2438    /// Detach callbacks and external ownership before capturing a runtime in a job.
2439    pub fn background_view(&self) -> Self {
2440        let mut view = self.detached_for_note_search_ann_provider();
2441        view.background_root = None;
2442        view
2443    }
2444
2445    /// Install the memory pack's note-search provider only on its own opened
2446    /// backend. A same-named but separate store keeps the exact search route.
2447    pub fn install_note_search_ann_provider(&self, provider: Arc<dyn NoteSearchAnnProvider>) {
2448        if !provider.serves_backend(self) {
2449            return;
2450        }
2451        if let Ok(mut guard) = self.note_search_ann_provider.write() {
2452            *guard = Some(provider);
2453        }
2454    }
2455
2456    pub(crate) fn note_search_ann_provider(
2457        &self,
2458    ) -> RuntimeResult<Option<Arc<dyn NoteSearchAnnProvider>>> {
2459        self.note_search_ann_provider
2460            .read()
2461            .map(|guard| {
2462                guard
2463                    .as_ref()
2464                    .filter(|provider| provider.serves_backend(self))
2465                    .cloned()
2466            })
2467            .map_err(|_| RuntimeError::Internal("note-search ANN provider lock poisoned".into()))
2468    }
2469
2470    /// Install the pack-aggregated entity-kind update hooks (issue #2943).
2471    ///
2472    /// Called by the transport after the `VerbRegistry` is built, same
2473    /// timing as [`install_kind_registry`](Self::install_kind_registry) —
2474    /// pass `registry.entity_kind_hooks()`. Idempotent: a later call
2475    /// replaces the set.
2476    pub fn install_entity_kind_hooks(&self, hooks: EntityKindHooks) {
2477        if let Ok(mut guard) = self.entity_kind_hooks.write() {
2478            *guard = hooks;
2479        }
2480    }
2481
2482    /// The installed `KindHook` for entity `kind`, if its owning pack
2483    /// registered one via [`install_entity_kind_hooks`](Self::install_entity_kind_hooks).
2484    ///
2485    /// `None` before the transport installs the aggregate (bare runtime) or
2486    /// when no pack registered a hook for this entity kind — the caller
2487    /// treats this the same as a hook whose `validate_entity_update`
2488    /// inherited the trait's `Ok(())` default.
2489    pub(crate) fn entity_kind_hook(&self, kind: &str) -> Option<Arc<dyn KindHook>> {
2490        find_entity_owner_hook(&self.entity_kind_hooks, kind)
2491    }
2492
2493    pub(crate) fn canonical_entity_owner_lookup(&self) -> EntityOwnerHookLookup {
2494        EntityOwnerHookLookup {
2495            hooks: Arc::clone(&self.entity_kind_hooks),
2496        }
2497    }
2498
2499    /// Install a pack-owned note-write validator.
2500    ///
2501    /// Called during pack registration (`PackRuntime::register_note_write_validator`)
2502    /// so that the covered note-write sites carrying caller-supplied
2503    /// `properties` derive the owning pack's identity properties from the
2504    /// authorization token, closing the gap where a direct Rust caller, the
2505    /// generic `create` verb, or the proposal-apply path (which dispatches no
2506    /// pack hooks) writes them unchecked. Single-slot semantics, same as
2507    /// [`install_note_mutation_hook`](Self::install_note_mutation_hook): a
2508    /// second installing pack overwrites the first, so a validator must return
2509    /// kinds it does not own unchanged.
2510    ///
2511    /// Covered sites — each calls `derive_note_write_properties`
2512    /// before the write: `create_note_inner` (`operations.rs`, the generic
2513    /// `create` verb funnel and every other public `create_note*` variant),
2514    /// `atomic_prepare::prepare_add_note` (the proposal-apply add-note path),
2515    /// and `atomic_message::create_notes_atomic_with_report` (the atomic
2516    /// multi-note writer).
2517    ///
2518    /// NOT covered by this validator: `try_create_note` (`operations.rs`).
2519    /// `try_create_note` is deliberately excluded — its only caller path is
2520    /// `comm.ingest`, where `properties.from_actor` is the external transport
2521    /// sender named by the `from` parameter, not the authenticated caller,
2522    /// and where transport-owned quarantine/channel properties are
2523    /// legitimately established. Running the generic validator there would
2524    /// stamp every inbound message as the ingesting daemon and reject the
2525    /// evidence the trusted ingest handler just derived. `try_create_note`
2526    /// instead runs its own narrower reserved-transport-property check
2527    /// inline (`operations.rs`'s `try_create_note_impl`), which allows the
2528    /// `message`-kind transport properties only when called through
2529    /// [`Self::try_create_note_as_trusted_ingest`] with a
2530    /// [`crate::pack::ChannelIngestCapability`].
2531    ///
2532    /// The `NoteStore` returned by [`notes`](Self::notes) is covered by a
2533    /// different, narrower mechanism: it is wrapped in
2534    /// `note_store_guard::PolicyEnforcingNoteStore`, which refuses
2535    /// `upsert_note` / `upsert_notes` / `try_insert_note` /
2536    /// `replace_note_if_unchanged` calls that would write a `kind = "message"`
2537    /// note carrying `quarantined` / `channel_kind` / `channel_slug`, and
2538    /// refuses `set_note_property` / `try_patch_note_property` /
2539    /// `patch_note_property_atomic` / `update_note_properties` calls that
2540    /// would patch any of those keys onto any note — unconditionally, since
2541    /// that public accessor has no way to see a trust decision. `try_create_note_impl` itself reaches storage through
2542    /// `Self::raw_notes`, the unwrapped accessor, so its own inline check
2543    /// (which can legitimately allow those properties for trusted ingest)
2544    /// is not double-enforced or contradicted by the wrapper.
2545    /// Register a pack-defined custom fusion strategy under `name` (ADR-012).
2546    ///
2547    /// Unlike `install_entity_type_validator`/`install_note_mutation_hook`,
2548    /// this slot is keyed rather than single-occupancy: multiple packs each
2549    /// register their own named strategy, and a second registration under an
2550    /// already-used `name` replaces the first. Looked up by
2551    /// `FusionStrategy::Custom { name, .. }` at the hybrid-search dispatch
2552    /// boundary in `crate::fusion`; an unregistered name fails closed with
2553    /// `RuntimeError::UnknownFusionStrategy` rather than silently falling
2554    /// back to RRF.
2555    pub fn register_fusion_strategy(
2556        &self,
2557        name: impl Into<String>,
2558        executor: Arc<dyn crate::fusion::FusionExecutor>,
2559    ) {
2560        if let Ok(mut guard) = self.fusion_executors.write() {
2561            guard.insert(name.into(), executor);
2562        }
2563    }
2564
2565    /// Resolve a registered custom fusion executor by name.
2566    ///
2567    /// Returns `RuntimeError::UnknownFusionStrategy` when no pack has
2568    /// registered `name` — callers must invoke this before any
2569    /// empty-input/zero-limit short circuit so a misconfigured name errors
2570    /// on every call, including zero-result ones.
2571    pub(crate) fn fusion_executor(
2572        &self,
2573        name: &str,
2574    ) -> RuntimeResult<Arc<dyn crate::fusion::FusionExecutor>> {
2575        let guard = self
2576            .fusion_executors
2577            .read()
2578            .map_err(|_| RuntimeError::Internal("fusion executor registry lock poisoned".into()))?;
2579        guard
2580            .get(name)
2581            .cloned()
2582            .ok_or_else(|| RuntimeError::UnknownFusionStrategy(name.to_string()))
2583    }
2584
2585    pub fn install_note_write_validator(&self, f: NoteWriteValidatorFn) {
2586        if let Ok(mut guard) = self.note_write_validator.write() {
2587            *guard = Some(f);
2588        }
2589    }
2590
2591    /// Whether a note-write validator is installed on this runtime.
2592    ///
2593    /// Exists so a transport's own tests can assert, per boot path, that the
2594    /// documented startup sequence actually filled the slot. A missing install
2595    /// fails open and silently — an empty slot passes caller-supplied
2596    /// properties straight through, which no write site can distinguish from a
2597    /// validator that approved them — so occupancy is asserted, never assumed.
2598    pub fn has_note_write_validator(&self) -> bool {
2599        self.note_write_validator
2600            .read()
2601            .map(|g| g.is_some())
2602            .unwrap_or(false)
2603    }
2604
2605    /// Run caller-supplied note `properties` through the installed note-write
2606    /// validator, returning the properties to store.
2607    ///
2608    /// Returns them unchanged when no validator is installed (bare runtime).
2609    pub(crate) fn derive_note_write_properties(
2610        &self,
2611        kind: &str,
2612        token: &NamespaceToken,
2613        properties: Option<serde_json::Value>,
2614    ) -> RuntimeResult<Option<serde_json::Value>> {
2615        let validator = self
2616            .note_write_validator
2617            .read()
2618            .map_err(|_| RuntimeError::Internal("note write validator lock poisoned".into()))?
2619            .clone();
2620        match validator {
2621            None => Ok(properties),
2622            Some(validate) => validate(kind, &token.actor().id, properties),
2623        }
2624    }
2625
2626    /// Invoke the pack-installed note-mutation hook, if any.
2627    ///
2628    /// `kind` is the note's `kind` string (e.g. `"memory"`); `id` is the
2629    /// note's UUID. No-op when no hook is installed (bare runtime, or no
2630    /// pack cares). Errors inside the hook are the hook's own concern to
2631    /// handle/log — this call site cannot propagate a failure without
2632    /// changing `update_note`/`delete_note`'s already-committed success
2633    /// return value.
2634    pub(crate) async fn fire_note_mutation_hook(&self, kind: &str, id: uuid::Uuid) {
2635        let hook = self
2636            .note_mutation_hook
2637            .read()
2638            .ok()
2639            .and_then(|guard| guard.clone());
2640        if let Some(hook) = hook {
2641            hook(kind.to_string(), id).await;
2642        }
2643    }
2644
2645    /// Snapshot of currently-installed pack edge rules.
2646    ///
2647    /// This is the same composed rule set `validate_edge_relation_endpoints`
2648    /// consults via `pack_rule_allows` when accepting/rejecting an edge. Public
2649    /// so pack-layer error-hint code (e.g. `khive-pack-kg`'s
2650    /// `valid_relations_for_entity_pair`) can derive hints from the exact
2651    /// source the validator uses, rather than maintaining a separate
2652    /// hand-authored table that can drift out of sync.
2653    pub fn pack_edge_rules(&self) -> Vec<EdgeEndpointRule> {
2654        self.edge_rules
2655            .read()
2656            .map(|g| g.clone())
2657            .unwrap_or_default()
2658    }
2659
2660    /// Borrow the installed pack edge rules for a synchronous calculation.
2661    pub(crate) fn with_pack_edge_rules<T>(&self, f: impl FnOnce(&[EdgeEndpointRule]) -> T) -> T {
2662        match self.edge_rules.read() {
2663            Ok(rules) => f(&rules),
2664            Err(_) => f(&[]),
2665        }
2666    }
2667
2668    /// List registered embedding models via `SqlAccess`, routing through the
2669    /// existing connection pool rather than opening a fresh `Connection` per call.
2670    ///
2671    /// Optionally filter by `engine_name`. Returns an empty vec when the
2672    /// `_embedding_models` table does not yet exist (e.g. no migrations have run
2673    /// or no models have been registered). All other SQL errors are propagated.
2674    /// Malformed required fields, unknown statuses and invalid non-NULL optional
2675    /// dimensions/UUIDs are warned and skipped. The legacy optional timestamps
2676    /// retain their non-integer-to-None compatibility behavior.
2677    pub async fn list_embedding_models(
2678        &self,
2679        engine_filter: Option<&str>,
2680    ) -> RuntimeResult<Vec<crate::EmbeddingModelRecord>> {
2681        use khive_storage::{SqlStatement, SqlValue};
2682
2683        let (sql_text, params) = if let Some(engine) = engine_filter {
2684            (
2685                "SELECT id, engine_name, model_id, key_version, dim, output_dim, status, \
2686                 activated_at, superseded_at, superseded_by, canonical_key, created_at \
2687                 FROM _embedding_models WHERE engine_name = ?1 \
2688                 ORDER BY engine_name, activated_at IS NULL, activated_at"
2689                    .to_string(),
2690                vec![SqlValue::Text(engine.to_string())],
2691            )
2692        } else {
2693            (
2694                "SELECT id, engine_name, model_id, key_version, dim, output_dim, status, \
2695                 activated_at, superseded_at, superseded_by, canonical_key, created_at \
2696                 FROM _embedding_models \
2697                 ORDER BY engine_name, activated_at IS NULL, activated_at"
2698                    .to_string(),
2699                vec![],
2700            )
2701        };
2702
2703        let stmt = SqlStatement {
2704            sql: sql_text,
2705            params,
2706            label: Some("list_embedding_models".into()),
2707        };
2708
2709        let mut reader = self
2710            .sql()
2711            .reader()
2712            .await
2713            .map_err(crate::RuntimeError::Storage)?;
2714
2715        let rows = match reader.query_all(stmt).await {
2716            Ok(rows) => rows,
2717            Err(e) if e.to_string().contains("no such table: _embedding_models") => {
2718                return Ok(Vec::new())
2719            }
2720            Err(e) => return Err(crate::RuntimeError::Storage(e)),
2721        };
2722
2723        Ok(rows
2724            .iter()
2725            .filter_map(crate::EmbeddingModelRecord::from_sql_row)
2726            .collect())
2727    }
2728}
2729
2730fn vector_dimensions_from_ddl(ddl: &str) -> Option<usize> {
2731    let lower = ddl.to_ascii_lowercase();
2732    let suffix = lower.split_once("embedding float[")?.1;
2733    let dimension = suffix.split_once(']')?.0;
2734    if dimension.is_empty() || !dimension.bytes().all(|byte| byte.is_ascii_digit()) {
2735        return None;
2736    }
2737    dimension.parse().ok()
2738}
2739
2740// IN-CRATE TEST JUSTIFICATION: tests here cover KhiveRuntime construction helpers
2741// (in-memory backend wiring, NamespaceToken::for_namespace) that are
2742// pub(crate)-only and cannot be called from the integration test crate.
2743#[cfg(test)]
2744#[path = "runtime_tests.rs"]
2745mod tests;
2746
2747#[cfg(test)]
2748mod background_resource_tests {
2749    use super::*;
2750
2751    fn config() -> RuntimeConfig {
2752        RuntimeConfig {
2753            db_path: None,
2754            warm_concurrency: 3,
2755            maintenance_concurrency: 2,
2756            ..RuntimeConfig::no_embeddings()
2757        }
2758    }
2759
2760    #[test]
2761    fn clones_core_and_detached_views_share_the_original_domain() {
2762        let runtime = KhiveRuntime::new(config()).expect("root runtime");
2763        let root = runtime.background_root().expect("external root");
2764        for view in [
2765            runtime.clone(),
2766            runtime.core(),
2767            runtime.detached_for_note_search_ann_provider(),
2768        ] {
2769            assert!(root.same_domain(&view.background_root().expect("retained external root")));
2770        }
2771        let other = KhiveRuntime::new(config()).expect("independent root");
2772        assert!(!root.same_domain(&other.background_root().unwrap()));
2773    }
2774
2775    #[test]
2776    fn assigned_backend_and_rebound_core_keep_the_main_domain() {
2777        let main = KhiveRuntime::new(config()).expect("main runtime");
2778        let root = main.background_root().unwrap();
2779        let secondary_config = RuntimeConfig {
2780            backend_id: BackendId::parse("secondary").expect("secondary backend id"),
2781            ..config()
2782        };
2783        let secondary = KhiveRuntime::try_from_backend_in_domain(
2784            Arc::new(StorageBackend::memory().unwrap()),
2785            secondary_config,
2786            root.clone(),
2787        )
2788        .unwrap()
2789        .with_core_backend(Arc::clone(&main.backend));
2790        assert!(root.same_domain(&secondary.background_root().unwrap()));
2791        assert!(root.same_domain(&secondary.core().background_root().unwrap()));
2792    }
2793
2794    #[test]
2795    fn background_view_cannot_keep_the_external_root_alive() {
2796        let runtime = KhiveRuntime::new(config()).expect("root runtime");
2797        let view = runtime.background_view();
2798        let control = view.background_resources_control();
2799        assert!(view.background_root().is_err());
2800        assert_eq!(view.background_domain().limits().warm(), 3);
2801        assert!(!control.is_closed());
2802        drop(runtime);
2803        assert!(
2804            control.is_closed(),
2805            "last external root closes despite the job view"
2806        );
2807    }
2808
2809    #[test]
2810    fn invalid_limits_and_injected_limit_mismatch_are_refused() {
2811        for (warm, maintenance) in [(0, 2), (3, 0), (usize::MAX, 2), (3, usize::MAX)] {
2812            let mut bad = config();
2813            bad.warm_concurrency = warm;
2814            bad.maintenance_concurrency = maintenance;
2815            assert!(matches!(
2816                KhiveRuntime::new(bad),
2817                Err(RuntimeError::InvalidInput(_))
2818            ));
2819        }
2820        let main = KhiveRuntime::new(config()).unwrap();
2821        let mut different = config();
2822        different.warm_concurrency += 1;
2823        assert!(matches!(
2824            KhiveRuntime::try_from_backend_in_domain(
2825                Arc::new(StorageBackend::memory().unwrap()),
2826                different,
2827                main.background_root().unwrap(),
2828            ),
2829            Err(RuntimeError::InvalidInput(_))
2830        ));
2831    }
2832}