"""``FrameSource`` error taxonomy (AZ-398 v1.0.0).

Per the replay contract
(``_docs/02_document/contracts/replay/replay_protocol.md``), every
transient I/O failure on the camera path MUST surface as
:class:`FrameSourceError` (Invariant 4 — replay must be deterministic,
silent ``None`` drops are forbidden).

The two-class hierarchy mirrors the C6/C7/C1 component taxonomies:

- :class:`FrameSourceError` — operational failures during streaming
  (decode error, device disconnect, out-of-order frame).
- :class:`FrameSourceConfigError` — composition-time failures (build
  flag OFF, missing dependency, invalid config).
"""

from __future__ import annotations


class FrameSourceError(RuntimeError):
    """Transient or fatal failure during frame ingestion.

    Examples:

    - A corrupt H.264 keyframe in the replay video file.
    - An ordering violation: ``next_frame()`` returned a frame whose
      ``monotonic_ns`` is < the previous frame's (Invariant 3).
    - A USB camera disconnect mid-flight (live source).

    The error message MUST identify the frame index or timestamp where
    the failure occurred so the operator can correlate against the
    upstream recording.
    """


class FrameSourceConfigError(RuntimeError):
    """Composition-time configuration failure for a frame source.

    Examples:

    - ``BUILD_VIDEO_FILE_FRAME_SOURCE=OFF`` and the binary tried to
      construct :class:`VideoFileFrameSource`.
    - The configured video path does not exist or is not readable.
    - OpenCV is not importable (Tier-0 / docker-minimal build).
    """


__all__ = ["FrameSourceError", "FrameSourceConfigError"]
