// file: crates/ksp-store-postgres-lib/src/error.rs
// version: 9

/// Stable KSP error code reserved for PostgreSQL retention transitions that require unsupported physical compaction.
pub const ERROR_CODE_POSTGRES_RETENTION_COMPACTION_UNSUPPORTED: ksp_store_api::ErrorCode =
    ksp_store_api::ErrorCode::new("store", "postgres_retention_compaction_unsupported");

/// Safe backend-local classification used by the Store facade for stable error mapping.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum PostgresBackendErrorKind {
    /// The supplied physical PostgreSQL configuration is unsupported or malformed.
    ConfigInvalid,
    /// A physical PostgreSQL connection could not be established.
    ConnectFailed,
    /// A bounded pool wait, create or recycle operation reached its deadline.
    PoolTimeout,
    /// A lightweight PostgreSQL health/readiness probe failed without exposing server text or SQL.
    HealthFailed,
    /// A canonical RAW identity or observation key already exists with divergent durable content.
    Conflict,
    /// PostgreSQL returned stored RAW data that cannot be represented by the stable Store API contract.
    DataInvalid,
    /// PostgreSQL migration/bootstrap execution failed without exposing server text or SQL.
    MigrationFailed,
    /// The requested RAW page size cannot be represented by the physical PostgreSQL LIMIT domain.
    PageLimitUnsupported,
    /// Applied PostgreSQL migration history diverges from the embedded immutable KSP history.
    MigrationMismatch,
    /// A bounded backend-private RAW query or opaque cursor is invalid for the requested navigation context.
    QueryInvalid,
    /// A PostgreSQL RAW read statement failed without exposing server text, SQL or bind values.
    ReadFailed,
    /// A RAW write requires an existing canonical reference that is not durable.
    ReferenceNotFound,
    /// The requested RAW retention transition requires a compacted representation unsupported by PostgreSQL.
    RetentionCompactionUnsupported,
    /// The database schema history contains a migration newer than this runtime understands.
    SchemaNewer,
    /// Explicit backend shutdown did not drain inside the supplied deadline.
    ShutdownTimeout,
    /// Verified TLS configuration or negotiation could not be established.
    TlsFailed,
    /// A PostgreSQL RAW write statement or transaction failed without exposing server text, SQL or bind values.
    WriteFailed,
    /// A network-scoped RAW operation targeted a network different from the backend binding.
    WrongNetwork,
}

/// Redacted PostgreSQL backend error carrying only a safe classification and static lifecycle phase.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct PostgresBackendError {
    kind: PostgresBackendErrorKind,
    phase: &'static str,
}

impl PostgresBackendError {
    /// Creates one backend error without retaining external error text or sensitive connection material.
    #[must_use]
    pub(crate) const fn new(kind: PostgresBackendErrorKind, phase: &'static str) -> Self {
        return Self { kind, phase };
    }

    /// Returns the safe backend-local error classification.
    #[must_use]
    pub const fn kind(&self) -> PostgresBackendErrorKind {
        return self.kind;
    }

    /// Returns the static safe lifecycle phase associated with the failure.
    #[must_use]
    pub const fn phase(&self) -> &'static str {
        return self.phase;
    }
}