"""Service layer for Meter epoch CRUD, swap/close, and time-range lookup.

All functions accept an explicit SQLAlchemy Session; callers are responsible
for committing or rolling back the transaction.

Design decisions
----------------
- ``meter_at``:       half-open interval ``[started_at, ended_at)`` lookup;
  returns the meter whose epoch covers *ts* for the given commodity.
  SQLite naive datetime is normalised via ``_as_utc()`` before comparison.

- ``declare_meter``:  validates that the new ``started_at`` is **not earlier
  than** the current active meter's ``started_at`` (rejects back-dating below
  the active meter's own start).  Equal timestamps are allowed because the
  typical "swap now" use-case sets ``started_at`` to the current moment, which
  coincides with the active meter's ``started_at`` only in degenerate test
  scenarios — but blocking equal values would make that workflow impossible.
  The old active meter is closed (``ended_at = started_at``) and a new active
  meter is opened in the same operation, guaranteeing continuity: the old
  meter's ``ended_at`` equals the new meter's ``started_at`` (contiguous,
  no gap, no overlap).

- ``update_meter``:   when ``started_at`` is modified, the service keeps the
  timeline contiguous by also updating the **previous** meter's ``ended_at``
  (the one whose ``ended_at`` matched the old ``started_at``) to the new
  ``started_at``.  Validation ensures the new ``started_at``:
    * is strictly after the previous meter's own ``started_at``
      (cannot push the boundary before the previous meter even started);
    * is strictly before the current meter's ``ended_at``, if set
      (cannot push the boundary past where the current meter was already
      closed).

- Mutual exclusion (at most one active meter per commodity) is enforced by the
  service layer; no DB-level unique partial index is added to keep migrations
  simple and to allow the application to return a meaningful error message.

SQLite timezone note
--------------------
SQLite stores ``DateTime(timezone=True)`` columns as naive UTC strings; on
read-back they come out as **timezone-naive** datetimes.  Wherever this code
compares timestamps from the DB against timezone-aware values, it calls
``_as_utc()`` to make both sides comparable without tripping on
"offset-naive vs offset-aware" TypeErrors.
"""

from __future__ import annotations

import logging
from datetime import UTC, datetime
from typing import Optional

from sqlalchemy import select
from sqlalchemy.orm import Session

from app.models.energy import Meter

logger = logging.getLogger(__name__)


# ---------------------------------------------------------------------------
# Internal helpers
# ---------------------------------------------------------------------------


def _as_utc(dt: datetime) -> datetime:
    """Return *dt* as a timezone-aware UTC datetime.

    SQLite's ``DateTime(timezone=True)`` column type stores datetimes as naive
    UTC strings and gives them back as naive datetimes on read.  This helper
    re-attaches the UTC timezone info when it is missing, making cross-origin
    comparisons safe.
    """
    if dt.tzinfo is None:
        return dt.replace(tzinfo=UTC)
    return dt


# ---------------------------------------------------------------------------
# Custom exceptions
# ---------------------------------------------------------------------------


class MeterError(ValueError):
    """Base class for meter service validation errors."""


class MeterOverlapError(MeterError):
    """Raised when a new meter's ``started_at`` would create an overlap or backdate.

    Specifically: the new meter's ``started_at`` must be greater than or equal
    to the current active meter's ``started_at``.  Allowing a value strictly
    earlier than the active meter's start would mean the new epoch begins before
    the current one, which is chronologically inconsistent.
    """


class MeterIntervalError(MeterError):
    """Raised when an ``update_meter`` call would produce an inconsistent interval.

    Examples of inconsistent intervals:
    - New ``started_at`` ≥ this meter's ``ended_at`` (epoch would be empty/inverted).
    - New ``started_at`` ≤ the previous meter's own ``started_at`` (previous meter
      would become empty/inverted after its ``ended_at`` is updated).
    """


# ---------------------------------------------------------------------------
# Internal query helpers
# ---------------------------------------------------------------------------


def _active_meter(session: Session, commodity: str) -> Optional[Meter]:
    """Return the current active (``ended_at IS NULL``) meter for *commodity*, or None."""
    return session.execute(
        select(Meter)
        .where(
            Meter.commodity == commodity,
            Meter.ended_at.is_(None),
        )
        .limit(1)
    ).scalar_one_or_none()


def _meter_before(session: Session, meter: Meter) -> Optional[Meter]:
    """Return the meter whose ``ended_at`` equals *meter*'s ``started_at``.

    This is the meter that was closed when *meter* was opened; its ``ended_at``
    needs to stay equal to *meter*'s ``started_at`` to maintain timeline
    continuity.  Returns None if *meter* is the first epoch for its commodity.

    The lookup compares naive/aware datetimes via string to avoid SQLite timezone
    quirks: both are formatted as ISO 8601 UTC strings for the WHERE clause.
    We rely on the fact that the service layer always stores the same timestamp
    object as both ``prev.ended_at`` and ``new.started_at``, so their string
    representations are identical.
    """
    # Normalise the target to a tz-aware UTC datetime for comparison.
    # We scan in Python (rather than SQL) to avoid SQLite naive-vs-aware
    # mismatch issues when comparing DateTime columns against tz-aware values.
    target = _as_utc(meter.started_at)

    # Fetch all closed meters of the same commodity and find the one whose
    # ended_at equals this meter's started_at (the standard contiguous handoff).
    candidates = session.execute(
        select(Meter)
        .where(
            Meter.commodity == meter.commodity,
            Meter.ended_at.is_not(None),
        )
    ).scalars().all()

    for candidate in candidates:
        if candidate.id == meter.id:
            continue
        candidate_ended = _as_utc(candidate.ended_at)
        if candidate_ended == target:
            return candidate

    return None


# ---------------------------------------------------------------------------
# Core service functions
# ---------------------------------------------------------------------------


def meter_at(
    session: Session,
    ts: datetime,
    commodity: str = "electricity",
) -> Optional[Meter]:
    """Return the meter epoch that covers *ts* for *commodity*.

    A meter covers *ts* when:
        ``started_at ≤ ts`` AND (``ended_at IS NULL`` OR ``ts < ended_at``)

    This is the standard half-open interval ``[started_at, ended_at)`` lookup,
    consistent with ``active_contract_version_at`` in ``contracts.py``.

    Returns ``None`` when no meter covers *ts* (e.g. before the first epoch
    was declared, or after a gap).

    Parameters
    ----------
    session:
        Active SQLAlchemy session (read-only usage).
    ts:
        UTC datetime to look up.
    commodity:
        Energy commodity (default ``"electricity"``).

    Returns
    -------
    Meter | None

    Implementation note — why the upper bound is pushed into SQL
    ------------------------------------------------------------
    When ``declare_meter`` is called with ``started_at == active.started_at``
    (the "equal-timestamp swap" allowed by §3.5), the old meter is closed as a
    zero-width epoch ``[T0, T0)`` and the new active meter also has
    ``started_at == T0``.  Two rows share the same ``started_at``; SQLite's
    row-ordering for ``ORDER BY started_at DESC LIMIT 1`` is then determined by
    rowid (i.e. insertion order), which returns the older zero-width row first.

    If the upper bound were checked in Python *after* fetching that one row, the
    condition ``ts < ended_at`` would be False for **any** ``ts >= T0`` (because
    ``ended_at == T0``), causing the function to return ``None`` and making the
    new active meter permanently invisible.

    Pushing both bounds into the SQL ``WHERE`` clause eliminates the ambiguity:
    the zero-width row is excluded by ``ts < ended_at`` before ``LIMIT 1`` is
    applied, so only the genuinely covering row survives.

    SQLite naive-vs-aware datetime note: SQLAlchemy's SQLite dialect strips the
    ``tzinfo`` from aware datetimes when binding parameters (it does *not*
    convert to UTC first).  Since all datetimes in this codebase are UTC (either
    naive-UTC from the DB or aware-UTC from ``datetime.now(UTC)``), stripping
    the tzinfo leaves the wall-clock value unchanged and comparisons remain
    correct.  This is consistent with how ``contracts.py`` handles the same
    situation (see OBS 2 in the M7-T02 review notes).
    """
    # Push both the lower and upper bounds into the SQL WHERE clause so that
    # zero-width epochs (ended_at == started_at) are excluded *before* LIMIT 1
    # is applied.  This prevents an equal-timestamp swap from making the new
    # active meter invisible (see implementation note above).
    stmt = (
        select(Meter)
        .where(
            Meter.commodity == commodity,
            Meter.started_at <= ts,
            (Meter.ended_at.is_(None)) | (Meter.ended_at > ts),
        )
        .order_by(Meter.started_at.desc())
        .limit(1)
    )
    return session.execute(stmt).scalar_one_or_none()


def declare_meter(
    session: Session,
    *,
    label: str,
    started_at: datetime,
    reason: str,
    commodity: str = "electricity",
    note: Optional[str] = None,
) -> Meter:
    """Declare a meter swap or initial meter epoch.

    Closes the current active meter for *commodity* (if one exists) by setting
    its ``ended_at`` to *started_at*, then opens a new active meter.  The
    resulting timeline is **contiguous**: old meter's ``ended_at`` equals new
    meter's ``started_at``.

    If there is no current active meter (first-ever declaration for this
    commodity), the new meter is simply opened without closing anything.

    Validation
    ----------
    - If a current active meter exists, *started_at* must be **≥** that meter's
      own ``started_at``.  A value strictly earlier would place the new epoch
      entirely before the current active meter, which is a chronological
      contradiction ("back-dating before the active epoch's start").  Raises
      ``MeterOverlapError`` when this constraint is violated.

    Note: equal timestamps (``started_at == active.started_at``) are allowed
    because that scenario effectively replaces the current meter at the same
    logical moment (e.g. correcting a mis-entry), which is a valid use-case.
    The old meter is then closed with ``ended_at == started_at`` (a zero-width
    epoch), which is intentional and auditable.

    Parameters
    ----------
    session:
        Active SQLAlchemy session.  Caller must commit after this returns.
    label:
        Human-readable label for the new meter.
    started_at:
        UTC datetime at which this meter epoch starts.  May be in the past.
    reason:
        Why this epoch was created (``"initial"``, ``"meter_swap"``,
        ``"home_move"``, or ``"other"``).
    commodity:
        Energy commodity (default ``"electricity"``).
    note:
        Optional free-form note.

    Returns
    -------
    Meter
        The newly created, not-yet-committed active meter.

    Raises
    ------
    MeterOverlapError
        If *started_at* is strictly earlier than the current active meter's
        ``started_at`` (chronological backdate below the active epoch's start).
    """
    active = _active_meter(session, commodity)

    if active is not None:
        # Reject back-dating: new started_at must be ≥ current active's started_at.
        if _as_utc(started_at) < _as_utc(active.started_at):
            raise MeterOverlapError(
                f"New meter started_at ({started_at.isoformat()}) must be ≥ the current "
                f"active {commodity!r} meter's started_at "
                f"({active.started_at.isoformat()}).  "
                "Declare a started_at on or after the active meter's start to avoid "
                "a chronologically inconsistent epoch ordering."
            )
        # Close the current active meter at the swap point (contiguous handoff).
        active.ended_at = started_at
        logger.info(
            "Closed active %r meter id=%d (ended_at=%s)",
            commodity,
            active.id,
            started_at.isoformat(),
        )

    now = datetime.now(UTC)
    new_meter = Meter(
        label=label,
        commodity=commodity,
        started_at=started_at,
        ended_at=None,
        reason=reason,
        note=note,
        created_at=now,
    )
    session.add(new_meter)

    logger.info(
        "Declared new %r meter %r (started_at=%s, reason=%s)",
        commodity,
        label,
        started_at.isoformat(),
        reason,
    )
    return new_meter


def list_meters(
    session: Session,
    commodity: Optional[str] = None,
) -> list[Meter]:
    """List all meter epochs, ordered by started_at ascending.

    Active meters (``ended_at IS NULL``) sort naturally to the end of the
    timeline since they have the latest ``started_at``.  Within a single
    commodity, the ascending ``started_at`` order reflects the historical
    sequence of installed meters.

    Parameters
    ----------
    session:
        Active SQLAlchemy session (read-only usage).
    commodity:
        If provided, filter to this commodity only.  If ``None``, return all
        meters across all commodities.

    Returns
    -------
    list[Meter]
        Meters ordered by (started_at ASC).
    """
    stmt = select(Meter).order_by(Meter.started_at.asc())
    if commodity is not None:
        stmt = stmt.where(Meter.commodity == commodity)

    return list(session.execute(stmt).scalars().all())


def update_meter(
    session: Session,
    meter: Meter,
    *,
    label: Optional[str] = None,
    note: Optional[str] = None,
    started_at: Optional[datetime] = None,
) -> Meter:
    """Update a meter's mutable fields (label, note, started_at).

    Passing ``None`` for a field leaves it unchanged.  At least one keyword
    argument must be non-``None``; calling with all-``None`` is a no-op but
    is not an error.

    Updating ``started_at`` (retroactive correction)
    ------------------------------------------------
    When ``started_at`` is provided the service maintains **timeline
    continuity** across the adjacent meter boundaries:

    1. **Previous meter's ``ended_at``** — if the meter immediately before
       this one has ``ended_at == meter.started_at`` (the standard contiguous
       handoff), its ``ended_at`` is updated to the new ``started_at`` so the
       boundary between the two epochs stays seamless.

    2. **Validation** — the new ``started_at`` is checked for consistency:
       a. It must be **strictly after** the previous meter's own ``started_at``
          (otherwise the previous meter's epoch would collapse to zero or
          invert).
       b. It must be **strictly before** this meter's ``ended_at`` (if set),
          so this meter's epoch remains non-empty.

    Note: triggering a billing recompute (``recompute_range``) after a
    retroactive ``started_at`` change is **out of scope** for this service
    layer; that is the API layer's responsibility (M7-T05).

    Parameters
    ----------
    session:
        Active SQLAlchemy session.  Caller must commit after this returns.
    meter:
        The ``Meter`` ORM instance to update (already loaded from the session).
    label:
        New human-readable label; ``None`` = keep existing.
    note:
        New free-form note; ``None`` = keep existing.
    started_at:
        New start timestamp for this meter epoch; ``None`` = keep existing.

    Returns
    -------
    Meter
        The updated ``Meter`` instance (not yet committed).

    Raises
    ------
    MeterIntervalError
        If the new ``started_at`` would produce an invalid (empty or inverted)
        epoch for this meter or the immediately preceding one.
    """
    if label is not None:
        meter.label = label
        logger.info("Updated meter id=%d label=%r", meter.id, label)

    if note is not None:
        meter.note = note
        logger.info("Updated meter id=%d note=%r", meter.id, note)

    if started_at is not None:
        old_started_at = meter.started_at

        # --- Validate upper bound: new started_at must be < this meter's ended_at (if set).
        if meter.ended_at is not None:
            if _as_utc(started_at) >= _as_utc(meter.ended_at):
                raise MeterIntervalError(
                    f"New started_at ({started_at.isoformat()}) must be strictly before "
                    f"this meter's ended_at ({meter.ended_at.isoformat()}).  "
                    "The meter epoch would become empty or inverted."
                )

        # --- Find the immediately preceding meter (its ended_at == meter's old started_at).
        prev = _meter_before(session, meter)

        # --- Validate lower bound: new started_at must be strictly after prev's started_at.
        if prev is not None:
            if _as_utc(started_at) <= _as_utc(prev.started_at):
                raise MeterIntervalError(
                    f"New started_at ({started_at.isoformat()}) must be strictly after "
                    f"the previous meter's started_at ({prev.started_at.isoformat()}).  "
                    "Moving the boundary that far back would collapse the previous meter's epoch."
                )
            # Maintain continuity: update the previous meter's ended_at to match the new start.
            prev.ended_at = started_at
            logger.info(
                "Updated previous meter id=%d ended_at=%s (boundary shift from %s)",
                prev.id,
                started_at.isoformat(),
                old_started_at.isoformat(),
            )

        meter.started_at = started_at
        logger.info(
            "Updated meter id=%d started_at=%s (was %s)",
            meter.id,
            started_at.isoformat(),
            old_started_at.isoformat(),
        )

    return meter