alkgit-substrate 0.1.0

//! The substrate open/construction error surface — the wave-6 scaffold's
//! pin (ADR-024 §1's fallible-constructor posture: construction fails
//! loudly and a half-migrated store refuses service rather than degrading
//! silently).
//!
//! Not one of the core's two backend-family error types
//! ([`RegistryError`](alkgit::RegistryError),
//! [`StorageError`](alkgit::StorageError)) and deliberately without any
//! conversion into them: the backend-family variant sets are closed over
//! the failures *their families* produce, with no catch-all (backend.md
//! §`RegistryError`) — a blanket `From` here would funnel engine-specific
//! construction failures into that closed set and break the claim. The
//! substrate's constructors are assembly-time calls that happen before
//! any backend-trait call exists, so their failures never cross the trait
//! seam's `Result<_, RegistryError>`/`Result<_, StorageError>` surface
//! and never reach the wire; a dedicated type is the honest shape. The
//! migration step's failure context (ADR-024 §1's loud construction-time
//! run) rides [`OpenError::Migration`], which the migrations task
//! consumes.
//!
//! Message-only by the family posture: engine source types
//! (`rusqlite::Error`, `tokio_postgres::Error`) are not stable public
//! surface, so their text is carried in the payload — the same rule the
//! core's `RegistryError::Io`/`StorageError::Io` pins.

/// The error the substrate's constructors fail with (open, reactivity
/// start, adapter construction, construction-time migrations).
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub enum OpenError {
    /// An engine open or a reactivity start failed at construction
    /// (the substrate's open fails loudly — the family posture ADR-024
    /// §1 records as established).
    #[error("substrate engine open failed: {0}")]
    Engine(String),
    /// A construction-time migration step failed (loud — the store
    /// refuses service; ADR-024 §1). `step` is the ordered step's
    /// position; concurrent-open races do not surface here (the
    /// re-key verification swallows the benign case — ADR-024 §3).
    #[error("migration step {step} failed: {reason}")]
    Migration {
        /// The position of the failing step in the ordered set.
        step: usize,
        /// The engine failure's message (message-only — no engine
        /// source types on the surface).
        reason: String,
    },
    /// Invalid construction input (a path or options shape a
    /// constructor rejects before touching the engine).
    #[error("invalid substrate construction input: {0}")]
    Invalid(String),
}