khive_db/
lib.rs

1//! SQLite storage backend for the khive knowledge graph runtime.
2//!
3//! Provides entity, note, event, edge, FTS5 text search, and optional
4//! `sqlite-vec` vector storage over a WAL-mode connection pool.
5//!
6//! # Terminal write settlement
7//! Pooled, standalone, and lifetime write owners retain their volume lease
8//! through rollback or successful owned connection close. If a retired
9//! connection remains outside autocommit and close also fails, cleanup reports
10//! the path, volume, rollback and close errors, returns a terminal
11//! outcome-unknown error, and poisons the pool so it refuses every later write
12//! and releases the lease. The process keeps running: the host decides whether
13//! to exit.
14
15/// Concrete storage backend providing capability-trait factories.
16pub mod backend;
17/// Periodic WAL checkpoint task.
18pub mod checkpoint;
19// Kept internal while the code-map constructor and SQLite callback wiring land.
20#[allow(dead_code)]
21mod code_map_vfs;
22mod connection_settlement;
23/// Durable database owner identity paired with the opened physical file.
24pub mod database_owner_identity;
25/// Read-only-by-intent database-integrity and WAL/checkpoint diagnostics.
26pub mod diagnostics;
27/// Physical-volume identity and bounded cooperative SQLite admission lease.
28mod disk_guard;
29mod disk_guard_config;
30/// Environment readers with explicit parse/default and boolean policies.
31pub mod env;
32/// Error types for the SQLite layer.
33pub mod error;
34/// SQLite extension registration (sqlite-vec auto-extension).
35pub mod extension;
36/// Physical file identity shared by pool admission and backend alias routing.
37#[cfg(any(unix, windows))]
38pub mod file_identity;
39mod fts_maintenance;
40/// Schema migration system (versioned migrations).
41pub mod migrations;
42/// What a live store's schema says about `namespace` (ADR-189).
43pub mod namespace_census;
44/// Moving records between namespaces (ADR-189).
45pub mod namespace_move;
46/// A store fixture reproducing the namespace split, for the move's own arms.
47#[cfg(any(test, feature = "test-support"))]
48pub mod namespace_move_fixture;
49/// Feature-gated namespace-bounded FTS5 trigram prototype.
50#[cfg(feature = "namespace-trigram-proto")]
51pub mod namespace_trigram_proto;
52/// WAL-mode connection pool: one writer, N concurrent readers.
53pub mod pool;
54mod read_cancellation;
55/// `SqlAccess` trait bridge to `ConnectionPool`.
56pub mod sql_bridge;
57/// Pure statement-list builders for caller-owned SQL execution.
58pub mod statement_lists;
59#[cfg(any(test, feature = "test-support"))]
60mod statement_observer;
61/// Per-substrate store implementations (entity, note, graph, event, text, vectors, sparse).
62pub mod stores;
63/// Append-only NDJSON writer-timeout event sink (crate-internal).
64mod timeout_sink;
65/// Metadata-only copy-size estimate for guarded VACUUM admission.
66mod vacuum_capacity;
67/// Cross-process WAL-pin attribution sidecar (ADR-091 Amendment 2 Plank B).
68/// The sidecar write path (heartbeat/beacon) and identity primitives are
69/// portable; directory collection (`enumerate_live`/`housekeep_live`) is
70/// Unix-only — its only caller is the daemon's checkpoint task, and daemon
71/// mode itself requires Unix (see `khive-mcp/src/serve.rs`).
72pub mod walpin;
73/// Single-writer task and bounded write queue (ADR-067 Component A).
74pub mod writer_task;
75
76#[cfg(test)]
77mod writer_busy_fixture;
78
79#[cfg(test)]
80mod test_process;
81
82#[cfg(test)]
83mod lease_latency_tests;
84
85pub use backend::StorageBackend;
86pub use checkpoint::{
87    checkpoint_once, run_checkpoint_task, CheckpointConfig, CheckpointLifecycleOwner,
88    CheckpointTick,
89};
90pub use checkpoint::{run_session_sweep_task, SessionSweepConfig, SweepBackend};
91pub use database_owner_identity::{DatabaseOwnerIdentity, DatabaseOwnerIdentityError};
92pub use disk_guard::harness_scoped_process_leases;
93pub use disk_guard_config::{
94    default_volume_lock_dir, require_volume_lock_dir, resolve_disk_guard_config,
95    DiskGuardConfigSource, DiskGuardEnvironment, EffectiveDiskGuardConfig,
96};
97pub use error::{
98    SqliteError, SQLITE_WAL_CAPACITY_REFUSED_STAGE, SQLITE_WAL_CAPACITY_UNAVAILABLE_STAGE,
99};
100pub use fts_maintenance::{
101    fts_maintenance_counters, FtsIndexStructure, FtsLevelStructure, FtsMaintenanceCounters,
102    FtsSegmentDiagnostics,
103};
104pub use khive_storage::{
105    await_request_read_phase, effective_request_read_deadline, ensure_request_read_active,
106    inherit_request_read_cancellation, inherit_request_read_context, request_read_is_cancelled,
107    request_read_timeout_from_env, scope_request_read_cancellation, scope_request_read_deadline,
108    scope_request_read_deadline_at, wait_for_request_read_cancellation, RequestReadDeadline,
109    DEFAULT_REQUEST_READ_TIMEOUT_SECS,
110};
111pub use migrations::{
112    inspect_integrity, inspect_page_accounting, inspect_schema_is_current, inspect_schema_version,
113    query_embedding_models, read_schema_version, run_migrations, run_migrations_with_policy,
114    EmbeddingModelRegistryRecord, Migration, MigrationWritePolicy, PageAccounting,
115    ServiceSchemaPlan, VersionedMigration, MIGRATIONS,
116};
117pub use pool::{
118    CheckpointGuard, CheckpointResult, ConnectionPool, PoolConfig, ReaderGuard, ReaderRow,
119    WalCeilingPolicy, WalCeilingSource, WriterGuard,
120};
121#[cfg(any(test, feature = "test-support"))]
122pub use read_cancellation::scope_test_read_progress;
123pub use read_cancellation::{sqlite_interrupt_grace_from_env, DEFAULT_SQLITE_INTERRUPT_GRACE_MS};
124pub use sql_bridge::SqlBridge;
125#[cfg(any(test, feature = "test-support"))]
126pub use statement_observer::{StartedStatement, StatementStartObservation};
127pub use writer_task::WriterTaskHandle;
128
129#[cfg(test)]
130mod namespace_move_fixture_tests;
131#[cfg(test)]
132mod stream_schema_tests;
133
134#[cfg(test)]
135mod reader_lease_tests;
136
137#[cfg(test)]
138mod raw_sql_reader_admission_tests;
khive_db/lib.rs

khive_db/
lib.rs
