"""One coercion, used everywhere this domain compares two datetimes.

MySQL ``DATETIME`` carries no timezone, so every datetime the ORM loads
comes back **naive** while everything the collectors and the ingest
engine construct is **aware**. Comparing the two raises
``TypeError: can't compare offset-naive and offset-aware datetimes``.

That is not a theoretical hazard here. This domain's whole job is
comparing timestamps — is this occurrence newer than what we stored,
did a later run succeed after this failure, does this fall inside the
recovery window — so the crash lands squarely on the ingest path. It
was hit twice while building the domain, in two different modules,
which is why the helper lives in one place instead of being copied a
third time.
"""
from __future__ import annotations

from datetime import UTC, datetime


def aware(dt: datetime | None) -> datetime | None:
    """Coerce a possibly-naive datetime to UTC-aware. ``None`` passes through."""
    if dt is None:
        return None
    return dt if dt.tzinfo else dt.replace(tzinfo=UTC)


def newest(*values: datetime | None) -> datetime | None:
    """The latest of several possibly-naive, possibly-``None`` datetimes.

    Returns ``None`` only when every argument is ``None``. Used where a
    row offers several candidate timestamps and the most recent one is
    the meaningful one.
    """
    coerced = [v for v in (aware(v) for v in values) if v is not None]
    return max(coerced) if coerced else None