"""
FreeExile Common Time & Temporal Utilities.
Stateless helper functions for authoritative timestamps and delta timing.
"""

from __future__ import annotations
import time
from datetime import datetime, timezone


def now_ms() -> int:
    """Returns current system UTC time in milliseconds."""
    return int(time.time() * 1000)


def now_sec() -> float:
    """Returns current system UTC time in fractional seconds."""
    return time.time()


def now_iso() -> str:
    """Returns current system UTC time formatted as an ISO-8601 string."""
    return datetime.now(timezone.utc).isoformat()


def elapsed_ms(start_time_sec: float) -> float:
    """Calculates elapsed milliseconds since a previous time.time() reference."""
    return (time.time() - start_time_sec) * 1000.0