"""C4 PoseEstimator error hierarchy (AZ-355).

Per the C4 contract (Invariant 9) and AC-4: ``PnpFailureError`` is
the ONLY non-warning exception that escapes ``PoseEstimator.estimate``.
``CovarianceDegradedWarning`` is a Python ``Warning`` (NOT an
``Exception``) — emitted via ``warnings.warn(...)`` at the start of
every Jacobian-path frame so a ``try / except Exception`` block in
the caller does NOT swallow it. R10 acceptance for the C4 contract
hangs on this distinction.

``PoseEstimatorConfigError`` is raised by the composition-root
factory (``runtime_root.pose_factory.build_pose_estimator``) for
unknown strategies, missing dependencies, or thread-binding
violations.
"""

from __future__ import annotations

__all__ = [
    "CovarianceDegradedWarning",
    "PnpFailureError",
    "PoseEstimatorConfigError",
    "PoseEstimatorError",
]


class PoseEstimatorError(Exception):
    """Base class for all C4 ``PoseEstimator`` errors."""


class PnpFailureError(PoseEstimatorError):
    """RANSAC convergence failure or degenerate match geometry.

    Per Invariant 9 this is NEVER converted to a fallback
    ``PoseEstimate`` inside C4 — the fallback decision belongs to
    C5 (AZ-385's source-label gate + AZ-388's no-estimate watchdog).
    """


class PoseEstimatorConfigError(PoseEstimatorError):
    """Composition-root factory rejection.

    Raised by ``build_pose_estimator`` for unknown ``config.pose.strategy``
    values, missing constructor dependencies, or attempted thread-binding
    violations.
    """


class CovarianceDegradedWarning(Warning):
    """Per-frame thermal-state-driven Jacobian-path engagement.

    NOT an exception. Emitted via ``warnings.warn(...)`` by the
    Jacobian path (AZ-361 / D-CROSS-LATENCY-1). Per AC-4 callers MUST
    use ``warnings.catch_warnings(...)`` or
    ``warnings.simplefilter("once", CovarianceDegradedWarning)`` if
    they need to observe these warnings — a ``try / except Exception``
    block does NOT catch them, because ``Warning`` does not subclass
    ``Exception`` in Python.
    """
