plugmem_core/
error.rs

1//! Engine error type.
2//!
3//! A panic inside the engine is a bug by definition; every failure mode is
4//! a typed variant here. Variants that only become reachable with later
5//! stages (storage, snapshot loading) are added together with those stages.
6
7use crate::id::FactId;
8
9extern crate alloc;
10
11/// Every way an engine call can fail.
12#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
13#[cfg_attr(feature = "serde", derive(serde::Serialize))]
14#[non_exhaustive]
15pub enum Error {
16    /// A pool or table would grow past its configured ceiling.
17    #[error("capacity exceeded: {what}")]
18    CapacityExceeded {
19        /// Which limit was hit (e.g. `"facts"`, `"tags per fact"`).
20        what: &'static str,
21    },
22
23    /// A single input value is larger than its configured maximum.
24    #[error("{what} too large: {len} bytes (max {max})")]
25    TooLarge {
26        /// Which input was oversized (e.g. `"text"`).
27        what: &'static str,
28        /// Actual length in bytes (or elements, per `what`).
29        len: usize,
30        /// The configured ceiling.
31        max: usize,
32    },
33
34    /// An input vector's dimension does not match `Config::dim`.
35    #[error("vector dimension mismatch: got {got}, want {want}")]
36    DimMismatch {
37        /// Dimension of the provided vector.
38        got: usize,
39        /// Dimension the database was configured with.
40        want: usize,
41    },
42
43    /// The referenced fact does not exist (or was purged).
44    #[error("fact {} not found", (.0).0)]
45    NotFound(FactId),
46
47    /// `revise` targeted a fact whose validity interval is already closed.
48    #[error("fact {} is already closed", (.0).0)]
49    AlreadyClosed(FactId),
50
51    /// A paginated read continued after the underlying catalog changed.
52    #[error("tag cursor is stale; restart without a cursor")]
53    StaleCursor,
54
55    /// A database contains vectors written before embedding-space identities
56    /// were persisted. Their model cannot be inferred safely.
57    #[error("vector space is untracked; run an explicit reembed")]
58    UntrackedVectorSpace,
59
60    /// The configured embedder belongs to a different semantic vector space
61    /// than the one recorded in the database.
62    #[error(
63        "vector space mismatch: stored {stored:?}, requested {requested:?}; run an explicit reembed"
64    )]
65    VectorSpaceMismatch {
66        /// Identity persisted with the current vectors.
67        stored: alloc::string::String,
68        /// Identity supplied by the configured embedder.
69        requested: alloc::string::String,
70    },
71
72    /// The supplied `Config` is invalid, or incompatible with the config
73    /// stored in an existing database (changing `dim` or shard counts
74    /// requires a reindex, not an open).
75    #[error("config mismatch: {0}")]
76    ConfigMismatch(&'static str),
77
78    /// A snapshot or journal failed validation.
79    #[error("corrupt input: {0}")]
80    Corrupt(&'static str),
81
82    /// The snapshot was written by an unknown format version.
83    #[error("unsupported snapshot format version {0}")]
84    UnsupportedVersion(u16),
85
86    /// An input violates a structural rule that is not a size limit
87    /// (a link without a subject entity, an empty tag, a name with no
88    /// indexable characters).
89    #[error("invalid input: {0}")]
90    Invalid(&'static str),
91
92    /// The [`Storage`](crate::storage::Storage) implementation failed;
93    /// carries the implementation error's debug rendering (the engine
94    /// stays generic and cloneable, the wrapper logs the original).
95    #[error("storage: {0}")]
96    Storage(alloc::string::String),
97
98    /// An underlying storage-structure error (bubbled up from the arena
99    /// layer with its context intact).
100    #[error("arena: {0}")]
101    Arena(#[from] plugmem_arena::Error),
102}
plugmem_core/error.rs

plugmem_core/
error.rs
