fathomdb_engine/
lib.rs

1#[macro_use]
2mod trace_support;
3
4mod admin;
5mod coordinator;
6mod database_lock;
7mod embedder;
8mod ids;
9mod operational;
10mod projection;
11pub mod rebuild_actor;
12mod runtime;
13mod sqlite;
14mod telemetry;
15mod vector_projection_actor;
16mod writer;
17
18pub use admin::{
19    AdminHandle, AdminService, Capabilities, ConfigureEmbeddingOutcome, ConfigureVecOutcome,
20    CurrentConfig, EmbedderCapability, EmbeddingProfileSummary, FtsKindConfig, FtsProfile,
21    FtsPropertyPathMode, FtsPropertyPathSpec, FtsPropertySchemaRecord, IntegrityReport,
22    KindDescription, LogicalPurgeReport, LogicalRestoreReport, ProjectionImpact,
23    ProvenancePurgeOptions, ProvenancePurgeReport, SafeExportManifest, SafeExportOptions,
24    SemanticReport, SkippedEdge, TOKENIZER_PRESETS, TraceReport, VecIndexStatus, VecKindConfig,
25    VecProfile, VectorRegenerationConfig, VectorRegenerationReport, VectorSource, WorkQueueSummary,
26    load_vector_regeneration_config,
27};
28pub use coordinator::{
29    ActionRow, EdgeExpansionRootRows, EdgeExpansionSlotRows, EdgeRow, ExecutionCoordinator,
30    ExpansionRootRows, ExpansionSlotRows, GroupedQueryRows, NodeRow, ProvenanceEvent, QueryPlan,
31    QueryRows, RunRow, StepRow,
32};
33#[cfg(feature = "default-embedder")]
34pub use embedder::BuiltinBgeSmallEmbedder;
35pub use embedder::{BatchEmbedder, EmbedderError, QueryEmbedder, QueryEmbedderIdentity};
36pub use ids::{new_id, new_row_id};
37pub use operational::{
38    OperationalCollectionKind, OperationalCollectionRecord, OperationalCompactionReport,
39    OperationalCurrentRow, OperationalFilterClause, OperationalFilterField,
40    OperationalFilterFieldType, OperationalFilterMode, OperationalFilterValue,
41    OperationalHistoryValidationIssue, OperationalHistoryValidationReport, OperationalMutationRow,
42    OperationalPurgeReport, OperationalReadReport, OperationalReadRequest,
43    OperationalRegisterRequest, OperationalRepairReport, OperationalRetentionActionKind,
44    OperationalRetentionPlanItem, OperationalRetentionPlanReport, OperationalRetentionRunItem,
45    OperationalRetentionRunReport, OperationalSecondaryIndexDefinition,
46    OperationalSecondaryIndexField, OperationalSecondaryIndexRebuildReport,
47    OperationalSecondaryIndexValueType, OperationalTraceReport, OperationalValidationContract,
48    OperationalValidationField, OperationalValidationFieldType, OperationalValidationMode,
49};
50pub use projection::{ProjectionRepairReport, ProjectionService, ProjectionTarget};
51pub use rebuild_actor::{RebuildMode, RebuildProgress, RebuildStateRow};
52pub use runtime::EngineRuntime;
53pub use sqlite::{SharedSqlitePolicy, shared_sqlite_policy};
54pub use telemetry::{
55    SqliteCacheStatus, TelemetryCounters, TelemetryLevel, TelemetrySnapshot, read_db_cache_status,
56};
57pub use vector_projection_actor::{DrainReport, VectorProjectionActor};
58pub use writer::{
59    ActionInsert, ChunkInsert, ChunkPolicy, EdgeInsert, EdgeRetire, LastAccessTouchReport,
60    LastAccessTouchRequest, NodeInsert, NodeRetire, OperationalWrite, OptionalProjectionTask,
61    ProvenanceMode, RunInsert, StepInsert, WriteReceipt, WriteRequest, WriterActor,
62};
63// Pack G: `VecInsert` is `#[deprecated]` but still re-exported so external
64// callers see the warning rather than a hard compile break during the
65// transition window. The inner `#[allow]` silences the deprecation on the
66// re-export itself.
67#[allow(deprecated)]
68pub use writer::VecInsert;
69
70use thiserror::Error;
71
72/// Top-level error type for all engine operations.
73#[derive(Debug, Error)]
74pub enum EngineError {
75    #[error("sqlite error: {0}")]
76    Sqlite(#[from] rusqlite::Error),
77    #[error("schema error: {0}")]
78    Schema(#[from] fathomdb_schema::SchemaError),
79    #[error("io error: {0}")]
80    Io(#[from] std::io::Error),
81    #[error("writer actor rejected request: {0}")]
82    WriterRejected(String),
83    #[error("write timed out (may still commit): {0}")]
84    WriterTimedOut(String),
85    #[error("invalid write request: {0}")]
86    InvalidWrite(String),
87    #[error("bridge error: {0}")]
88    Bridge(String),
89    #[error("capability missing: {0}")]
90    CapabilityMissing(String),
91    #[error("database locked: {0}")]
92    DatabaseLocked(String),
93    #[error("invalid configuration: {0}")]
94    InvalidConfig(String),
95    #[error(
96        "embedder not configured: call Engine::open with a non-None EmbedderChoice to regenerate vector embeddings"
97    )]
98    EmbedderNotConfigured,
99    /// Attempted to change the database-wide embedding identity while
100    /// enabled per-kind vector index schemas exist, but the caller did not
101    /// acknowledge the rebuild impact. Re-invoke with
102    /// `acknowledge_rebuild_impact = true` to proceed (which will mark the
103    /// affected kinds `stale` without triggering a rebuild).
104    #[error(
105        "changing the database-wide embedding identity would invalidate {affected_kinds} enabled vector index kinds; re-invoke with acknowledge_rebuild_impact=true"
106    )]
107    EmbeddingChangeRequiresAck {
108        /// Number of enabled per-kind vector index schemas that would be
109        /// marked stale by the identity change.
110        affected_kinds: usize,
111    },
112    /// The caller ran `semantic_search` / `raw_vector_search` against a
113    /// kind that has no enabled `vector_index_schemas` row. Configure per-kind
114    /// vector indexing via `AdminService::configure_vec_kind` first.
115    #[error(
116        "kind {kind:?} is not vector-indexed; call configure_vec_kind({kind:?}, VectorSource::Chunks) before running semantic_search/raw_vector_search"
117    )]
118    KindNotVectorIndexed {
119        /// Node kind the caller tried to search.
120        kind: String,
121    },
122    /// The caller's vector (or the embedder's output) does not match the
123    /// active embedding profile's dimension.
124    #[error("vector dimension mismatch: expected {expected}, got {actual}")]
125    DimensionMismatch {
126        /// Dimension declared by the active embedding profile.
127        expected: usize,
128        /// Dimension of the vector the caller / embedder produced.
129        actual: usize,
130    },
131}
fathomdb_engine/lib.rs

fathomdb_engine/
lib.rs
