frame-state 0.2.0

use std::error::Error;
use std::fmt;

use frame_core::capability::{CapabilityCheckError, CapabilityDenied};
use frame_core::component::ComponentId;
use haematite::{
    BranchCommitError, BranchError, BranchKind, BranchPolicyError, BranchRefError, CheckoutError,
    MergeError, NodeError, SnapshotError, StoreError, TreeError,
};

use crate::types::{MergePolicy, ReferenceTargetState};

/// A durable branch/meta mismatch that boot reconciliation refuses to guess at.
#[derive(Debug)]
pub enum ReconcileInconsistency {
    /// A component Namespace ref exists with no corresponding meta record.
    BranchWithoutMeta {
        /// Durable branch name observed.
        branch: String,
        /// Persisted kind observed.
        kind: BranchKind,
    },
    /// Meta says Active but the required namespace ref is absent.
    ActiveWithoutBranch {
        /// Component named by the durable Active record.
        component: ComponentId,
    },
    /// Meta says Archived but a same-named namespace ref is present.
    ArchivedWithBranch {
        /// Component named by both conflicting durable records.
        component: ComponentId,
    },
    /// A removed namespace has no deterministic archive snapshot.
    RemovedWithoutSnapshot {
        /// Component whose branch was removed.
        component: ComponentId,
        /// Snapshot name that must have been pinned first.
        snapshot: String,
    },
    /// A deterministic snapshot name points at a different root.
    SnapshotRootMismatch {
        /// Snapshot name whose existing binding was inspected.
        snapshot: String,
        /// Root required by the archive transition.
        expected: haematite::Hash,
        /// Root already bound under that name.
        actual: haematite::Hash,
    },
}

impl fmt::Display for ReconcileInconsistency {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::BranchWithoutMeta { branch, kind } => write!(
                formatter,
                "durable branch '{branch}' ({kind}) has no frame-state meta record"
            ),
            Self::ActiveWithoutBranch { component } => {
                write!(
                    formatter,
                    "active component {component} has no Namespace branch"
                )
            }
            Self::ArchivedWithBranch { component } => write!(
                formatter,
                "archived component {component} still has a Namespace branch"
            ),
            Self::RemovedWithoutSnapshot {
                component,
                snapshot,
            } => write!(
                formatter,
                "component {component} branch was removed without required snapshot '{snapshot}'"
            ),
            Self::SnapshotRootMismatch {
                snapshot,
                expected,
                actual,
            } => write!(
                formatter,
                "snapshot '{snapshot}' names root {actual}, expected {expected}"
            ),
        }
    }
}

impl Error for ReconcileInconsistency {}

/// Typed failures from component storage, preserving every substrate error.
#[derive(Debug)]
pub enum StateError {
    /// Filesystem setup failed outside a haematite operation.
    Io(std::io::Error),
    /// Node-store operation failed.
    Store(StoreError),
    /// Empty-node construction failed.
    Node(NodeError),
    /// Tree traversal failed.
    Tree(TreeError),
    /// Branch commit/lifecycle failed outside a more specific category.
    BranchCommit(BranchCommitError),
    /// Engine namespace policy refused an operation, retaining names and kinds.
    BranchPolicy(BranchPolicyError),
    /// Engine content merge failed.
    Merge(MergeError),
    /// Durable branch-ref operation failed.
    BranchRef(BranchRefError),
    /// Branch handle operation failed.
    Branch(BranchError),
    /// Snapshot registry operation failed.
    Snapshot(SnapshotError),
    /// Historical checkout failed.
    Checkout(CheckoutError),
    /// The supplied checker belongs to a different component than the handle.
    CapabilityBinding {
        /// Component incarnation represented by the storage handle.
        handle_component: ComponentId,
        /// Component whose authority the supplied checker would evaluate.
        checker_component: ComponentId,
    },
    /// A fresh check denied this resolution, preserved verbatim from frame-core.
    CapabilityDenied(CapabilityDenied),
    /// A fresh check could not produce or publish its verdict.
    CapabilityCheck(CapabilityCheckError),
    /// The named target has no active namespace to resolve.
    DanglingReference {
        /// Component named by the link.
        target: ComponentId,
        /// Durable target state observed after authority was granted.
        state: ReferenceTargetState,
    },
    /// Internal synchronization was poisoned by a prior panic.
    SynchronizationPoisoned,
    /// No schema was declared before install.
    SchemaNotDeclared {
        /// Component whose install lacks a declaration.
        component: ComponentId,
    },
    /// A schema was already fixed for this component's current lifecycle.
    SchemaAlreadyDeclared {
        /// Component whose pending declaration would be replaced.
        component: ComponentId,
    },
    /// The published engine cannot execute the declared vocabulary entry.
    UnsupportedPolicy {
        /// Policy refused at schema declaration.
        policy: MergePolicy,
    },
    /// A custom policy named a resolver absent at declaration time.
    ResolverNotRegistered {
        /// Stable resolver name that was not registered.
        name: String,
    },
    /// A resolver registration would silently replace an existing function.
    ResolverAlreadyRegistered {
        /// Stable resolver name already bound in this process.
        name: String,
    },
    /// An install is already executing for this identity.
    InstallInProgress {
        /// Component with an active install transition.
        component: ComponentId,
    },
    /// An archive is already executing for this identity.
    ArchiveInProgress {
        /// Component with an active archive transition.
        component: ComponentId,
    },
    /// A fork or merge is already executing for this identity.
    WorkInProgress {
        /// Component with an active Work operation.
        component: ComponentId,
    },
    /// Install was requested for an active namespace.
    AlreadyActive {
        /// Component whose namespace is already Active.
        component: ComponentId,
    },
    /// The component has no active namespace.
    NotActive {
        /// Component for which active storage was required.
        component: ComponentId,
    },
    /// A handle's captured incarnation no longer owns the branch name.
    StaleHandle {
        /// Component whose name was reused.
        component: ComponentId,
        /// Incarnation captured by the handle.
        held: u64,
        /// Durable current incarnation.
        current: u64,
    },
    /// A requested Work branch is not outstanding.
    WorkNotFound {
        /// Durable Work branch name that was absent.
        branch: String,
    },
    /// A Work handle came from another store, component, or incarnation.
    ForeignWorkHandle,
    /// A branch/archive key did not have Frame's fixed-width encoding.
    CorruptRecord {
        /// Exact codec or durable-invariant failure.
        detail: String,
    },
    /// Boot found a durable state it cannot safely repair.
    Reconcile(ReconcileInconsistency),
}

impl fmt::Display for StateError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Io(error) => write!(formatter, "frame-state filesystem error: {error}"),
            Self::Store(error) => write!(formatter, "frame-state node store error: {error}"),
            Self::Node(error) => write!(formatter, "frame-state node encoding error: {error}"),
            Self::Tree(error) => write!(formatter, "frame-state tree traversal error: {error}"),
            Self::BranchCommit(error) => error.fmt(formatter),
            Self::BranchPolicy(error) => error.fmt(formatter),
            Self::Merge(error) => error.fmt(formatter),
            Self::BranchRef(error) => error.fmt(formatter),
            Self::Branch(error) => error.fmt(formatter),
            Self::Snapshot(error) => error.fmt(formatter),
            Self::Checkout(error) => error.fmt(formatter),
            Self::CapabilityBinding {
                handle_component,
                checker_component,
            } => fmt_capability_binding(formatter, *handle_component, *checker_component),
            Self::CapabilityDenied(denial) => fmt_capability_denied(formatter, denial),
            Self::CapabilityCheck(error) => error.fmt(formatter),
            Self::DanglingReference { target, state } => {
                fmt_dangling_reference(formatter, *target, *state)
            }
            Self::SynchronizationPoisoned => {
                formatter.write_str("frame-state synchronization poisoned")
            }
            Self::SchemaNotDeclared { component } => {
                write!(
                    formatter,
                    "component {component} has no declared storage schema"
                )
            }
            Self::SchemaAlreadyDeclared { component } => {
                write!(
                    formatter,
                    "component {component} storage schema is already declared"
                )
            }
            Self::UnsupportedPolicy { policy } => {
                write!(
                    formatter,
                    "haematite 0.5.0 cannot execute merge policy {policy}"
                )
            }
            Self::ResolverNotRegistered { name } => {
                write!(
                    formatter,
                    "custom merge resolver '{name}' is not registered"
                )
            }
            Self::ResolverAlreadyRegistered { name } => {
                write!(
                    formatter,
                    "custom merge resolver '{name}' is already registered"
                )
            }
            Self::InstallInProgress { component } => {
                write!(
                    formatter,
                    "component {component} storage install is in progress"
                )
            }
            Self::ArchiveInProgress { component } => {
                write!(
                    formatter,
                    "component {component} storage archive is in progress"
                )
            }
            Self::WorkInProgress { component } => {
                write!(
                    formatter,
                    "component {component} Work operation is in progress"
                )
            }
            Self::AlreadyActive { component } => {
                write!(formatter, "component {component} storage is already active")
            }
            Self::NotActive { component } => {
                write!(formatter, "component {component} storage is not active")
            }
            Self::StaleHandle {
                component,
                held,
                current,
            } => write!(
                formatter,
                "stale handle for component {component}: held incarnation {held}, current incarnation {current}"
            ),
            Self::WorkNotFound { branch } => {
                write!(formatter, "Work branch '{branch}' is not outstanding")
            }
            Self::ForeignWorkHandle => formatter
                .write_str("Work handle belongs to another store, component, or incarnation"),
            Self::CorruptRecord { detail } => {
                write!(formatter, "corrupt frame-state record: {detail}")
            }
            Self::Reconcile(error) => error.fmt(formatter),
        }
    }
}

fn fmt_capability_binding(
    formatter: &mut fmt::Formatter<'_>,
    handle_component: ComponentId,
    checker_component: ComponentId,
) -> fmt::Result {
    write!(
        formatter,
        "capability checker for component {checker_component} cannot resolve through component {handle_component}'s storage handle"
    )
}

fn fmt_capability_denied(
    formatter: &mut fmt::Formatter<'_>,
    denial: &CapabilityDenied,
) -> fmt::Result {
    write!(
        formatter,
        "cross-component resolution denied for component {}: kind {:?}, scope {:?}, declared {}",
        denial.component_id, denial.kind, denial.scope, denial.declared
    )
}

fn fmt_dangling_reference(
    formatter: &mut fmt::Formatter<'_>,
    target: ComponentId,
    state: ReferenceTargetState,
) -> fmt::Result {
    write!(
        formatter,
        "cross-component reference target {target} is {state}"
    )
}

impl Error for StateError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            Self::Io(error) => Some(error),
            Self::Store(error) => Some(error),
            Self::Node(error) => Some(error),
            Self::Tree(error) => Some(error),
            Self::BranchCommit(error) => Some(error),
            Self::BranchPolicy(error) => Some(error),
            Self::Merge(error) => Some(error),
            Self::BranchRef(error) => Some(error),
            Self::Branch(error) => Some(error),
            Self::Snapshot(error) => Some(error),
            Self::Checkout(error) => Some(error),
            Self::CapabilityCheck(error) => Some(error),
            Self::Reconcile(error) => Some(error),
            _ => None,
        }
    }
}

impl From<std::io::Error> for StateError {
    fn from(error: std::io::Error) -> Self {
        Self::Io(error)
    }
}
impl From<StoreError> for StateError {
    fn from(error: StoreError) -> Self {
        Self::Store(error)
    }
}
impl From<NodeError> for StateError {
    fn from(error: NodeError) -> Self {
        Self::Node(error)
    }
}
impl From<TreeError> for StateError {
    fn from(error: TreeError) -> Self {
        Self::Tree(error)
    }
}
impl From<BranchRefError> for StateError {
    fn from(error: BranchRefError) -> Self {
        Self::BranchRef(error)
    }
}
impl From<BranchError> for StateError {
    fn from(error: BranchError) -> Self {
        Self::Branch(error)
    }
}
impl From<SnapshotError> for StateError {
    fn from(error: SnapshotError) -> Self {
        Self::Snapshot(error)
    }
}
impl From<CheckoutError> for StateError {
    fn from(error: CheckoutError) -> Self {
        Self::Checkout(error)
    }
}
impl From<CapabilityCheckError> for StateError {
    fn from(error: CapabilityCheckError) -> Self {
        Self::CapabilityCheck(error)
    }
}
impl From<ReconcileInconsistency> for StateError {
    fn from(error: ReconcileInconsistency) -> Self {
        Self::Reconcile(error)
    }
}

impl From<BranchCommitError> for StateError {
    fn from(error: BranchCommitError) -> Self {
        match error {
            BranchCommitError::Policy(policy) => Self::BranchPolicy(policy),
            BranchCommitError::Merge(merge) => Self::Merge(merge),
            other => Self::BranchCommit(other),
        }
    }
}