"""C1 VioStrategy error taxonomy (AZ-331).

Every ``VioStrategy`` method raises only members of :class:`VioError`.
Lower-level exceptions from OpenCV / OKVIS2 / VINS-Mono / GTSAM MUST
be caught and rewrapped — the contract closes the error envelope so
consumers can ``except VioError`` once and handle the family.

:class:`VioDegradedError` is documented but is **not raised** during
the normal degraded-operation path: degraded operation returns a
``VioOutput`` with inflated covariance and ``VioHealth.state == DEGRADED``.
The error type exists for the rare degraded→fatal transition.

A separate composition-time error
(:class:`gps_denied_onboard.runtime_root.errors.StrategyNotAvailableError`)
lives outside this family — it is raised by the factory, not by a
``VioStrategy`` method.
"""

from __future__ import annotations

__all__ = [
    "VioDegradedError",
    "VioError",
    "VioFatalError",
    "VioInitializingError",
]


class VioError(Exception):
    """Base class for the C1 VIO error family.

    All three documented subtypes are children. Consumers catch the
    family with ``except c1_vio.errors.VioError as e``.
    """


class VioInitializingError(VioError):
    """Raised while ``VioHealth.state == INIT`` and the strategy has no
    pose to emit.

    C5 fusion catches this and falls back to the FC IMU prior until
    the strategy reports ``TRACKING``.
    """


class VioDegradedError(VioError):
    """Raised on the rare degraded→fatal transition.

    The normal degraded-operation path is NOT this exception — it is
    a ``VioOutput`` with inflated covariance + ``VioHealth.state ==
    DEGRADED``. This type exists only so consumer ``except VioError``
    wrappers can name the family member explicitly.
    """


class VioFatalError(VioError):
    """Raised once ``consecutive_lost`` exceeds the configured threshold
    (default 9) or on irrecoverable backend init failure during
    :meth:`VioStrategy.reset_to_warm_start`.

    The AC-5.2 fallback path engages once this fires: the camera
    ingest loop stops feeding the strategy and the watchdog flips
    the composition root into FC-IMU-only mode.
    """
