"""Public exception hierarchy for underframe_deflection.

Integrators should catch `DeflectionError` for any algorithm failure that
should be surfaced to the user. Subclasses indicate what specifically went
wrong so callers can render targeted error messages.

Non-fatal data-quality issues are not raised as exceptions; they are
reported via `DeflectionResult.quality_flags`.
"""

from __future__ import annotations


class DeflectionError(Exception):
    """Base class for all errors raised by the deflection pipeline."""


class InvalidPointCloudError(DeflectionError):
    """Raised when the input point cloud is malformed or unreadable."""


class InsufficientPointsError(DeflectionError):
    """Raised when the input has too few points to run the pipeline."""


class FrameInferenceError(DeflectionError):
    """Raised when the vehicle reference frame cannot be determined."""


class UnsupportedFormatError(InvalidPointCloudError):
    """Raised when the input file extension is not supported."""


__all__ = [
    "DeflectionError",
    "InvalidPointCloudError",
    "InsufficientPointsError",
    "FrameInferenceError",
    "UnsupportedFormatError",
]