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;
26
27#[cfg(test)]
28#[path = "backend/filter_builder_tests.rs"]
29mod filter_builder_tests;
30
31mod namespace_listing;
32pub use namespace_listing::NamespaceLiveness;
33
34#[cfg(test)]
35#[path = "backend/memory_visibility_tests.rs"]
36mod memory_visibility_tests;
37
38#[cfg(any(unix, windows))]
39mod claimed_file_identity;
40
41fn sqlite_table_exists(conn: &rusqlite::Connection, table: &str) -> Result<bool, SqliteError> {
42 conn.query_row(
43 "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1",
44 rusqlite::params![table],
45 |row| row.get::<_, i64>(0),
46 )
47 .optional()
48 .map(|row| row.is_some())
49 .map_err(SqliteError::Rusqlite)
50}
51
52fn ensure_fts_rowid_map_backfilled(
112 conn: &rusqlite::Connection,
113 table: &str,
114 admission: &crate::pool::WriteAdmission,
115) -> Result<bool, SqliteError> {
116 let map = text::rowid_map_table(table);
117 let state = text::rowid_map_state_table(table);
118 let already_backfilled: bool = conn.query_row(
119 &format!("SELECT EXISTS(SELECT 1 FROM {state} WHERE key = 'backfill' AND value = ?1)"),
120 rusqlite::params![text::ROWID_MAP_BACKFILL_COMPLETE],
121 |row| row.get(0),
122 )?;
123 if already_backfilled {
124 return Ok(true);
125 }
126 let fts_has_a_row: bool = conn.query_row(
127 &format!("SELECT EXISTS(SELECT 1 FROM {table} LIMIT 1)"),
128 [],
129 |row| row.get(0),
130 )?;
131 if !fts_has_a_row {
132 return Ok(false);
133 }
134
135 conn.execute_batch("BEGIN IMMEDIATE")?;
136 if let Err(error) = admission.check() {
137 return Err(crate::migrations::capacity_refusal_after_rollback(
138 conn,
139 conn.execute_batch("ROLLBACK"),
140 error,
141 "FTS rowid-map backfill",
142 ));
143 }
144 let result: Result<(), SqliteError> = (|| {
145 conn.execute_batch(&format!(
146 "DELETE FROM {map} WHERE NOT EXISTS ( \
147 SELECT 1 FROM {table} \
148 WHERE {table}.rowid = {map}.rowid \
149 AND {table}.namespace = {map}.namespace \
150 AND {table}.subject_id = {map}.subject_id \
151 )"
152 ))?;
153 conn.execute_batch(&format!(
154 "INSERT OR REPLACE INTO {map} (namespace, subject_id, rowid) \
155 SELECT namespace, subject_id, rowid FROM {table} \
156 WHERE namespace IS NOT NULL AND subject_id IS NOT NULL \
157 ORDER BY updated_at ASC, rowid ASC"
158 ))?;
159 conn.execute_batch(&format!(
160 "DELETE FROM {table} \
161 WHERE namespace IS NOT NULL AND subject_id IS NOT NULL \
162 AND rowid NOT IN (SELECT rowid FROM {map})"
163 ))?;
164 conn.execute(
165 &format!("INSERT OR REPLACE INTO {state} (key, value) VALUES ('backfill', ?1)"),
166 rusqlite::params![text::ROWID_MAP_BACKFILL_COMPLETE],
167 )?;
168 Ok(())
169 })();
170
171 match result {
172 Ok(()) => {
173 conn.execute_batch("COMMIT")?;
174 Ok(true)
175 }
176 Err(e) => {
177 let _ = conn.execute_batch("ROLLBACK");
178 Err(e)
179 }
180 }
181}
182
183fn warn_scan_fallback_once(table: &str) {
189 static WARNED: std::sync::Once = std::sync::Once::new();
190 WARNED.call_once(|| {
191 tracing::warn!(
192 table,
193 "opened a read-only text-search table with no rowid-map sidecar, or with a sidecar \
194 that has never proven a completed backfill (no durable completion marker); a \
195 read-only connection cannot create, backfill, or reconcile the map itself, so this \
196 falls back to pre-map namespace/subject_id scan predicates for get/delete on this \
197 table rather than trusting a map that might be partial"
198 );
199 });
200}
201
202fn validate_vector_model_key(model_key: &str) -> Result<(), SqliteError> {
203 if model_key.is_empty()
204 || !model_key
205 .chars()
206 .all(|c| c.is_ascii_alphanumeric() || c == '_')
207 {
208 return Err(SqliteError::InvalidData(format!(
209 "invalid model_key '{}': must be non-empty and contain only \
210 alphanumeric/underscore characters",
211 model_key
212 )));
213 }
214 Ok(())
215}
216
217fn validate_vector_table_columns(
218 conn: &rusqlite::Connection,
219 table: &str,
220) -> Result<(), SqliteError> {
221 let pragma = format!("PRAGMA table_xinfo({table})");
222 let mut stmt = conn.prepare(&pragma)?;
223 let mut rows = stmt.query([])?;
224 let mut has_field = false;
225 let mut has_embedding_model = false;
226 while let Some(row) = rows.next()? {
227 let name: String = row.get(1)?;
228 if name == "field" {
229 has_field = true;
230 }
231 if name == "embedding_model" {
232 has_embedding_model = true;
233 }
234 }
235 if !has_field || !has_embedding_model {
236 return Err(SqliteError::InvalidData(format!(
237 "vec0 table '{table}' is missing required column(s) (field={has_field}, \
238 embedding_model={has_embedding_model}); this is a pre-v0.2.8 vector schema and is \
239 not supported — recreate the database"
240 )));
241 }
242 Ok(())
243}
244
245#[derive(Clone, Copy, Debug)]
246pub(crate) enum StoreSchemaKind {
247 Entities,
248 Graph,
249 Notes,
250 Events,
251 Agents,
252}
253
254impl StoreSchemaKind {
255 fn initializer(self) -> fn(&rusqlite::Connection) -> Result<(), rusqlite::Error> {
256 match self {
257 Self::Entities => entity::ensure_entities_schema,
258 Self::Graph => graph::ensure_graph_schema,
259 Self::Notes => note::ensure_notes_schema,
260 Self::Events => event::ensure_events_schema,
261 Self::Agents => agents::ensure_agents_schema,
262 }
263 }
264}
265
266#[derive(Default)]
267pub(crate) struct StoreSchemaGate {
268 pub(crate) ready: AtomicBool,
269 #[cfg(test)]
270 pub(crate) attempts: AtomicUsize,
271}
272
273impl StoreSchemaGate {
274 pub(crate) fn ensure(
275 &self,
276 conn: &rusqlite::Connection,
277 ensure: fn(&rusqlite::Connection) -> Result<(), rusqlite::Error>,
278 ) -> Result<(), rusqlite::Error> {
279 if self.ready.load(Ordering::Acquire) {
282 return Ok(());
283 }
284 #[cfg(test)]
285 self.attempts.fetch_add(1, Ordering::Relaxed);
286 ensure(conn)?;
287 self.ready.store(true, Ordering::Release);
288 Ok(())
289 }
290}
291
292pub struct StorageBackend {
298 pool: Arc<ConnectionPool>,
299 is_file_backed: bool,
300 path: Option<std::path::PathBuf>,
301 vector_tables_ready: parking_lot::Mutex<std::collections::HashSet<String>>,
309 text_tables_ready: parking_lot::Mutex<std::collections::HashSet<String>>,
317 notes_seq_repair_runs: AtomicUsize,
324 store_schemas: [Arc<StoreSchemaGate>; 5],
325}
326
327impl StorageBackend {
328 pub fn sqlite(path: impl AsRef<Path>) -> Result<Self, SqliteError> {
342 Self::sqlite_with_pool_config(path, PoolConfig::default(), None)
343 }
344
345 #[cfg(any(test, feature = "test-support"))]
347 pub fn sqlite_for_test(path: impl AsRef<Path>) -> Result<Self, SqliteError> {
348 Self::sqlite_with_pool_config(path, PoolConfig::for_test(), None)
349 }
350
351 #[cfg(any(test, feature = "test-support"))]
353 pub fn sqlite_for_test_with_journal_mode(
354 path: impl AsRef<Path>,
355 wal_mode: bool,
356 busy_timeout: std::time::Duration,
357 ) -> Result<Self, SqliteError> {
358 Self::sqlite_with_pool_config(
359 path,
360 PoolConfig {
361 wal_mode,
362 busy_timeout,
363 write_queue_enabled: Some(true),
364 ..PoolConfig::for_test()
365 },
366 None,
367 )
368 }
369
370 #[cfg(any(test, feature = "test-support"))]
375 pub fn sqlite_for_test_with_journal_mode_in(
376 path: impl AsRef<Path>,
377 wal_mode: bool,
378 busy_timeout: std::time::Duration,
379 volume_lock_dir: std::path::PathBuf,
380 ) -> Result<Self, SqliteError> {
381 Self::sqlite_with_pool_config(
382 path,
383 PoolConfig {
384 wal_mode,
385 busy_timeout,
386 write_queue_enabled: Some(true),
387 volume_lock_dir: Some(volume_lock_dir),
388 ..PoolConfig::for_test()
389 },
390 None,
391 )
392 }
393
394 pub fn sqlite_with_max_readers(
398 path: impl AsRef<Path>,
399 max_readers: Option<usize>,
400 ) -> Result<Self, SqliteError> {
401 Self::sqlite_with_pool_config(path, PoolConfig::default(), max_readers)
402 }
403
404 pub fn sqlite_with_max_readers_and_wal_ceiling(
408 path: impl AsRef<Path>,
409 max_readers: Option<usize>,
410 wal_ceiling: WalCeilingPolicy,
411 ) -> Result<Self, SqliteError> {
412 Self::sqlite_with_pool_config(
413 path,
414 PoolConfig {
415 wal_ceiling,
416 ..PoolConfig::default()
417 },
418 max_readers,
419 )
420 }
421
422 pub(crate) fn sqlite_with_pool_config(
423 path: impl AsRef<Path>,
424 pool_config: PoolConfig,
425 max_readers: Option<usize>,
426 ) -> Result<Self, SqliteError> {
427 crate::extension::ensure_extensions_loaded();
428 let resolved = path.as_ref().to_path_buf();
429 let read_only =
430 std::fs::metadata(&resolved).is_ok_and(|metadata| metadata.permissions().readonly());
431 let mut config = PoolConfig {
432 path: Some(resolved.clone()),
433 read_only,
434 ..pool_config
435 };
436 if let Some(max_readers) = max_readers {
437 config.max_readers = max_readers;
438 }
439 if read_only {
440 config.write_queue_enabled = Some(false);
441 }
442 let pool = ConnectionPool::new(config)?;
443 Ok(Self {
444 pool: Arc::new(pool),
445 is_file_backed: true,
446 path: Some(resolved),
447 vector_tables_ready: Default::default(),
448 text_tables_ready: Default::default(),
449 notes_seq_repair_runs: AtomicUsize::new(0),
450 store_schemas: std::array::from_fn(|_| Arc::new(StoreSchemaGate::default())),
451 })
452 }
453
454 pub fn sqlite_read_only(path: impl AsRef<Path>) -> Result<Self, SqliteError> {
465 Self::sqlite_read_only_with_pool_config(path, PoolConfig::default(), None)
466 }
467
468 #[cfg(any(test, feature = "test-support"))]
470 pub fn sqlite_read_only_for_test(path: impl AsRef<Path>) -> Result<Self, SqliteError> {
471 Self::sqlite_read_only_with_pool_config(path, PoolConfig::for_test(), None)
472 }
473
474 pub fn sqlite_read_only_with_max_readers(
476 path: impl AsRef<Path>,
477 max_readers: Option<usize>,
478 ) -> Result<Self, SqliteError> {
479 Self::sqlite_read_only_with_pool_config(path, PoolConfig::default(), max_readers)
480 }
481
482 pub fn sqlite_read_only_with_max_readers_and_wal_ceiling(
485 path: impl AsRef<Path>,
486 max_readers: Option<usize>,
487 wal_ceiling: WalCeilingPolicy,
488 ) -> Result<Self, SqliteError> {
489 Self::sqlite_read_only_with_pool_config(
490 path,
491 PoolConfig {
492 wal_ceiling,
493 ..PoolConfig::default()
494 },
495 max_readers,
496 )
497 }
498
499 pub fn sqlite_read_only_live_with_max_readers_and_wal_ceiling(
504 path: impl AsRef<Path>,
505 max_readers: Option<usize>,
506 wal_ceiling: WalCeilingPolicy,
507 ) -> Result<Self, SqliteError> {
508 Self::sqlite_read_only_with_pool_constructor(
509 path,
510 PoolConfig {
511 wal_ceiling,
512 ..PoolConfig::default()
513 },
514 max_readers,
515 ConnectionPool::new_read_only_live,
516 )
517 }
518
519 fn sqlite_read_only_with_pool_config(
520 path: impl AsRef<Path>,
521 pool_config: PoolConfig,
522 max_readers: Option<usize>,
523 ) -> Result<Self, SqliteError> {
524 Self::sqlite_read_only_with_pool_constructor(
525 path,
526 pool_config,
527 max_readers,
528 ConnectionPool::new,
529 )
530 }
531
532 fn sqlite_read_only_with_pool_constructor(
533 path: impl AsRef<Path>,
534 pool_config: PoolConfig,
535 max_readers: Option<usize>,
536 open_pool: fn(PoolConfig) -> Result<ConnectionPool, SqliteError>,
537 ) -> Result<Self, SqliteError> {
538 crate::extension::ensure_extensions_loaded();
539 let resolved = path.as_ref().to_path_buf();
540 let mut config = PoolConfig {
541 path: Some(resolved.clone()),
542 read_only: true,
543 write_queue_enabled: Some(false),
544 ..pool_config
545 };
546 if let Some(max_readers) = max_readers {
547 config.max_readers = max_readers;
548 }
549 let pool = open_pool(config)?;
555 Ok(Self {
556 pool: Arc::new(pool),
557 is_file_backed: true,
558 path: Some(resolved),
559 vector_tables_ready: Default::default(),
560 text_tables_ready: Default::default(),
561 notes_seq_repair_runs: AtomicUsize::new(0),
562 store_schemas: std::array::from_fn(|_| Arc::new(StoreSchemaGate::default())),
563 })
564 }
565
566 pub fn memory() -> Result<Self, SqliteError> {
572 crate::extension::ensure_extensions_loaded();
573 let config = PoolConfig {
574 path: None,
575 ..PoolConfig::default()
576 };
577 let pool = ConnectionPool::new(config)?;
578 Ok(Self {
579 pool: Arc::new(pool),
580 is_file_backed: false,
581 path: None,
582 vector_tables_ready: Default::default(),
583 text_tables_ready: Default::default(),
584 notes_seq_repair_runs: AtomicUsize::new(0),
585 store_schemas: std::array::from_fn(|_| Arc::new(StoreSchemaGate::default())),
586 })
587 }
588
589 pub fn apply_schema(
596 &self,
597 plan: &crate::migrations::ServiceSchemaPlan,
598 ) -> Result<(), SqliteError> {
599 let admission = self.pool.write_admission();
600 crate::migrations::apply_schema_plan_with_admission(
601 &mut self.pool.migration_transactions(),
602 plan,
603 &admission,
604 )
605 }
606
607 pub fn apply_pack_ddl_statements(
623 &self,
624 statements: &[&'static str],
625 ) -> Result<(), SqliteError> {
626 self.apply_pack_ddl_statements_with_columns(statements, &[])
627 }
628
629 pub fn apply_pack_ddl_statements_with_columns(
636 &self,
637 statements: &[&'static str],
638 additions: &[khive_types::PackColumnAddition],
639 ) -> Result<(), SqliteError> {
640 let writer = self.pool.writer()?;
641 writer.transaction(|conn| {
642 pack_schema::add_missing_columns(conn, additions)?;
643 for &stmt in statements {
644 conn.execute_batch(stmt)?;
645 }
646 pack_schema::validate_columns(conn, additions)?;
647 Ok(())
648 })
649 }
650
651 pub fn validate_pack_schema_columns(
654 &self,
655 additions: &[khive_types::PackColumnAddition],
656 ) -> Result<(), SqliteError> {
657 if additions.is_empty() {
658 return Ok(());
659 }
660 let reader = self.pool.reader()?;
661 pack_schema::validate_columns(reader.conn(), additions)
662 }
663
664 pub fn prepare_core_schema(&self) -> Result<u32, SqliteError> {
674 if self.is_read_only() {
675 let reader = self.pool.reader()?;
676 crate::migrations::validate_schema_is_current(reader.conn())
677 } else {
678 let latest = crate::migrations::MIGRATIONS
679 .last()
680 .map(|migration| migration.version)
681 .unwrap_or(0);
682 {
683 let reader = self.pool.reader()?;
684 let current = crate::migrations::read_schema_version(reader.conn())?;
685 if current >= latest {
686 return crate::migrations::validate_schema_is_current(reader.conn());
687 }
688 }
689 let owner = crate::stores::blob::acquire_database_gc_owner_for_path_blocking(
690 self.pool.canonical_path().map(Path::to_path_buf),
691 )
692 .map_err(|error| {
693 SqliteError::InvalidData(format!(
694 "failed to acquire database GC owner before schema preparation: {error}"
695 ))
696 })?;
697 self.run_core_migrations(&owner)
698 }
699 }
700
701 pub fn attachment_cutover_status(
703 &self,
704 ) -> Result<crate::migrations::AttachmentCutoverStatus, SqliteError> {
705 let reader = self.pool.reader()?;
706 crate::migrations::attachment_cutover_status(reader.conn())
707 }
708
709 fn require_attachment_cutover_owner(
710 &self,
711 owner: &crate::stores::blob::DatabaseGcOwnerGuard,
712 ) -> Result<(), SqliteError> {
713 let sql = self.sql();
714 let backend_path = sql.database_path();
715 if owner.database_path() != backend_path.as_deref() {
716 return Err(SqliteError::InvalidData(format!(
717 "attachment cutover GC owner targets {:?}, but this backend is {:?}",
718 owner.database_path(),
719 backend_path.as_deref()
720 )));
721 }
722 Ok(())
723 }
724
725 pub fn stage_attachment_cutover(
729 &self,
730 owner: &crate::stores::blob::DatabaseGcOwnerGuard,
731 ) -> Result<(), SqliteError> {
732 self.require_attachment_cutover_owner(owner)?;
733 if self.is_read_only() {
734 return Err(SqliteError::InvalidData(
735 "cannot stage attachment cutover on a read-only backend".into(),
736 ));
737 }
738 let mut writer = self.pool.writer()?;
739 let admission = self.pool.write_admission();
740 writer.conn_mut().with_mut(|conn| {
741 crate::migrations::stage_attachment_cutover_with_admission(conn, &admission)
742 })
743 }
744
745 pub fn apply_verified_attachments(
747 &self,
748 owner: &crate::stores::blob::DatabaseGcOwnerGuard,
749 attachments: &[khive_storage::Attachment],
750 ) -> Result<(), SqliteError> {
751 self.require_attachment_cutover_owner(owner)?;
752 if self.is_read_only() {
753 return Err(SqliteError::InvalidData(
754 "cannot apply verified attachments on a read-only backend".into(),
755 ));
756 }
757 let mut writer = self.pool.writer()?;
758 let admission = self.pool.write_admission();
759 writer.conn_mut().with_mut(|conn| {
760 let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
761 if let Err(error) = admission.check() {
762 let rollback = tx.rollback();
763 return Err(crate::migrations::capacity_refusal_after_rollback(
764 conn,
765 rollback,
766 error,
767 "verified attachment publication",
768 ));
769 }
770 for attachment in attachments {
771 attachment
772 .validate()
773 .map_err(|error| SqliteError::InvalidData(error.to_string()))?;
774 crate::migrations::apply_generic_verified_attachment(
775 &tx,
776 &attachment.record_uuid.to_string(),
777 attachment.substrate.as_str(),
778 &attachment.role,
779 &attachment.content_ref,
780 attachment.media_type.as_deref(),
781 attachment.size_bytes,
782 attachment.created_at,
783 )?;
784 }
785 tx.commit()?;
786 Ok(())
787 })
788 }
789
790 pub fn finalize_attachment_cutover(
793 &self,
794 owner: &crate::stores::blob::DatabaseGcOwnerGuard,
795 ) -> Result<(), SqliteError> {
796 self.require_attachment_cutover_owner(owner)?;
797 if self.is_read_only() {
798 return Err(SqliteError::InvalidData(
799 "cannot finalize attachment cutover on a read-only backend".into(),
800 ));
801 }
802 let mut writer = self.pool.writer()?;
803 let admission = self.pool.write_admission();
804 writer.conn_mut().with_mut(|conn| {
805 crate::migrations::finalize_attachment_cutover_with_admission(conn, &admission)
806 })
807 }
808
809 pub fn entities(&self) -> Result<Arc<dyn khive_storage::EntityStore>, SqliteError> {
813 self.entities_for_namespace("local")
814 }
815
816 pub fn entities_for_namespace(
820 &self,
821 namespace: &str,
822 ) -> Result<Arc<dyn khive_storage::EntityStore>, SqliteError> {
823 if namespace.trim().is_empty() {
824 return Err(SqliteError::InvalidData(
825 "entities namespace must be non-empty".to_string(),
826 ));
827 }
828 self.ensure_store_schema(StoreSchemaKind::Entities)?;
829
830 Ok(Arc::new(entity::SqlEntityStore::new(
831 Arc::clone(&self.pool),
832 self.is_file_backed,
833 )))
834 }
835
836 pub fn attachments(&self) -> Result<Arc<dyn khive_storage::AttachmentStore>, SqliteError> {
843 Ok(Arc::new(attachment::SqlAttachmentStore::new(
844 Arc::clone(&self.pool),
845 self.is_file_backed,
846 )))
847 }
848
849 pub fn graph(&self) -> Result<Arc<dyn khive_storage::GraphStore>, SqliteError> {
854 self.graph_for_namespace("local")
855 }
856
857 pub fn graph_for_namespace(
859 &self,
860 namespace: &str,
861 ) -> Result<Arc<dyn khive_storage::GraphStore>, SqliteError> {
862 if namespace.trim().is_empty() {
863 return Err(SqliteError::InvalidData(
864 "graph namespace must be non-empty".to_string(),
865 ));
866 }
867 self.ensure_store_schema(StoreSchemaKind::Graph)?;
868
869 Ok(Arc::new(
870 graph::SqlGraphStore::new_scoped(
871 Arc::clone(&self.pool),
872 self.is_file_backed,
873 namespace.trim().to_string(),
874 )
875 .with_index_repair(crate::stores::index_repair::IndexRepairContext::new(
876 Arc::clone(&self.pool),
877 self.store_schemas.clone(),
878 crate::stores::index_repair::IndexReadKind::Graph,
879 )),
880 ))
881 }
882
883 fn ensure_store_schema(&self, kind: StoreSchemaKind) -> Result<(), SqliteError> {
884 if self.is_read_only()
885 || self.store_schemas[kind as usize]
886 .ready
887 .load(Ordering::Acquire)
888 {
889 return Ok(());
890 }
891 let writer = self.constructor_writer()?;
892 self.ensure_store_schema_with_writer(kind, writer.conn())
893 }
894
895 fn ensure_store_schema_with_writer(
896 &self,
897 kind: StoreSchemaKind,
898 conn: &rusqlite::Connection,
899 ) -> Result<(), SqliteError> {
900 self.store_schemas[kind as usize].ensure(conn, kind.initializer())?;
901 Ok(())
902 }
903
904 fn constructor_writer(
905 &self,
906 ) -> Result<crate::pool::PooledAutocommitWriteUnit<'_>, SqliteError> {
907 let context = khive_storage::capture_request_read_context();
908 let Some(operation) = context.store_acquisition_operation() else {
909 return self.pool.autocommit_write_unit();
910 };
911 let writer = self
912 .pool
913 .writer_until_for_admitted_operation(|| context.blocking_stop_reason().is_some())?
914 .ok_or_else(|| {
915 SqliteError::RequestReadStopped(khive_storage::StorageError::Timeout {
916 operation: operation.into(),
917 })
918 })?;
919 writer.admit_autocommit()
920 }
921
922 pub fn notes(&self) -> Result<Arc<dyn khive_storage::NoteStore>, SqliteError> {
926 self.notes_for_namespace("local")
927 }
928
929 pub fn notes_for_namespace(
933 &self,
934 namespace: &str,
935 ) -> Result<Arc<dyn khive_storage::NoteStore>, SqliteError> {
936 if namespace.trim().is_empty() {
937 return Err(SqliteError::InvalidData(
938 "notes namespace must be non-empty".to_string(),
939 ));
940 }
941 if !self.is_read_only()
942 && (!self.store_schemas[StoreSchemaKind::Notes as usize]
943 .ready
944 .load(Ordering::Acquire)
945 || self.notes_seq_repair_runs.load(Ordering::Relaxed) == 0)
946 {
947 let writer = self.constructor_writer()?;
948 self.ensure_store_schema_with_writer(StoreSchemaKind::Notes, writer.conn())?;
949
950 if self.notes_seq_repair_runs.load(Ordering::Relaxed) == 0 {
957 note::repair_notes_seq(writer.conn())?;
958 self.notes_seq_repair_runs.fetch_add(1, Ordering::Relaxed);
959 }
960 }
961
962 Ok(Arc::new(
963 note::SqlNoteStore::new(Arc::clone(&self.pool), self.is_file_backed).with_index_repair(
964 crate::stores::index_repair::IndexRepairContext::new(
965 Arc::clone(&self.pool),
966 self.store_schemas.clone(),
967 crate::stores::index_repair::IndexReadKind::Notes,
968 ),
969 ),
970 ))
971 }
972
973 pub fn notes_seq_repair_run_count(&self) -> usize {
978 self.notes_seq_repair_runs.load(Ordering::Relaxed)
979 }
980
981 pub fn events(&self) -> Result<Arc<dyn khive_storage::EventStore>, SqliteError> {
986 self.events_for_namespace("local")
987 }
988
989 pub fn events_for_namespace(
991 &self,
992 namespace: &str,
993 ) -> Result<Arc<dyn khive_storage::EventStore>, SqliteError> {
994 if namespace.trim().is_empty() {
995 return Err(SqliteError::InvalidData(
996 "events namespace must be non-empty".to_string(),
997 ));
998 }
999 self.ensure_store_schema(StoreSchemaKind::Events)?;
1000
1001 Ok(Arc::new(event::SqlEventStore::new_scoped(
1002 Arc::clone(&self.pool),
1003 self.is_file_backed,
1004 namespace.trim().to_string(),
1005 )))
1006 }
1007
1008 pub fn agents(&self) -> Result<Arc<dyn khive_storage::AgentStore>, SqliteError> {
1013 self.ensure_store_schema(StoreSchemaKind::Agents)?;
1014
1015 Ok(Arc::new(agents::SqlAgentStore::new(
1016 Arc::clone(&self.pool),
1017 self.is_file_backed,
1018 )))
1019 }
1020
1021 pub fn vectors(
1027 &self,
1028 model_key: &str,
1029 embedding_model: &str,
1030 dimensions: usize,
1031 ) -> Result<Arc<dyn khive_storage::VectorStore>, SqliteError> {
1032 self.vectors_for_namespace(model_key, embedding_model, dimensions, "local")
1033 }
1034
1035 pub fn vectors_for_namespace(
1045 &self,
1046 model_key: &str,
1047 embedding_model: &str,
1048 dimensions: usize,
1049 namespace: &str,
1050 ) -> Result<Arc<dyn khive_storage::VectorStore>, SqliteError> {
1051 validate_vector_model_key(model_key)?;
1052 if namespace.trim().is_empty() {
1053 return Err(SqliteError::InvalidData(
1054 "vector store namespace must be non-empty".to_string(),
1055 ));
1056 }
1057 self.ensure_vector_tables(&[(model_key, dimensions)])?;
1058 Ok(Arc::new(vectors::SqliteVecStore::new(
1059 Arc::clone(&self.pool),
1060 self.is_file_backed,
1061 model_key.to_string(),
1062 embedding_model.to_string(),
1063 dimensions,
1064 namespace.trim().to_string(),
1065 )?))
1066 }
1067
1068 pub fn ensure_vector_tables(&self, models: &[(&str, usize)]) -> Result<(), SqliteError> {
1077 for (model_key, _) in models {
1078 validate_vector_model_key(model_key)?;
1079 }
1080 if models.is_empty() {
1081 return Ok(());
1082 }
1083
1084 crate::extension::ensure_extensions_loaded();
1086
1087 if self.is_read_only() {
1092 let reader = self.pool.reader()?;
1096 for (model_key, _) in models {
1097 let table = format!("vec_{model_key}");
1098 if !sqlite_table_exists(reader.conn(), &table)? {
1099 return Err(SqliteError::InvalidData(format!(
1100 "read-only database has no vector table '{table}'; create and populate it in \
1101 a writable copy before opening the snapshot"
1102 )));
1103 }
1104 validate_vector_table_columns(reader.conn(), &table)?;
1105 }
1106 return Ok(());
1107 }
1108
1109 let pending = self.unprepared_vector_tables(models);
1110 if pending.is_empty() {
1111 return Ok(());
1112 }
1113 let writer = self.constructor_writer()?;
1114 let pending = self.unprepared_vector_tables(&pending);
1117 if pending.is_empty() {
1118 return Ok(());
1119 }
1120
1121 for (model_key, _) in &pending {
1125 let table = format!("vec_{model_key}");
1126 if sqlite_table_exists(writer.conn(), &table)? {
1132 validate_vector_table_columns(writer.conn(), &table)?;
1133 }
1134 }
1135
1136 writer
1145 .conn()
1146 .execute_batch(crate::migrations::EMBEDDING_MODELS_DDL)?;
1147
1148 writer
1152 .conn()
1153 .execute_batch(crate::migrations::ANN_WRITE_LOG_DDL)?;
1154 writer
1155 .conn()
1156 .execute_batch(crate::migrations::ANN_WRITE_LOG_MODEL_SEQ_INDEX_DDL)?;
1157 writer
1158 .conn()
1159 .execute_batch(crate::migrations::ANN_CONSUMER_PENDING_DDL)?;
1160 for (model_key, dimensions) in &pending {
1162 let ddl = format!(
1163 "CREATE VIRTUAL TABLE IF NOT EXISTS vec_{} USING vec0(\
1164 subject_id TEXT PRIMARY KEY, \
1165 namespace TEXT NOT NULL, \
1166 kind TEXT NOT NULL, \
1167 field TEXT NOT NULL, \
1168 embedding_model TEXT NOT NULL, \
1169 embedding float[{}] distance_metric=cosine\
1170 )",
1171 model_key, dimensions
1172 );
1173 writer.conn().execute_batch(&ddl)?;
1174 }
1175 self.vector_tables_ready.lock().extend(
1178 pending
1179 .iter()
1180 .map(|(model_key, _)| (*model_key).to_string()),
1181 );
1182 Ok(())
1183 }
1184
1185 fn unprepared_vector_tables<'a>(&self, models: &[(&'a str, usize)]) -> Vec<(&'a str, usize)> {
1187 let ready = self.vector_tables_ready.lock();
1188 models
1189 .iter()
1190 .filter(|(model_key, _)| !ready.contains(*model_key))
1191 .copied()
1192 .collect()
1193 }
1194
1195 pub fn register_embedding_model(
1200 &self,
1201 engine_name: &str,
1202 model_id: &str,
1203 key_version: &str,
1204 dimensions: u32,
1205 ) -> Result<(), SqliteError> {
1206 let writer = self.pool.autocommit_write_unit()?;
1207 writer
1208 .conn()
1209 .execute_batch(crate::migrations::EMBEDDING_MODELS_DDL)
1210 .map_err(|error| {
1211 SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
1212 })?;
1213
1214 let now = chrono::Utc::now().timestamp_micros();
1215 let canonical_key =
1216 format!("{engine_name}:{model_id}:{key_version}:{dimensions}").into_bytes();
1217 let id = uuid::Uuid::new_v4();
1218 writer
1219 .conn()
1220 .execute(
1221 "INSERT INTO _embedding_models \
1222 (id, engine_name, model_id, key_version, dim, output_dim, status, \
1223 activated_at, superseded_at, superseded_by, canonical_key, created_at) \
1224 VALUES (?1, ?2, ?3, ?4, ?5, NULL, 'active', ?6, NULL, NULL, ?7, ?8) \
1225 ON CONFLICT(canonical_key) DO UPDATE SET \
1226 status = 'active', \
1227 activated_at = COALESCE(_embedding_models.activated_at, excluded.activated_at)",
1228 rusqlite::params![
1229 id.as_bytes().as_slice(),
1230 engine_name,
1231 model_id,
1232 key_version,
1233 dimensions as i64,
1234 now,
1235 canonical_key,
1236 now,
1237 ],
1238 )
1239 .map_err(|error| {
1240 SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
1241 })?;
1242 Ok(())
1243 }
1244
1245 pub fn sparse(
1249 &self,
1250 model_key: &str,
1251 ) -> Result<Arc<dyn khive_storage::SparseStore>, SqliteError> {
1252 self.sparse_for_namespace(model_key, "local")
1253 }
1254
1255 pub fn sparse_for_namespace(
1259 &self,
1260 model_key: &str,
1261 namespace: &str,
1262 ) -> Result<Arc<dyn khive_storage::SparseStore>, SqliteError> {
1263 if model_key.is_empty()
1264 || !model_key
1265 .chars()
1266 .all(|c| c.is_ascii_alphanumeric() || c == '_')
1267 {
1268 return Err(SqliteError::InvalidData(format!(
1269 "invalid model_key '{}': must be non-empty and contain only alphanumeric/underscore characters",
1270 model_key
1271 )));
1272 }
1273 if namespace.trim().is_empty() {
1274 return Err(SqliteError::InvalidData(
1275 "sparse store namespace must be non-empty".to_string(),
1276 ));
1277 }
1278
1279 if self.is_read_only() {
1280 let table = format!("sparse_{model_key}");
1281 let reader = self.pool.reader()?;
1282 if !sqlite_table_exists(reader.conn(), &table)? {
1283 return Err(SqliteError::InvalidData(format!(
1284 "read-only database has no sparse table '{table}'; create and populate it in \
1285 a writable copy before opening the snapshot"
1286 )));
1287 }
1288 } else {
1289 let writer = self.pool.autocommit_write_unit()?;
1290 sparse::ensure_sparse_schema(writer.conn(), model_key)
1291 .map_err(SqliteError::Rusqlite)?;
1292 }
1293
1294 Ok(Arc::new(sparse::SqliteSparseStore::new(
1295 Arc::clone(&self.pool),
1296 self.is_file_backed,
1297 model_key.to_string(),
1298 namespace.trim().to_string(),
1299 )?))
1300 }
1301
1302 pub fn text(&self, table_key: &str) -> Result<Arc<dyn khive_storage::TextSearch>, SqliteError> {
1309 self.text_with_tokenizer(table_key, "trigram")
1310 }
1311
1312 pub fn text_with_tokenizer(
1320 &self,
1321 table_key: &str,
1322 tokenizer: &str,
1323 ) -> Result<Arc<dyn khive_storage::TextSearch>, SqliteError> {
1324 if table_key.is_empty()
1325 || !table_key
1326 .chars()
1327 .all(|c| c.is_ascii_alphanumeric() || c == '_')
1328 {
1329 return Err(SqliteError::InvalidData(format!(
1330 "invalid table_key '{}': must be non-empty and contain only \
1331 alphanumeric/underscore characters",
1332 table_key
1333 )));
1334 }
1335 if table_key.ends_with("_rowids") || table_key.ends_with("_rowids_state") {
1345 return Err(SqliteError::InvalidData(format!(
1346 "invalid table_key '{}': must not end in '_rowids' or '_rowids_state' — those \
1347 suffixes are reserved for a text table's own rowid-map sidecar and its \
1348 completion-marker state table (see text::rowid_map_table, \
1349 text::rowid_map_state_table)",
1350 table_key
1351 )));
1352 }
1353 if tokenizer.is_empty()
1354 || !tokenizer
1355 .chars()
1356 .all(|c| c.is_ascii_alphanumeric() || c == '_')
1357 {
1358 return Err(SqliteError::InvalidData(format!(
1359 "invalid tokenizer '{}': must be non-empty and contain only \
1360 alphanumeric/underscore characters",
1361 tokenizer
1362 )));
1363 }
1364
1365 let ddl = format!(
1366 "CREATE VIRTUAL TABLE IF NOT EXISTS fts_{} USING fts5(\
1367 subject_id UNINDEXED, \
1368 kind UNINDEXED, \
1369 title, \
1370 body, \
1371 tags UNINDEXED, \
1372 namespace UNINDEXED, \
1373 metadata UNINDEXED, \
1374 updated_at UNINDEXED, \
1375 record_kind, \
1376 tokenize = '{}'\
1377 )",
1378 table_key, tokenizer
1379 );
1380 let table = format!("fts_{table_key}");
1381 if self.is_read_only() {
1382 let reader = self.pool.reader()?;
1383 if !sqlite_table_exists(reader.conn(), &table)? {
1384 return Err(SqliteError::InvalidData(format!(
1385 "read-only database has no text-search table '{table}'; create and populate \
1386 it in a writable copy before opening the snapshot"
1387 )));
1388 }
1389 let map = text::rowid_map_table(&table);
1403 let map_exists = sqlite_table_exists(reader.conn(), &map)?;
1404 let marker_present = if map_exists {
1405 let state = text::rowid_map_state_table(&table);
1406 sqlite_table_exists(reader.conn(), &state)?
1407 && reader.conn().query_row(
1408 &format!(
1409 "SELECT EXISTS(SELECT 1 FROM {state} WHERE key = 'backfill' AND value = ?1)"
1410 ),
1411 rusqlite::params![text::ROWID_MAP_BACKFILL_COMPLETE],
1412 |row| row.get(0),
1413 )?
1414 } else {
1415 false
1416 };
1417 if !map_exists || !marker_present {
1418 warn_scan_fallback_once(&table);
1419 return Ok(Arc::new(text::Fts5TextSearch::new_scan_fallback(
1420 Arc::clone(&self.pool),
1421 self.is_file_backed,
1422 table_key.to_string(),
1423 )));
1424 }
1425 } else if !self.text_tables_ready.lock().contains(&table) {
1426 let writer = self.pool.autocommit_write_unit()?;
1427 if !self.text_tables_ready.lock().contains(&table) {
1430 writer.conn().execute_batch(&ddl)?;
1431 writer.conn().execute_batch(&text::rowid_map_ddl(&table))?;
1432 let marker_durable = ensure_fts_rowid_map_backfilled(
1433 writer.conn(),
1434 &table,
1435 &self.pool.write_admission(),
1436 )?;
1437 if marker_durable {
1440 self.text_tables_ready.lock().insert(table.clone());
1441 }
1442 }
1443 }
1444
1445 Ok(Arc::new(text::Fts5TextSearch::new(
1446 Arc::clone(&self.pool),
1447 self.is_file_backed,
1448 table_key.to_string(),
1449 )))
1450 }
1451
1452 pub fn blob_store(
1461 &self,
1462 config_root: Option<&Path>,
1463 floor_bytes: Option<u64>,
1464 ) -> Result<Arc<dyn khive_storage::BlobStore>, SqliteError> {
1465 Ok(Arc::new(self.fs_blob_store(config_root, floor_bytes)?))
1466 }
1467
1468 pub(crate) fn fs_blob_store(
1471 &self,
1472 config_root: Option<&Path>,
1473 floor_bytes: Option<u64>,
1474 ) -> Result<blob::FsBlobStore, SqliteError> {
1475 let root = blob::resolve_blob_root(self.data_dir().as_deref(), config_root)?;
1476 let floor = blob::FsBlobStore::resolve_floor(&root, floor_bytes);
1477 blob::FsBlobStore::new(root, floor)
1478 }
1479
1480 pub fn blob_store_read_only(
1485 &self,
1486 config_root: Option<&Path>,
1487 floor_bytes: Option<u64>,
1488 ) -> Result<Arc<dyn khive_storage::BlobStore>, SqliteError> {
1489 let root = blob::resolve_blob_root(self.data_dir().as_deref(), config_root)?;
1490 let floor = blob::FsBlobStore::resolve_floor(&root, floor_bytes);
1491 Ok(Arc::new(blob::FsBlobStore::open_existing(root, floor)?))
1492 }
1493
1494 pub fn is_file_backed(&self) -> bool {
1496 self.is_file_backed
1497 }
1498
1499 pub fn is_read_only(&self) -> bool {
1502 self.pool.config().read_only
1503 }
1504
1505 pub fn data_dir(&self) -> Option<std::path::PathBuf> {
1508 self.path.as_ref()?.parent().map(|p| p.to_path_buf())
1509 }
1510
1511 pub fn ann_root(&self) -> Option<std::path::PathBuf> {
1519 ann_root_for(self.path.as_ref()?)
1520 }
1521
1522 pub fn pool(&self) -> &ConnectionPool {
1524 &self.pool
1525 }
1526
1527 pub fn database_owner_identity(
1530 &self,
1531 ) -> Result<DatabaseOwnerIdentity, DatabaseOwnerIdentityError> {
1532 self.pool.database_owner_identity()
1533 }
1534
1535 pub fn verify_database_owner(
1537 &self,
1538 expected: &DatabaseOwnerIdentity,
1539 ) -> Result<(), DatabaseOwnerIdentityError> {
1540 self.pool.verify_database_owner(expected)
1541 }
1542
1543 pub fn pool_arc(&self) -> Arc<ConnectionPool> {
1545 Arc::clone(&self.pool)
1546 }
1547}
1548
1549fn ann_root_for(path: &std::path::Path) -> Option<std::path::PathBuf> {
1554 let mut file = path.file_name()?.to_os_string();
1555 file.push(".ann");
1556 path.parent().map(|p| p.join(file))
1557}
1558
1559#[cfg(test)]
1560#[path = "backend/store_accessor_tests.rs"]
1561mod store_accessor_tests;
1562
1563#[cfg(test)]
1564#[path = "backend/store_accessor_index_tests.rs"]
1565mod store_accessor_index_tests;
1566
1567#[cfg(test)]
1568#[path = "backend_tests.rs"]
1569mod tests;
1570
1571#[cfg(test)]
1572#[path = "backend_admission_tests.rs"]
1573mod admission_tests;
1574
1575#[cfg(test)]
1576mod live_readonly_tests;