"""Relative (route-length-independent) pause policy.

mountain_twin.weather.temporal.planning_scenarios() hardcodes pause marks as
absolute route-distance metres (12000 m, 9000 m, 19000 m, ...) chosen to fit
TMB Day 1's ~28 km length -- see docs/design_reference/
camps_staging_spike_v0_1.md section 1.4. That function is untouched by this
module and keeps serving the existing Explorer/TMB pipeline unchanged.

This module generates the same mountain_twin.weather.temporal.Pause objects
mountain_twin.pace.analysis.analyze_route_pace already accepts, but placed
every N metres of *this route's own length* -- so the identical rule
produces sensible pauses on a 3 km or a 300 km route without per-route
tuning.
"""

from __future__ import annotations

from mountain_twin.weather.temporal import Pause

RELATIVE_PAUSE_POLICY_ID = "relative_distance_pauses_v0_1"

DEFAULT_INTERVAL_M = 8000.0
DEFAULT_DURATION_MINUTES = 15.0


def generate_relative_pauses(
    total_distance_m: float,
    *,
    interval_m: float = DEFAULT_INTERVAL_M,
    duration_minutes: float = DEFAULT_DURATION_MINUTES,
) -> tuple[Pause, ...]:
    """One pause every ``interval_m`` metres, never at the very start or end.

    A route shorter than ``interval_m`` gets no pauses (there is no
    "one third of the way" mark to invent) rather than a guessed one.
    """
    if total_distance_m < 0 or duration_minutes < 0:
        raise ValueError("route length and pause duration must be non-negative")
    if interval_m <= 0:
        raise ValueError("pause interval must be positive")
    pauses = []
    distance = interval_m
    while distance < total_distance_m:
        pauses.append(Pause(distance, duration_minutes))
        distance += interval_m
    return tuple(pauses)