alkgit_substrate/error.rs
1//! The substrate open/construction error surface — the wave-6 scaffold's
2//! pin (ADR-024 §1's fallible-constructor posture: construction fails
3//! loudly and a half-migrated store refuses service rather than degrading
4//! silently).
5//!
6//! Not one of the core's two backend-family error types
7//! ([`RegistryError`](alkgit::RegistryError),
8//! [`StorageError`](alkgit::StorageError)) and deliberately without any
9//! conversion into them: the backend-family variant sets are closed over
10//! the failures *their families* produce, with no catch-all (backend.md
11//! §`RegistryError`) — a blanket `From` here would funnel engine-specific
12//! construction failures into that closed set and break the claim. The
13//! substrate's constructors are assembly-time calls that happen before
14//! any backend-trait call exists, so their failures never cross the trait
15//! seam's `Result<_, RegistryError>`/`Result<_, StorageError>` surface
16//! and never reach the wire; a dedicated type is the honest shape. The
17//! migration step's failure context (ADR-024 §1's loud construction-time
18//! run) rides [`OpenError::Migration`], which the migrations task
19//! consumes.
20//!
21//! Message-only by the family posture: engine source types
22//! (`rusqlite::Error`, `tokio_postgres::Error`) are not stable public
23//! surface, so their text is carried in the payload — the same rule the
24//! core's `RegistryError::Io`/`StorageError::Io` pins.
25
26/// The error the substrate's constructors fail with (open, reactivity
27/// start, adapter construction, construction-time migrations).
28#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
29pub enum OpenError {
30 /// An engine open or a reactivity start failed at construction
31 /// (the substrate's open fails loudly — the family posture ADR-024
32 /// §1 records as established).
33 #[error("substrate engine open failed: {0}")]
34 Engine(String),
35 /// A construction-time migration step failed (loud — the store
36 /// refuses service; ADR-024 §1). `step` is the ordered step's
37 /// position; concurrent-open races do not surface here (the
38 /// re-key verification swallows the benign case — ADR-024 §3).
39 #[error("migration step {step} failed: {reason}")]
40 Migration {
41 /// The position of the failing step in the ordered set.
42 step: usize,
43 /// The engine failure's message (message-only — no engine
44 /// source types on the surface).
45 reason: String,
46 },
47 /// Invalid construction input (a path or options shape a
48 /// constructor rejects before touching the engine).
49 #[error("invalid substrate construction input: {0}")]
50 Invalid(String),
51}