Skip to main content

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/// Transaction-scoped persistence for shared authority records.
16pub mod authority;
17/// Concrete storage backend providing capability-trait factories.
18pub mod backend;
19/// Periodic WAL checkpoint task.
20pub mod checkpoint;
21// Kept internal while the code-map constructor and SQLite callback wiring land.
22#[allow(dead_code)]
23mod code_map_vfs;
24mod connection_settlement;
25/// Durable database owner identity paired with the opened physical file.
26pub mod database_owner_identity;
27/// Read-only-by-intent database-integrity and WAL/checkpoint diagnostics.
28pub mod diagnostics;
29/// Physical-volume identity and bounded cooperative SQLite admission lease.
30mod disk_guard;
31mod disk_guard_config;
32/// Environment readers with explicit parse/default and boolean policies.
33pub mod env;
34/// Error types for the SQLite layer.
35pub mod error;
36
37/// Bounded prune of expendable polling-dispatch audit rows (ADR-212 §4, operator maintenance).
38pub mod events_prune;
39#[cfg(test)]
40mod events_prune_tests;
41/// SQLite extension registration (sqlite-vec auto-extension).
42pub mod extension;
43/// Physical file identity shared by pool admission and backend alias routing.
44#[cfg(any(unix, windows))]
45pub mod file_identity;
46mod fts_maintenance;
47/// Read predicates and transaction assertions for the graph-lint caller.
48pub mod graph_lint;
49/// Canonical physical store sets for cooperative maintenance metadata.
50#[cfg(unix)]
51pub mod maintenance;
52/// Schema migration system (versioned migrations).
53pub mod migrations;
54/// What a live store's schema says about `namespace` (ADR-189).
55pub mod namespace_census;
56/// Moving records between namespaces (ADR-189).
57pub mod namespace_move;
58/// A store fixture reproducing the namespace split, for the move's own arms.
59#[cfg(any(test, feature = "test-support"))]
60pub mod namespace_move_fixture;
61/// Feature-gated namespace-bounded FTS5 trigram prototype.
62#[cfg(feature = "namespace-trigram-proto")]
63pub mod namespace_trigram_proto;
64/// Durable deferred entity-index obligations (ADR-014 Amendment 7).
65pub mod pending_index;
66/// WAL-mode connection pool: one writer, N concurrent readers.
67pub mod pool;
68mod progress_conn;
69#[cfg(any(test, feature = "test-support"))]
70pub mod test_hooks;
71#[doc(hidden)]
72pub use progress_conn::ProgressConn;
73mod read_cancellation;
74/// `SqlAccess` trait bridge to `ConnectionPool`.
75pub mod sql_bridge;
76/// Pure statement-list builders for caller-owned SQL execution.
77pub mod statement_lists;
78#[cfg(any(test, feature = "test-support"))]
79mod statement_observer;
80/// Per-substrate store implementations (entity, note, graph, event, text, vectors, sparse).
81pub mod stores;
82/// Append-only NDJSON writer-timeout event sink (crate-internal).
83mod timeout_sink;
84/// Metadata-only copy-size estimate for guarded VACUUM admission.
85mod vacuum_capacity;
86/// Cross-process WAL-pin attribution sidecar (ADR-091 Amendment 2 Plank B).
87/// The sidecar write path (heartbeat/beacon) and identity primitives are
88/// portable; directory collection (`enumerate_live`/`housekeep_live`) is
89/// Unix-only — its only caller is the daemon's checkpoint task, and daemon
90/// mode itself requires Unix (see `khive-mcp/src/serve.rs`).
91pub mod walpin;
92/// Single-writer task and bounded write queue (ADR-067 Component A).
93mod writer_admission_metrics;
94pub mod writer_task;
95
96#[cfg(test)]
97mod writer_busy_fixture;
98
99#[cfg(test)]
100mod test_process;
101
102#[cfg(test)]
103mod lease_latency_tests;
104
105pub use backend::StorageBackend;
106pub use checkpoint::{
107    checkpoint_once, run_checkpoint_task, CheckpointConfig, CheckpointLifecycleOwner,
108    CheckpointTick,
109};
110pub use checkpoint::{run_session_sweep_task, SessionSweepConfig, SweepBackend};
111pub use database_owner_identity::{DatabaseOwnerIdentity, DatabaseOwnerIdentityError};
112pub use disk_guard::harness_scoped_process_leases;
113pub use disk_guard::{ScopedFuture, WriteClassContext};
114pub use disk_guard_config::{
115    default_volume_lock_dir, require_volume_lock_dir, resolve_disk_guard_config,
116    DiskGuardConfigSource, DiskGuardEnvironment, EffectiveDiskGuardConfig,
117};
118pub use error::{
119    SqliteError, SQLITE_WAL_CAPACITY_REFUSED_STAGE, SQLITE_WAL_CAPACITY_UNAVAILABLE_STAGE,
120};
121pub use fts_maintenance::{
122    fts_maintenance_counters, FtsIndexStructure, FtsLevelStructure, FtsMaintenanceCounters,
123    FtsSegmentDiagnostics,
124};
125pub use khive_storage::{
126    await_request_read_phase, effective_request_read_deadline, ensure_request_read_active,
127    inherit_request_read_cancellation, inherit_request_read_context, request_read_is_cancelled,
128    request_read_timeout_from_env, scope_request_read_cancellation, scope_request_read_deadline,
129    scope_request_read_deadline_at, wait_for_request_read_cancellation, RequestReadDeadline,
130    DEFAULT_REQUEST_READ_TIMEOUT_SECS,
131};
132pub use migrations::{
133    inspect_integrity, inspect_page_accounting, inspect_schema_is_current, inspect_schema_version,
134    query_embedding_models, read_schema_version, run_migrations, run_migrations_with_policy,
135    EmbeddingModelRegistryRecord, Migration, MigrationWritePolicy, PageAccounting,
136    ServiceSchemaPlan, VersionedMigration, MIGRATIONS,
137};
138pub use pool::{
139    CheckpointGuard, CheckpointResult, ConnectionPool, PoolConfig, ReaderGuard, ReaderRow,
140    StandaloneCheckpoint, WalCeilingPolicy, WalCeilingSource, WriterGuard,
141};
142#[cfg(any(test, feature = "test-support"))]
143pub use read_cancellation::scope_test_read_progress;
144pub use read_cancellation::{sqlite_interrupt_grace_from_env, DEFAULT_SQLITE_INTERRUPT_GRACE_MS};
145pub use sql_bridge::SqlBridge;
146#[cfg(any(test, feature = "test-support"))]
147pub use statement_observer::{StartedStatement, StatementStartObservation};
148pub use writer_task::WriterTaskHandle;
149
150#[cfg(test)]
151mod namespace_move_fixture_tests;
152#[cfg(test)]
153mod stream_schema_tests;
154
155#[cfg(test)]
156mod reader_lease_tests;
157
158#[cfg(test)]
159mod raw_sql_reader_admission_tests;