1use std::path::Path;
9use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
10use std::sync::Arc;
11
12use rusqlite::OptionalExtension;
13
14use crate::database_owner_identity::{DatabaseOwnerIdentity, DatabaseOwnerIdentityError};
15use crate::error::SqliteError;
16use crate::pool::{ConnectionPool, PoolConfig, WalCeilingPolicy};
17use crate::stores::{agents, attachment, blob, entity, event, graph, note, sparse, text, vectors};
18
19mod capability_factories;
20mod code_map;
21mod core_stores;
22#[path = "backend/schema_readiness.rs"]
23mod memory_visibility;
24mod pack_schema;
25mod policy_open;
26mod schema_barrier;
27pub use schema_barrier::ForcedIndexCheck;
28
29#[cfg(test)]
30#[path = "backend/filter_builder_tests.rs"]
31mod filter_builder_tests;
32
33mod namespace_listing;
34pub use namespace_listing::NamespaceLiveness;
35
36#[cfg(test)]
37#[path = "backend/memory_visibility_tests.rs"]
38mod memory_visibility_tests;
39
40#[cfg(any(unix, windows))]
41mod claimed_file_identity;
42
43fn sqlite_table_exists(conn: &rusqlite::Connection, table: &str) -> Result<bool, SqliteError> {
44 conn.query_row(
45 "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1",
46 rusqlite::params![table],
47 |row| row.get::<_, i64>(0),
48 )
49 .optional()
50 .map(|row| row.is_some())
51 .map_err(SqliteError::Rusqlite)
52}
53
54fn ensure_fts_rowid_map_backfilled(
110 conn: &rusqlite::Connection,
111 table: &str,
112 admission: &crate::pool::WriteAdmission,
113) -> Result<(), SqliteError> {
114 let map = text::rowid_map_table(table);
115 let state = text::rowid_map_state_table(table);
116 let already_backfilled: bool = conn.query_row(
117 &format!("SELECT EXISTS(SELECT 1 FROM {state} WHERE key = 'backfill' AND value = ?1)"),
118 rusqlite::params![text::ROWID_MAP_BACKFILL_COMPLETE],
119 |row| row.get(0),
120 )?;
121 if already_backfilled {
122 return Ok(());
123 }
124
125 conn.execute_batch("BEGIN IMMEDIATE")?;
126 if let Err(error) = admission.check() {
127 return Err(crate::migrations::capacity_refusal_after_rollback(
128 conn,
129 conn.execute_batch("ROLLBACK"),
130 error,
131 "FTS rowid-map backfill",
132 ));
133 }
134 let result: Result<(), SqliteError> = (|| {
135 conn.execute_batch(&format!(
136 "DELETE FROM {map} WHERE NOT EXISTS ( \
137 SELECT 1 FROM {table} \
138 WHERE {table}.rowid = {map}.rowid \
139 AND {table}.namespace = {map}.namespace \
140 AND {table}.subject_id = {map}.subject_id \
141 )"
142 ))?;
143 conn.execute_batch(&format!(
144 "INSERT OR REPLACE INTO {map} (namespace, subject_id, rowid) \
145 SELECT namespace, subject_id, rowid FROM {table} \
146 WHERE namespace IS NOT NULL AND subject_id IS NOT NULL \
147 ORDER BY updated_at ASC, rowid ASC"
148 ))?;
149 conn.execute_batch(&format!(
150 "DELETE FROM {table} \
151 WHERE namespace IS NOT NULL AND subject_id IS NOT NULL \
152 AND rowid NOT IN (SELECT rowid FROM {map})"
153 ))?;
154 conn.execute(
155 &format!("INSERT OR REPLACE INTO {state} (key, value) VALUES ('backfill', ?1)"),
156 rusqlite::params![text::ROWID_MAP_BACKFILL_COMPLETE],
157 )?;
158 Ok(())
159 })();
160
161 match result {
162 Ok(()) => {
163 conn.execute_batch("COMMIT")?;
164 Ok(())
165 }
166 Err(e) => {
167 let _ = conn.execute_batch("ROLLBACK");
168 Err(e)
169 }
170 }
171}
172
173fn warn_scan_fallback_once(table: &str) {
179 static WARNED: std::sync::Once = std::sync::Once::new();
180 WARNED.call_once(|| {
181 tracing::warn!(
182 table,
183 "opened a read-only text-search table with no rowid-map sidecar, or with a sidecar \
184 that has never proven a completed backfill (no durable completion marker); a \
185 read-only connection cannot create, backfill, or reconcile the map itself, so this \
186 falls back to pre-map namespace/subject_id scan predicates for get/delete on this \
187 table rather than trusting a map that might be partial"
188 );
189 });
190}
191
192fn validate_vector_model_key(model_key: &str) -> Result<(), SqliteError> {
193 if model_key.is_empty()
194 || !model_key
195 .chars()
196 .all(|c| c.is_ascii_alphanumeric() || c == '_')
197 {
198 return Err(SqliteError::InvalidData(format!(
199 "invalid model_key '{}': must be non-empty and contain only \
200 alphanumeric/underscore characters",
201 model_key
202 )));
203 }
204 Ok(())
205}
206
207fn validate_vector_table_columns(
208 conn: &rusqlite::Connection,
209 table: &str,
210) -> Result<(), SqliteError> {
211 let pragma = format!("PRAGMA table_xinfo({table})");
212 let mut stmt = conn.prepare(&pragma)?;
213 let mut rows = stmt.query([])?;
214 let mut has_field = false;
215 let mut has_embedding_model = false;
216 while let Some(row) = rows.next()? {
217 let name: String = row.get(1)?;
218 if name == "field" {
219 has_field = true;
220 }
221 if name == "embedding_model" {
222 has_embedding_model = true;
223 }
224 }
225 if !has_field || !has_embedding_model {
226 return Err(SqliteError::InvalidData(format!(
227 "vec0 table '{table}' is missing required column(s) (field={has_field}, \
228 embedding_model={has_embedding_model}); this is a pre-v0.2.8 vector schema and is \
229 not supported — recreate the database"
230 )));
231 }
232 Ok(())
233}
234
235#[derive(Clone, Copy, Debug, PartialEq, Eq)]
236pub(crate) enum StoreSchemaKind {
237 Entities,
238 Graph,
239 Notes,
240 Events,
241 Agents,
242}
243
244impl StoreSchemaKind {
245 pub(crate) fn initializer(self) -> fn(&rusqlite::Connection) -> Result<(), rusqlite::Error> {
246 match self {
247 Self::Entities => entity::ensure_entities_schema,
248 Self::Graph => graph::ensure_graph_schema,
249 Self::Notes => note::ensure_notes_schema,
250 Self::Events => event::ensure_events_schema,
251 Self::Agents => agents::ensure_agents_schema,
252 }
253 }
254}
255
256#[derive(Default)]
257pub(crate) struct StoreSchemaGate {
258 pub(crate) ready: AtomicBool,
259 #[cfg(test)]
260 pub(crate) attempts: AtomicUsize,
261}
262
263impl StoreSchemaGate {
264 pub(crate) fn ensure(
265 &self,
266 conn: &rusqlite::Connection,
267 ensure: fn(&rusqlite::Connection) -> Result<(), rusqlite::Error>,
268 ) -> Result<(), rusqlite::Error> {
269 if self.ready.load(Ordering::Acquire) {
272 return Ok(());
273 }
274 #[cfg(test)]
275 self.attempts.fetch_add(1, Ordering::Relaxed);
276 ensure(conn)?;
277 self.ready.store(true, Ordering::Release);
278 Ok(())
279 }
280}
281
282pub struct StorageBackend {
288 pool: Arc<ConnectionPool>,
289 is_file_backed: bool,
290 path: Option<std::path::PathBuf>,
291 vector_tables_ready: parking_lot::Mutex<std::collections::HashSet<String>>,
299 text_tables_ready: parking_lot::Mutex<std::collections::HashSet<String>>,
307 sparse_tables_ready: parking_lot::Mutex<std::collections::HashSet<String>>,
313 notes_seq_repair_runs: AtomicUsize,
320 store_schemas: [Arc<StoreSchemaGate>; 5],
321}
322
323impl StorageBackend {
324 pub fn sqlite(path: impl AsRef<Path>) -> Result<Self, SqliteError> {
338 Self::sqlite_with_pool_config(path, PoolConfig::default(), None)
339 }
340
341 #[cfg(any(test, feature = "test-support"))]
343 pub fn sqlite_for_test(path: impl AsRef<Path>) -> Result<Self, SqliteError> {
344 Self::sqlite_with_pool_config(path, PoolConfig::for_test(), None)
345 }
346
347 #[cfg(any(test, feature = "test-support"))]
349 pub fn sqlite_for_test_with_journal_mode(
350 path: impl AsRef<Path>,
351 wal_mode: bool,
352 busy_timeout: std::time::Duration,
353 ) -> Result<Self, SqliteError> {
354 Self::sqlite_with_pool_config(
355 path,
356 PoolConfig {
357 wal_mode,
358 busy_timeout,
359 write_queue_enabled: Some(true),
360 ..PoolConfig::for_test()
361 },
362 None,
363 )
364 }
365
366 #[cfg(any(test, feature = "test-support"))]
371 pub fn sqlite_for_test_with_journal_mode_in(
372 path: impl AsRef<Path>,
373 wal_mode: bool,
374 busy_timeout: std::time::Duration,
375 volume_lock_dir: std::path::PathBuf,
376 ) -> Result<Self, SqliteError> {
377 Self::sqlite_with_pool_config(
378 path,
379 PoolConfig {
380 wal_mode,
381 busy_timeout,
382 write_queue_enabled: Some(true),
383 volume_lock_dir: Some(volume_lock_dir),
384 ..PoolConfig::for_test()
385 },
386 None,
387 )
388 }
389
390 pub fn sqlite_with_max_readers(
394 path: impl AsRef<Path>,
395 max_readers: Option<usize>,
396 ) -> Result<Self, SqliteError> {
397 Self::sqlite_with_pool_config(path, PoolConfig::default(), max_readers)
398 }
399
400 pub fn sqlite_with_max_readers_and_wal_ceiling(
404 path: impl AsRef<Path>,
405 max_readers: Option<usize>,
406 wal_ceiling: WalCeilingPolicy,
407 ) -> Result<Self, SqliteError> {
408 Self::sqlite_with_pool_config(
409 path,
410 PoolConfig {
411 wal_ceiling,
412 ..PoolConfig::default()
413 },
414 max_readers,
415 )
416 }
417
418 pub(crate) fn sqlite_with_pool_config(
419 path: impl AsRef<Path>,
420 pool_config: PoolConfig,
421 max_readers: Option<usize>,
422 ) -> Result<Self, SqliteError> {
423 crate::extension::ensure_extensions_loaded();
424 let resolved = path.as_ref().to_path_buf();
425 let read_only =
426 std::fs::metadata(&resolved).is_ok_and(|metadata| metadata.permissions().readonly());
427 let mut config = PoolConfig {
428 path: Some(resolved.clone()),
429 read_only,
430 ..pool_config
431 };
432 if let Some(max_readers) = max_readers {
433 config.max_readers = max_readers;
434 }
435 if read_only {
436 config.write_queue_enabled = Some(false);
437 }
438 let pool = ConnectionPool::new(config)?;
439 Ok(Self {
440 pool: Arc::new(pool),
441 is_file_backed: true,
442 path: Some(resolved),
443 vector_tables_ready: Default::default(),
444 text_tables_ready: Default::default(),
445 sparse_tables_ready: Default::default(),
446 notes_seq_repair_runs: AtomicUsize::new(0),
447 store_schemas: std::array::from_fn(|_| Arc::new(StoreSchemaGate::default())),
448 })
449 }
450
451 pub fn sqlite_read_only(path: impl AsRef<Path>) -> Result<Self, SqliteError> {
462 Self::sqlite_read_only_with_pool_config(path, PoolConfig::default(), None)
463 }
464
465 #[cfg(any(test, feature = "test-support"))]
467 pub fn sqlite_read_only_for_test(path: impl AsRef<Path>) -> Result<Self, SqliteError> {
468 Self::sqlite_read_only_with_pool_config(path, PoolConfig::for_test(), None)
469 }
470
471 pub fn sqlite_read_only_with_max_readers(
473 path: impl AsRef<Path>,
474 max_readers: Option<usize>,
475 ) -> Result<Self, SqliteError> {
476 Self::sqlite_read_only_with_pool_config(path, PoolConfig::default(), max_readers)
477 }
478
479 pub fn sqlite_read_only_with_max_readers_and_wal_ceiling(
482 path: impl AsRef<Path>,
483 max_readers: Option<usize>,
484 wal_ceiling: WalCeilingPolicy,
485 ) -> Result<Self, SqliteError> {
486 Self::sqlite_read_only_with_pool_config(
487 path,
488 PoolConfig {
489 wal_ceiling,
490 ..PoolConfig::default()
491 },
492 max_readers,
493 )
494 }
495
496 pub fn sqlite_read_only_live_with_max_readers_and_wal_ceiling(
501 path: impl AsRef<Path>,
502 max_readers: Option<usize>,
503 wal_ceiling: WalCeilingPolicy,
504 ) -> Result<Self, SqliteError> {
505 Self::sqlite_read_only_with_pool_constructor(
506 path,
507 PoolConfig {
508 wal_ceiling,
509 ..PoolConfig::default()
510 },
511 max_readers,
512 ConnectionPool::new_read_only_live,
513 )
514 }
515
516 fn sqlite_read_only_with_pool_config(
517 path: impl AsRef<Path>,
518 pool_config: PoolConfig,
519 max_readers: Option<usize>,
520 ) -> Result<Self, SqliteError> {
521 Self::sqlite_read_only_with_pool_constructor(
522 path,
523 pool_config,
524 max_readers,
525 ConnectionPool::new,
526 )
527 }
528
529 fn sqlite_read_only_with_pool_constructor(
530 path: impl AsRef<Path>,
531 pool_config: PoolConfig,
532 max_readers: Option<usize>,
533 open_pool: fn(PoolConfig) -> Result<ConnectionPool, SqliteError>,
534 ) -> Result<Self, SqliteError> {
535 crate::extension::ensure_extensions_loaded();
536 let resolved = path.as_ref().to_path_buf();
537 let mut config = PoolConfig {
538 path: Some(resolved.clone()),
539 read_only: true,
540 write_queue_enabled: Some(false),
541 ..pool_config
542 };
543 if let Some(max_readers) = max_readers {
544 config.max_readers = max_readers;
545 }
546 let pool = open_pool(config)?;
552 Ok(Self {
553 pool: Arc::new(pool),
554 is_file_backed: true,
555 path: Some(resolved),
556 vector_tables_ready: Default::default(),
557 text_tables_ready: Default::default(),
558 sparse_tables_ready: Default::default(),
559 notes_seq_repair_runs: AtomicUsize::new(0),
560 store_schemas: std::array::from_fn(|_| Arc::new(StoreSchemaGate::default())),
561 })
562 }
563
564 pub fn memory() -> Result<Self, SqliteError> {
570 crate::extension::ensure_extensions_loaded();
571 let config = PoolConfig {
572 path: None,
573 ..PoolConfig::default()
574 };
575 let pool = ConnectionPool::new(config)?;
576 Ok(Self {
577 pool: Arc::new(pool),
578 is_file_backed: false,
579 path: None,
580 vector_tables_ready: Default::default(),
581 text_tables_ready: Default::default(),
582 sparse_tables_ready: Default::default(),
583 notes_seq_repair_runs: AtomicUsize::new(0),
584 store_schemas: std::array::from_fn(|_| Arc::new(StoreSchemaGate::default())),
585 })
586 }
587
588 pub fn apply_schema(
595 &self,
596 plan: &crate::migrations::ServiceSchemaPlan,
597 ) -> Result<(), SqliteError> {
598 let admission = self.pool.write_admission();
599 crate::migrations::apply_schema_plan_with_admission(
600 &mut self.pool.migration_transactions(),
601 plan,
602 &admission,
603 )
604 }
605
606 pub fn apply_pack_ddl_statements(
622 &self,
623 statements: &[&'static str],
624 ) -> Result<(), SqliteError> {
625 self.apply_pack_ddl_statements_with_columns(statements, &[])
626 }
627
628 pub fn apply_pack_ddl_statements_with_columns(
635 &self,
636 statements: &[&'static str],
637 additions: &[khive_types::PackColumnAddition],
638 ) -> Result<(), SqliteError> {
639 let writer = self.pool.writer_for_schema()?;
640 writer.transaction(|conn| {
641 pack_schema::add_missing_columns(conn, additions)?;
642 for &stmt in statements {
643 conn.execute_batch(stmt)?;
644 }
645 pack_schema::validate_columns(conn, additions)?;
646 Ok(())
647 })
648 }
649
650 pub fn validate_pack_schema_columns(
653 &self,
654 additions: &[khive_types::PackColumnAddition],
655 ) -> Result<(), SqliteError> {
656 if additions.is_empty() {
657 return Ok(());
658 }
659 let reader = self.pool.reader()?;
660 pack_schema::validate_columns(reader.conn(), additions)
661 }
662
663 pub fn prepare_core_schema(&self) -> Result<u32, SqliteError> {
673 if self.is_read_only() {
674 let reader = self.pool.reader()?;
675 crate::migrations::validate_schema_is_current(reader.conn())
676 } else {
677 let latest = crate::migrations::MIGRATIONS
678 .last()
679 .map(|migration| migration.version)
680 .unwrap_or(0);
681 {
682 let reader = self.pool.reader()?;
683 let current = crate::migrations::read_schema_version(reader.conn())?;
684 if current >= latest {
685 return crate::migrations::validate_schema_is_current(reader.conn());
686 }
687 }
688 let owner = crate::stores::blob::acquire_database_gc_owner_for_path_blocking(
689 self.pool.canonical_path().map(Path::to_path_buf),
690 )
691 .map_err(|error| {
692 SqliteError::InvalidData(format!(
693 "failed to acquire database GC owner before schema preparation: {error}"
694 ))
695 })?;
696 self.run_core_migrations(&owner)
697 }
698 }
699
700 pub fn attachment_cutover_status(
702 &self,
703 ) -> Result<crate::migrations::AttachmentCutoverStatus, SqliteError> {
704 let reader = self.pool.reader()?;
705 crate::migrations::attachment_cutover_status(reader.conn())
706 }
707
708 fn require_attachment_cutover_owner(
709 &self,
710 owner: &crate::stores::blob::DatabaseGcOwnerGuard,
711 ) -> Result<(), SqliteError> {
712 let sql = self.sql();
713 let backend_path = sql.database_path();
714 if owner.database_path() != backend_path.as_deref() {
715 return Err(SqliteError::InvalidData(format!(
716 "attachment cutover GC owner targets {:?}, but this backend is {:?}",
717 owner.database_path(),
718 backend_path.as_deref()
719 )));
720 }
721 Ok(())
722 }
723
724 pub fn stage_attachment_cutover(
728 &self,
729 owner: &crate::stores::blob::DatabaseGcOwnerGuard,
730 ) -> Result<(), SqliteError> {
731 self.require_attachment_cutover_owner(owner)?;
732 if self.is_read_only() {
733 return Err(SqliteError::InvalidData(
734 "cannot stage attachment cutover on a read-only backend".into(),
735 ));
736 }
737 let _class = crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Migration);
739 let mut writer = self.pool.writer_for_attachment_cutover()?;
740 let admission = self.pool.write_admission();
741 writer.conn_mut().with_mut(|conn| {
742 crate::migrations::stage_attachment_cutover_with_admission(conn, &admission)
743 })
744 }
745
746 pub fn apply_verified_attachments(
748 &self,
749 owner: &crate::stores::blob::DatabaseGcOwnerGuard,
750 attachments: &[khive_storage::Attachment],
751 ) -> Result<(), SqliteError> {
752 self.require_attachment_cutover_owner(owner)?;
753 if self.is_read_only() {
754 return Err(SqliteError::InvalidData(
755 "cannot apply verified attachments on a read-only backend".into(),
756 ));
757 }
758 let _class = crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Migration);
759 let mut writer = self.pool.writer_for_attachment_cutover()?;
760 let admission = self.pool.write_admission();
761 writer.conn_mut().with_mut(|conn| {
762 let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
763 if let Err(error) = admission.check() {
764 let rollback = tx.rollback();
765 return Err(crate::migrations::capacity_refusal_after_rollback(
766 conn,
767 rollback,
768 error,
769 "verified attachment publication",
770 ));
771 }
772 for attachment in attachments {
773 attachment
774 .validate()
775 .map_err(|error| SqliteError::InvalidData(error.to_string()))?;
776 crate::migrations::apply_generic_verified_attachment(
777 &tx,
778 &attachment.record_uuid.to_string(),
779 attachment.substrate.as_str(),
780 &attachment.role,
781 &attachment.content_ref,
782 attachment.media_type.as_deref(),
783 attachment.size_bytes,
784 attachment.created_at,
785 )?;
786 }
787 tx.commit()?;
788 Ok(())
789 })
790 }
791
792 pub fn finalize_attachment_cutover(
795 &self,
796 owner: &crate::stores::blob::DatabaseGcOwnerGuard,
797 ) -> Result<(), SqliteError> {
798 self.require_attachment_cutover_owner(owner)?;
799 if self.is_read_only() {
800 return Err(SqliteError::InvalidData(
801 "cannot finalize attachment cutover on a read-only backend".into(),
802 ));
803 }
804 let _class = crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Migration);
805 let mut writer = self.pool.writer_for_attachment_cutover()?;
806 let admission = self.pool.write_admission();
807 writer.conn_mut().with_mut(|conn| {
808 crate::migrations::finalize_attachment_cutover_with_admission(conn, &admission)
809 })
810 }
811
812 pub fn entities(&self) -> Result<Arc<dyn khive_storage::EntityStore>, SqliteError> {
816 self.entities_for_namespace("local")
817 }
818
819 pub fn entities_for_namespace(
823 &self,
824 namespace: &str,
825 ) -> Result<Arc<dyn khive_storage::EntityStore>, SqliteError> {
826 if namespace.trim().is_empty() {
827 return Err(SqliteError::InvalidData(
828 "entities namespace must be non-empty".to_string(),
829 ));
830 }
831 self.ensure_store_schema(StoreSchemaKind::Entities)?;
832
833 Ok(Arc::new(entity::SqlEntityStore::new(
834 Arc::clone(&self.pool),
835 self.is_file_backed,
836 )))
837 }
838
839 pub fn attachments(&self) -> Result<Arc<dyn khive_storage::AttachmentStore>, SqliteError> {
846 Ok(Arc::new(attachment::SqlAttachmentStore::new(
847 Arc::clone(&self.pool),
848 self.is_file_backed,
849 )))
850 }
851
852 pub fn graph(&self) -> Result<Arc<dyn khive_storage::GraphStore>, SqliteError> {
857 self.graph_for_namespace("local")
858 }
859
860 pub fn graph_for_namespace(
862 &self,
863 namespace: &str,
864 ) -> Result<Arc<dyn khive_storage::GraphStore>, SqliteError> {
865 if namespace.trim().is_empty() {
866 return Err(SqliteError::InvalidData(
867 "graph namespace must be non-empty".to_string(),
868 ));
869 }
870 self.ensure_store_schema(StoreSchemaKind::Graph)?;
871
872 Ok(Arc::new(
873 graph::SqlGraphStore::new_scoped(
874 Arc::clone(&self.pool),
875 self.is_file_backed,
876 namespace.trim().to_string(),
877 )
878 .with_index_repair(crate::stores::index_repair::IndexRepairContext::new(
879 Arc::clone(&self.pool),
880 self.store_schemas.clone(),
881 crate::stores::index_repair::IndexReadKind::Graph,
882 )),
883 ))
884 }
885
886 fn ensure_store_schema(&self, kind: StoreSchemaKind) -> Result<(), SqliteError> {
887 if self.is_read_only()
888 || self.store_schemas[kind as usize]
889 .ready
890 .load(Ordering::Acquire)
891 {
892 return Ok(());
893 }
894 let writer = self.constructor_writer()?;
895 self.ensure_store_schema_with_writer(kind, writer.conn())
896 }
897
898 fn ensure_store_schema_with_writer(
899 &self,
900 kind: StoreSchemaKind,
901 conn: &rusqlite::Connection,
902 ) -> Result<(), SqliteError> {
903 self.store_schemas[kind as usize].ensure(conn, kind.initializer())?;
904 Ok(())
905 }
906
907 fn constructor_writer(
908 &self,
909 ) -> Result<crate::pool::PooledAutocommitWriteUnit<'_>, SqliteError> {
910 let context = khive_storage::capture_request_read_context();
911 let Some(operation) = context.store_acquisition_operation() else {
912 return self.pool.writer_for_schema()?.admit_autocommit();
913 };
914 let writer = self
915 .pool
916 .schema_writer_until_for_admitted_operation(|| {
917 context.blocking_stop_reason().is_some()
918 })?
919 .ok_or_else(|| {
920 SqliteError::RequestReadStopped(khive_storage::StorageError::Timeout {
921 operation: operation.into(),
922 })
923 })?;
924 writer.admit_autocommit()
925 }
926
927 pub fn notes(&self) -> Result<Arc<dyn khive_storage::NoteStore>, SqliteError> {
931 self.notes_for_namespace("local")
932 }
933
934 pub fn notes_for_namespace(
938 &self,
939 namespace: &str,
940 ) -> Result<Arc<dyn khive_storage::NoteStore>, SqliteError> {
941 if namespace.trim().is_empty() {
942 return Err(SqliteError::InvalidData(
943 "notes namespace must be non-empty".to_string(),
944 ));
945 }
946 if !self.is_read_only()
947 && (!self.store_schemas[StoreSchemaKind::Notes as usize]
948 .ready
949 .load(Ordering::Acquire)
950 || self.notes_seq_repair_runs.load(Ordering::Relaxed) == 0)
951 {
952 let writer = self.constructor_writer()?;
953 self.ensure_store_schema_with_writer(StoreSchemaKind::Notes, writer.conn())?;
954
955 self.repair_notes_seq_with_writer(writer.conn())?;
962 }
963
964 Ok(Arc::new(
965 note::SqlNoteStore::new(Arc::clone(&self.pool), self.is_file_backed).with_index_repair(
966 crate::stores::index_repair::IndexRepairContext::new(
967 Arc::clone(&self.pool),
968 self.store_schemas.clone(),
969 crate::stores::index_repair::IndexReadKind::Notes,
970 ),
971 ),
972 ))
973 }
974
975 pub fn notes_seq_repair_run_count(&self) -> usize {
980 self.notes_seq_repair_runs.load(Ordering::Relaxed)
981 }
982
983 pub fn events(&self) -> Result<Arc<dyn khive_storage::EventStore>, SqliteError> {
988 self.events_for_namespace("local")
989 }
990
991 pub fn events_for_namespace(
993 &self,
994 namespace: &str,
995 ) -> Result<Arc<dyn khive_storage::EventStore>, SqliteError> {
996 if namespace.trim().is_empty() {
997 return Err(SqliteError::InvalidData(
998 "events namespace must be non-empty".to_string(),
999 ));
1000 }
1001 self.ensure_store_schema(StoreSchemaKind::Events)?;
1002
1003 Ok(Arc::new(event::SqlEventStore::new_scoped(
1004 Arc::clone(&self.pool),
1005 self.is_file_backed,
1006 namespace.trim().to_string(),
1007 )))
1008 }
1009
1010 pub fn agents(&self) -> Result<Arc<dyn khive_storage::AgentStore>, SqliteError> {
1015 self.ensure_store_schema(StoreSchemaKind::Agents)?;
1016
1017 Ok(Arc::new(agents::SqlAgentStore::new(
1018 Arc::clone(&self.pool),
1019 self.is_file_backed,
1020 )))
1021 }
1022
1023 pub fn vectors(
1029 &self,
1030 model_key: &str,
1031 embedding_model: &str,
1032 dimensions: usize,
1033 ) -> Result<Arc<dyn khive_storage::VectorStore>, SqliteError> {
1034 self.vectors_for_namespace(model_key, embedding_model, dimensions, "local")
1035 }
1036
1037 pub fn vectors_for_namespace(
1047 &self,
1048 model_key: &str,
1049 embedding_model: &str,
1050 dimensions: usize,
1051 namespace: &str,
1052 ) -> Result<Arc<dyn khive_storage::VectorStore>, SqliteError> {
1053 validate_vector_model_key(model_key)?;
1054 if namespace.trim().is_empty() {
1055 return Err(SqliteError::InvalidData(
1056 "vector store namespace must be non-empty".to_string(),
1057 ));
1058 }
1059 self.ensure_vector_tables(&[(model_key, dimensions)])?;
1060 Ok(Arc::new(vectors::SqliteVecStore::new(
1061 Arc::clone(&self.pool),
1062 self.is_file_backed,
1063 model_key.to_string(),
1064 embedding_model.to_string(),
1065 dimensions,
1066 namespace.trim().to_string(),
1067 )?))
1068 }
1069
1070 pub fn ensure_vector_tables(&self, models: &[(&str, usize)]) -> Result<(), SqliteError> {
1079 for (model_key, _) in models {
1080 validate_vector_model_key(model_key)?;
1081 }
1082 if models.is_empty() {
1083 return Ok(());
1084 }
1085
1086 crate::extension::ensure_extensions_loaded();
1088
1089 if self.is_read_only() {
1094 let reader = self.pool.reader()?;
1098 for (model_key, _) in models {
1099 let table = format!("vec_{model_key}");
1100 if !sqlite_table_exists(reader.conn(), &table)? {
1101 return Err(SqliteError::InvalidData(format!(
1102 "read-only database has no vector table '{table}'; create and populate it in \
1103 a writable copy before opening the snapshot"
1104 )));
1105 }
1106 validate_vector_table_columns(reader.conn(), &table)?;
1107 }
1108 return Ok(());
1109 }
1110
1111 let pending = self.unprepared_vector_tables(models);
1112 if pending.is_empty() {
1113 return Ok(());
1114 }
1115 let writer = self.constructor_writer()?;
1116 let pending = self.unprepared_vector_tables(&pending);
1119 if pending.is_empty() {
1120 return Ok(());
1121 }
1122
1123 for (model_key, _) in &pending {
1127 let table = format!("vec_{model_key}");
1128 if sqlite_table_exists(writer.conn(), &table)? {
1134 validate_vector_table_columns(writer.conn(), &table)?;
1135 }
1136 }
1137
1138 writer
1147 .conn()
1148 .execute_batch(crate::migrations::EMBEDDING_MODELS_DDL)?;
1149
1150 writer
1154 .conn()
1155 .execute_batch(crate::migrations::ANN_WRITE_LOG_DDL)?;
1156 writer
1157 .conn()
1158 .execute_batch(crate::migrations::ANN_WRITE_LOG_MODEL_SEQ_INDEX_DDL)?;
1159 writer
1160 .conn()
1161 .execute_batch(crate::migrations::ANN_CONSUMER_PENDING_DDL)?;
1162 for (model_key, dimensions) in &pending {
1164 let ddl = format!(
1165 "CREATE VIRTUAL TABLE IF NOT EXISTS vec_{} USING vec0(\
1166 subject_id TEXT PRIMARY KEY, \
1167 namespace TEXT NOT NULL, \
1168 kind TEXT NOT NULL, \
1169 field TEXT NOT NULL, \
1170 embedding_model TEXT NOT NULL, \
1171 embedding float[{}] distance_metric=cosine\
1172 )",
1173 model_key, dimensions
1174 );
1175 writer.conn().execute_batch(&ddl)?;
1176 }
1177 self.vector_tables_ready.lock().extend(
1180 pending
1181 .iter()
1182 .map(|(model_key, _)| (*model_key).to_string()),
1183 );
1184 Ok(())
1185 }
1186
1187 fn unprepared_vector_tables<'a>(&self, models: &[(&'a str, usize)]) -> Vec<(&'a str, usize)> {
1189 let ready = self.vector_tables_ready.lock();
1190 models
1191 .iter()
1192 .filter(|(model_key, _)| !ready.contains(*model_key))
1193 .copied()
1194 .collect()
1195 }
1196
1197 pub fn register_embedding_model(
1202 &self,
1203 engine_name: &str,
1204 model_id: &str,
1205 key_version: &str,
1206 dimensions: u32,
1207 ) -> Result<(), SqliteError> {
1208 let writer = self.pool.writer_for_schema()?.admit_autocommit()?;
1209 writer
1210 .conn()
1211 .execute_batch(crate::migrations::EMBEDDING_MODELS_DDL)
1212 .map_err(|error| {
1213 SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
1214 })?;
1215
1216 let now = chrono::Utc::now().timestamp_micros();
1217 let canonical_key =
1218 format!("{engine_name}:{model_id}:{key_version}:{dimensions}").into_bytes();
1219 let id = uuid::Uuid::new_v4();
1220 writer
1221 .conn()
1222 .execute(
1223 "INSERT INTO _embedding_models \
1224 (id, engine_name, model_id, key_version, dim, output_dim, status, \
1225 activated_at, superseded_at, superseded_by, canonical_key, created_at) \
1226 VALUES (?1, ?2, ?3, ?4, ?5, NULL, 'active', ?6, NULL, NULL, ?7, ?8) \
1227 ON CONFLICT(canonical_key) DO UPDATE SET \
1228 status = 'active', \
1229 activated_at = COALESCE(_embedding_models.activated_at, excluded.activated_at)",
1230 rusqlite::params![
1231 id.as_bytes().as_slice(),
1232 engine_name,
1233 model_id,
1234 key_version,
1235 dimensions as i64,
1236 now,
1237 canonical_key,
1238 now,
1239 ],
1240 )
1241 .map_err(|error| {
1242 SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
1243 })?;
1244 Ok(())
1245 }
1246
1247 pub fn sparse(
1251 &self,
1252 model_key: &str,
1253 ) -> Result<Arc<dyn khive_storage::SparseStore>, SqliteError> {
1254 self.sparse_for_namespace(model_key, "local")
1255 }
1256
1257 #[cfg(test)]
1261 pub(crate) fn forget_proven_text_tables_for_test(&self) {
1262 self.text_tables_ready.lock().clear();
1263 }
1264
1265 fn ensure_sparse_table(&self, model_key: &str) -> Result<(), SqliteError> {
1271 if self.sparse_tables_ready.lock().contains(model_key) {
1272 return Ok(());
1273 }
1274 let writer = self.pool.writer_for_schema()?.admit_autocommit()?;
1275 if !self.sparse_tables_ready.lock().contains(model_key) {
1276 sparse::ensure_sparse_schema(writer.conn(), model_key)
1277 .map_err(SqliteError::Rusqlite)?;
1278 self.sparse_tables_ready
1279 .lock()
1280 .insert(model_key.to_string());
1281 }
1282 Ok(())
1283 }
1284
1285 pub fn sparse_for_namespace(
1289 &self,
1290 model_key: &str,
1291 namespace: &str,
1292 ) -> Result<Arc<dyn khive_storage::SparseStore>, SqliteError> {
1293 if model_key.is_empty()
1294 || !model_key
1295 .chars()
1296 .all(|c| c.is_ascii_alphanumeric() || c == '_')
1297 {
1298 return Err(SqliteError::InvalidData(format!(
1299 "invalid model_key '{}': must be non-empty and contain only alphanumeric/underscore characters",
1300 model_key
1301 )));
1302 }
1303 if namespace.trim().is_empty() {
1304 return Err(SqliteError::InvalidData(
1305 "sparse store namespace must be non-empty".to_string(),
1306 ));
1307 }
1308
1309 if self.is_read_only() {
1310 let table = format!("sparse_{model_key}");
1311 let reader = self.pool.reader()?;
1312 if !sqlite_table_exists(reader.conn(), &table)? {
1313 return Err(SqliteError::InvalidData(format!(
1314 "read-only database has no sparse table '{table}'; create and populate it in \
1315 a writable copy before opening the snapshot"
1316 )));
1317 }
1318 } else {
1319 self.ensure_sparse_table(model_key)?;
1320 }
1321
1322 Ok(Arc::new(sparse::SqliteSparseStore::new(
1323 Arc::clone(&self.pool),
1324 self.is_file_backed,
1325 model_key.to_string(),
1326 namespace.trim().to_string(),
1327 )?))
1328 }
1329
1330 pub fn text(&self, table_key: &str) -> Result<Arc<dyn khive_storage::TextSearch>, SqliteError> {
1337 self.text_with_tokenizer(table_key, "trigram")
1338 }
1339
1340 pub fn text_with_tokenizer(
1348 &self,
1349 table_key: &str,
1350 tokenizer: &str,
1351 ) -> Result<Arc<dyn khive_storage::TextSearch>, SqliteError> {
1352 if table_key.is_empty()
1353 || !table_key
1354 .chars()
1355 .all(|c| c.is_ascii_alphanumeric() || c == '_')
1356 {
1357 return Err(SqliteError::InvalidData(format!(
1358 "invalid table_key '{}': must be non-empty and contain only \
1359 alphanumeric/underscore characters",
1360 table_key
1361 )));
1362 }
1363 if table_key.ends_with("_rowids") || table_key.ends_with("_rowids_state") {
1373 return Err(SqliteError::InvalidData(format!(
1374 "invalid table_key '{}': must not end in '_rowids' or '_rowids_state' — those \
1375 suffixes are reserved for a text table's own rowid-map sidecar and its \
1376 completion-marker state table (see text::rowid_map_table, \
1377 text::rowid_map_state_table)",
1378 table_key
1379 )));
1380 }
1381 if tokenizer.is_empty()
1382 || !tokenizer
1383 .chars()
1384 .all(|c| c.is_ascii_alphanumeric() || c == '_')
1385 {
1386 return Err(SqliteError::InvalidData(format!(
1387 "invalid tokenizer '{}': must be non-empty and contain only \
1388 alphanumeric/underscore characters",
1389 tokenizer
1390 )));
1391 }
1392
1393 let ddl = format!(
1394 "CREATE VIRTUAL TABLE IF NOT EXISTS fts_{} USING fts5(\
1395 subject_id UNINDEXED, \
1396 kind UNINDEXED, \
1397 title, \
1398 body, \
1399 tags UNINDEXED, \
1400 namespace UNINDEXED, \
1401 metadata UNINDEXED, \
1402 updated_at UNINDEXED, \
1403 record_kind, \
1404 tokenize = '{}'\
1405 )",
1406 table_key, tokenizer
1407 );
1408 let table = format!("fts_{table_key}");
1409 if self.is_read_only() {
1410 let reader = self.pool.reader()?;
1411 if !sqlite_table_exists(reader.conn(), &table)? {
1412 return Err(SqliteError::InvalidData(format!(
1413 "read-only database has no text-search table '{table}'; create and populate \
1414 it in a writable copy before opening the snapshot"
1415 )));
1416 }
1417 let map = text::rowid_map_table(&table);
1431 let map_exists = sqlite_table_exists(reader.conn(), &map)?;
1432 let marker_present = if map_exists {
1433 let state = text::rowid_map_state_table(&table);
1434 sqlite_table_exists(reader.conn(), &state)?
1435 && reader.conn().query_row(
1436 &format!(
1437 "SELECT EXISTS(SELECT 1 FROM {state} WHERE key = 'backfill' AND value = ?1)"
1438 ),
1439 rusqlite::params![text::ROWID_MAP_BACKFILL_COMPLETE],
1440 |row| row.get(0),
1441 )?
1442 } else {
1443 false
1444 };
1445 if !map_exists || !marker_present {
1446 warn_scan_fallback_once(&table);
1447 return Ok(Arc::new(text::Fts5TextSearch::new_scan_fallback(
1448 Arc::clone(&self.pool),
1449 self.is_file_backed,
1450 table_key.to_string(),
1451 )));
1452 }
1453 } else if !self.text_tables_ready.lock().contains(&table) {
1454 let writer = self.pool.writer_for_schema()?.admit_autocommit()?;
1455 if !self.text_tables_ready.lock().contains(&table) {
1458 writer.conn().execute_batch(&ddl)?;
1459 writer.conn().execute_batch(&text::rowid_map_ddl(&table))?;
1460 ensure_fts_rowid_map_backfilled(
1461 writer.conn(),
1462 &table,
1463 &self.pool.write_admission(),
1464 )?;
1465 self.text_tables_ready.lock().insert(table.clone());
1468 }
1469 }
1470
1471 Ok(Arc::new(text::Fts5TextSearch::new(
1472 Arc::clone(&self.pool),
1473 self.is_file_backed,
1474 table_key.to_string(),
1475 )))
1476 }
1477
1478 pub fn blob_store(
1487 &self,
1488 config_root: Option<&Path>,
1489 floor_bytes: Option<u64>,
1490 ) -> Result<Arc<dyn khive_storage::BlobStore>, SqliteError> {
1491 Ok(Arc::new(self.fs_blob_store(config_root, floor_bytes)?))
1492 }
1493
1494 pub(crate) fn fs_blob_store(
1497 &self,
1498 config_root: Option<&Path>,
1499 floor_bytes: Option<u64>,
1500 ) -> Result<blob::FsBlobStore, SqliteError> {
1501 let root = blob::resolve_blob_root(self.data_dir().as_deref(), config_root)?;
1502 let floor = blob::FsBlobStore::resolve_floor(&root, floor_bytes);
1503 blob::FsBlobStore::new(root, floor)
1504 }
1505
1506 pub fn blob_store_read_only(
1511 &self,
1512 config_root: Option<&Path>,
1513 floor_bytes: Option<u64>,
1514 ) -> Result<Arc<dyn khive_storage::BlobStore>, SqliteError> {
1515 let root = blob::resolve_blob_root(self.data_dir().as_deref(), config_root)?;
1516 let floor = blob::FsBlobStore::resolve_floor(&root, floor_bytes);
1517 Ok(Arc::new(blob::FsBlobStore::open_existing(root, floor)?))
1518 }
1519
1520 pub fn is_file_backed(&self) -> bool {
1522 self.is_file_backed
1523 }
1524
1525 pub fn is_read_only(&self) -> bool {
1528 self.pool.config().read_only
1529 }
1530
1531 pub fn data_dir(&self) -> Option<std::path::PathBuf> {
1534 self.path.as_ref()?.parent().map(|p| p.to_path_buf())
1535 }
1536
1537 pub fn ann_root(&self) -> Option<std::path::PathBuf> {
1545 ann_root_for(self.path.as_ref()?)
1546 }
1547
1548 pub fn pool(&self) -> &ConnectionPool {
1550 &self.pool
1551 }
1552
1553 pub fn database_owner_identity(
1556 &self,
1557 ) -> Result<DatabaseOwnerIdentity, DatabaseOwnerIdentityError> {
1558 self.pool.database_owner_identity()
1559 }
1560
1561 pub fn verify_database_owner(
1563 &self,
1564 expected: &DatabaseOwnerIdentity,
1565 ) -> Result<(), DatabaseOwnerIdentityError> {
1566 self.pool.verify_database_owner(expected)
1567 }
1568
1569 pub fn pool_arc(&self) -> Arc<ConnectionPool> {
1571 Arc::clone(&self.pool)
1572 }
1573}
1574
1575fn ann_root_for(path: &std::path::Path) -> Option<std::path::PathBuf> {
1580 let mut file = path.file_name()?.to_os_string();
1581 file.push(".ann");
1582 path.parent().map(|p| p.join(file))
1583}
1584
1585#[cfg(test)]
1586#[path = "backend/store_accessor_tests.rs"]
1587mod store_accessor_tests;
1588
1589#[cfg(test)]
1590#[path = "backend/store_accessor_index_tests.rs"]
1591mod store_accessor_index_tests;
1592
1593#[cfg(test)]
1594#[path = "backend/schema_barrier_tests.rs"]
1595mod schema_barrier_tests;
1596
1597#[cfg(test)]
1598#[path = "backend_tests.rs"]
1599mod tests;
1600
1601#[cfg(test)]
1602#[path = "backend_admission_tests.rs"]
1603mod admission_tests;
1604
1605#[cfg(test)]
1606mod live_readonly_tests;