"""Typed telematics error hierarchy.

``TelematicsError`` subclasses ``mgf.common.exceptions.AppError`` so a
consumer's top-level handler treats every device-session failure
uniformly (rule EH-01). The subclasses name the distinct failure shapes
a codec / provider raises — a consumer maps them to its own outcome
(e.g. a ``parse_status``) as it sees fit.
"""

from __future__ import annotations

from mgf.common.exceptions import AppError

__all__ = [
    "ChecksumError",
    "MalformedHandshakeError",
    "MalformedPacketError",
    "SessionClosedError",
    "TelematicsError",
    "UnknownTrackerError",
    "UnsupportedCodecError",
]


class TelematicsError(AppError):
    """Base for every device-session / codec failure."""


class MalformedPacketError(TelematicsError):
    """Preamble / length / framing was wrong — the packet can't be parsed."""


class ChecksumError(TelematicsError):
    """The packet's CRC / checksum didn't match the payload."""


class UnsupportedCodecError(TelematicsError):
    """The packet declared a codec id this decoder doesn't implement."""


class MalformedHandshakeError(TelematicsError):
    """The device's handshake (e.g. IMEI prefix) was malformed."""


class UnknownTrackerError(TelematicsError):
    """The handshake authenticated a device the registry doesn't know."""


class SessionClosedError(TelematicsError):
    """The peer closed the connection mid-read (typed translation of an
    incomplete-read / connection-reset at the socket layer)."""
