Crate khive_db 

SQLite storage backend for the khive knowledge graph runtime.

Provides entity, note, event, edge, FTS5 text search, and optional sqlite-vec vector storage over a WAL-mode connection pool.

Terminal write settlement

Pooled, standalone, and lifetime write owners retain their volume lease through rollback or successful owned connection close. If a retired connection remains outside autocommit and close also fails, cleanup reports the path, volume, rollback and close errors, returns a terminal outcome-unknown error, and poisons the pool so it refuses every later write and releases the lease. The process keeps running: the host decides whether to exit.

Re-exports

pub use backend::StorageBackend;

pub use checkpoint::checkpoint_once;

pub use checkpoint::run_checkpoint_task;

pub use checkpoint::CheckpointConfig;

pub use checkpoint::CheckpointLifecycleOwner;

pub use checkpoint::CheckpointTick;

pub use checkpoint::run_session_sweep_task;

pub use checkpoint::SessionSweepConfig;

pub use checkpoint::SweepBackend;

pub use database_owner_identity::DatabaseOwnerIdentity;

pub use database_owner_identity::DatabaseOwnerIdentityError;

pub use error::SqliteError;

pub use error::SQLITE_WAL_CAPACITY_REFUSED_STAGE;

pub use error::SQLITE_WAL_CAPACITY_UNAVAILABLE_STAGE;

pub use migrations::inspect_schema_is_current;

pub use migrations::inspect_schema_version;

pub use migrations::query_embedding_models;

pub use migrations::read_schema_version;

pub use migrations::run_migrations;

pub use migrations::run_migrations_with_policy;

pub use migrations::EmbeddingModelRegistryRecord;

pub use migrations::Migration;

pub use migrations::MigrationWritePolicy;

pub use migrations::ServiceSchemaPlan;

pub use migrations::VersionedMigration;

pub use migrations::MIGRATIONS;

pub use pool::CheckpointGuard;

pub use pool::CheckpointResult;

pub use pool::ConnectionPool;

pub use pool::PoolConfig;

pub use pool::ReaderGuard;

pub use pool::ReaderRow;

pub use pool::WalCeilingPolicy;

pub use pool::WalCeilingSource;

pub use pool::WriterGuard;

pub use sql_bridge::SqlBridge;

pub use writer_task::WriterTaskHandle;

Modules

backend

Concrete storage backend providing capability-trait factories. Concrete storage backend providing capability traits.

checkpoint

Periodic WAL checkpoint task. Periodic WAL checkpoint task for the connection pool (ADR-091; dedicated checkpoint connection amendment, see below).

database_owner_identity

Durable database owner identity paired with the opened physical file. Durable ownership evidence captured from the database SQLite opened.

diagnostics

Read-only-by-intent database-integrity and WAL/checkpoint diagnostics. Non-mutating-by-intent database, WAL, and checkpoint diagnostics (read-only operator surface).

error

Error types for the SQLite layer. Error types for the SQLite storage layer.

extension

SQLite extension registration (sqlite-vec auto-extension). SQLite extension registration for sqlite-vec.

file_identity

Physical file identity shared by pool admission and backend alias routing. Physical identity of a database file, including SQLite’s opened Windows handle.

migrations

Schema migration system (versioned migrations). Schema migration system for the SQLite storage layer.

namespace_census

What a live store’s schema says about namespace (ADR-189). What a live store’s schema says about namespace (ADR-189).

namespace_move

Moving records between namespaces (ADR-189). Moving records between namespaces (ADR-189).

pool

WAL-mode connection pool: one writer, N concurrent readers. Connection pool for SQLite: one exclusive writer, N concurrent readers.

sql_bridge

SqlAccess trait bridge to ConnectionPool. SqlAccess bridge: connects ConnectionPool to khive_storage::SqlAccess.

stores

Per-substrate store implementations (entity, note, graph, event, text, vectors, sparse). Per-substrate SQLite store implementations.

walpin

Cross-process WAL-pin attribution sidecar (ADR-091 Amendment 2 Plank B). The sidecar write path (heartbeat/beacon) and identity primitives are portable; directory collection (enumerate_live/housekeep_live) is Unix-only — its only caller is the daemon’s checkpoint task, and daemon mode itself requires Unix (see khive-mcp/src/serve.rs). ADR-091 Amendment 2 Plank B: cross-process WAL-pin attribution sidecar.

writer_task

Single-writer task and bounded write queue (ADR-067 Component A). Single-writer task and bounded write queue (ADR-067 Component A).

Structs

DiskGuardEnvironment

One construction-time snapshot shared by backend opening and config identity. Raw values remain intact so invalid Unicode and overflow fail at validation.

EffectiveDiskGuardConfig

FtsIndexStructure

FtsLevelStructure

FtsMaintenanceCounters

FtsSegmentDiagnostics

RequestReadDeadline

One absolute request deadline represented on async and blocking clocks.

Enums

DiskGuardConfigSource

Provenance is diagnostic; daemon compatibility uses only effective numbers.

Constants

DEFAULT_REQUEST_READ_TIMEOUT_SECS

Default nonzero ceiling for request-owned read work, including compose.

DEFAULT_SQLITE_INTERRUPT_GRACE_MS

Post-deadline window for interrupted read tasks to finalize SQLite and return their connection before a coordinator escalates async cancellation.

Functions

await_request_read_phase

Await one request-owned read phase under the current absolute deadline.

default_volume_lock_dir

The directory that holds the volume advisory lock files shared by every khive process of one user.

effective_request_read_deadline

Constrain candidate by the current request’s deadline without installing a new scope.

ensure_request_read_active

Refuse to begin another request-owned read phase after cancellation.

fts_maintenance_counters

harness_scoped_process_leases

Whether in-process volume leases are scoped by lock directory, which only the workspace test marker turns on. Read once per process.

inherit_request_read_cancellation

Intention-revealing alias for cancellation-only child tasks.

inherit_request_read_context

Capture the current request read context for a spawned child future.

request_read_is_cancelled

Return whether the current request has stopped its read-only work.

request_read_timeout_from_env

Resolve the operator-visible request-read ceiling from KHIVE_REQUEST_READ_TIMEOUT_SECS.

require_volume_lock_dir

A caller’s optional lock directory, or the configuration error that default_volume_lock_dir reports when no directory can be resolved.

resolve_disk_guard_config

scope_request_read_cancellation

Scope future to an explicit read-cancellation signal.

scope_request_read_deadline

Scope future to one relative read deadline, preserving an earlier outer deadline instead of renewing it.

scope_request_read_deadline_at

Scope future to an already-created absolute read deadline.

sqlite_interrupt_grace_from_env

Resolve the validated SQLite interrupt-settlement grace.

wait_for_request_read_cancellation

Wait until the current request’s read-only work is cancelled or timed out.