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