"""C7 inference runtime error taxonomy (AZ-297).

All Protocol methods raise only members of :class:`RuntimeError` (the
C7-local family — NOT stdlib :class:`builtins.RuntimeError`).
Consumers catch the family with a single
``except c7_inference.errors.RuntimeError``; implementations rewrap
third-party library exceptions (TRT C++ exceptions, ORT internal
errors, PyTorch CUDA errors) into one of these types.

Two composition-time errors live OUTSIDE the family:
- :class:`gps_denied_onboard.runtime_root.errors.RuntimeNotAvailableError`
  is raised by the factory when the requested ``BUILD_*`` is OFF.
- :class:`gps_denied_onboard.config.schema.ConfigError` is raised at
  config-load time for unknown ``runtime`` labels.
"""

from __future__ import annotations

__all__ = [
    "CalibrationCacheError",
    "EngineBuildError",
    "EngineDeserializeError",
    "EngineHashMismatchError",
    "EngineSchemaMismatchError",
    "EngineSidecarMissingError",
    "InferenceError",
    "OutOfMemoryError",
    "RuntimeError",
    "TelemetryUnavailableError",
]


class RuntimeError(Exception):  # noqa: A001  - the contract names this RuntimeError
    """Base class for the C7 inference runtime error family.

    Named ``RuntimeError`` per the contract (``inference_runtime_protocol.md``
    Shape § Error hierarchy); this shadows the stdlib name only inside
    ``c7_inference.errors``. Consumers MUST import from this module by
    fully-qualified name to avoid collision.
    """


class EngineBuildError(RuntimeError):
    """``compile_engine`` failed before producing a usable engine binary."""


class EngineDeserializeError(RuntimeError):
    """``deserialize_engine`` could not load the engine binary into memory."""


class EngineHashMismatchError(RuntimeError):
    """The sha256 of the engine file does not match
    :attr:`EngineCacheEntry.sha256_hex` (D-C10-3 / cache poisoning gate)."""


class EngineSchemaMismatchError(RuntimeError):
    """The engine's IO schema (input / output tensor names + shapes) does
    not match the runtime expectation (D-C10-7)."""


class EngineSidecarMissingError(RuntimeError):
    """The ``.sha256`` sidecar file expected next to the engine binary is
    absent or unreadable."""


class CalibrationCacheError(RuntimeError):
    """``compile_engine`` with ``precision=INT8`` could not load or write
    the calibration cache."""


class InferenceError(RuntimeError):
    """``infer`` failed during GPU execution.

    The impl MUST rewrap CUDA / TRT C++ / ORT exceptions into this
    type; raw exceptions MUST NOT escape the Protocol.
    """


class OutOfMemoryError(RuntimeError):  # noqa: A001  - the contract names this OutOfMemoryError
    """GPU OOM during ``deserialize_engine`` or ``infer``.

    Named ``OutOfMemoryError`` per the contract; this shadows the
    stdlib name only inside ``c7_inference.errors``.
    """


class TelemetryUnavailableError(RuntimeError):
    """``thermal_state`` cold-start could not bind to the
    ``tegrastats`` / ``jtop`` source.

    Steady-state telemetry absence is signalled by
    ``ThermalState.is_telemetry_available == False`` (NOT this
    exception); this error is the cold-start fail-fast.
    """
