"""Resolve a route's IANA timezone from its own coordinates -- offline, no
network dependency (docs/route_persistence_v0_1_design.md, Work Package 3).

Chosen over asking the user to name a timezone explicitly: a route's
timezone is an objective property of where it physically is, not a
preference, and Planning Workspace's browser-side clock already tells us
nothing useful about it (it only knows the *viewer's* offset, not the
route's location -- exactly the gap docs/design_reference/
route_drawing_spike_v0_1.md's WP1/WP2 report flagged). See the final report
for the full comparison against timezonefinder (same open timezone-
boundary-builder data, but a 53 MB source distribution needing a build
step, versus tzfpy's ~13 MB precompiled wheel) and against an explicit
picker UI.
"""

from __future__ import annotations

from tzfpy import get_tz


def resolve_route_timezone(latitude: float, longitude: float) -> str:
    """The IANA timezone name at this coordinate. Raises ValueError rather
    than silently defaulting to UTC or guessing when tzfpy has no polygon
    covering the point (only possible for out-of-range input; every point
    already stored via mountain_twin.journey.route_persistence has passed
    RoutePointInput's latitude/longitude bounds check)."""
    zone_name = get_tz(longitude, latitude)
    if not zone_name:
        raise ValueError(f"could not resolve a timezone for ({latitude}, {longitude})")
    return zone_name