"""C3.5 ``ConditionalRefiner`` error taxonomy (AZ-348).

The family is intentionally small: per-candidate failures are
handled inside C3 (drop-and-continue); at C3.5 the only failure
mode is the AdHoP backbone (TensorRT exception, OOM, NaN, shape
mismatch) and it is contained within the strategy via
passthrough fall-through (contract Invariant 4) — never re-raised
out of :meth:`refine_if_needed`.

:class:`RefinerConfigError` is the composition-root rejection at
startup; never raised per-frame.
"""

from __future__ import annotations

__all__ = [
    "RefinerBackboneError",
    "RefinerConfigError",
    "RefinerError",
]


class RefinerError(Exception):
    """Base class for all C3.5 refinement-strategy errors."""


class RefinerBackboneError(RefinerError):
    """AdHoP backbone forward-pass failed.

    TensorRT exception, OOM, NaN, shape mismatch. Caught inside
    :meth:`ConditionalRefiner.refine_if_needed`, converted to
    passthrough fall-through (Invariant 4), logged at ERROR with
    one FDR record. NEVER re-raised out of the strategy.
    """


class RefinerConfigError(RefinerError):
    """Composition-root rejected the refiner config.

    Unknown strategy label OR invalid threshold (``<= 0``). Raised
    at startup ONLY — never per-frame. The composition root logs
    ERROR (``kind="c3_5.refiner.strategy_unknown"`` or
    ``kind="c3_5.refiner.invalid_threshold"``) before raising.
    """
