"""Reserved-concurrency advisory — an AIMD controller on the throttle signal.

Not currently wired to an endpoint; kept for an upcoming concurrency recommender.
"""

import math

from resonance_engine.tasks.planner import SAFETY_FACTOR

MAX_CONCURRENCY = 1000  # AWS regional default — cap to keep within quota


def get_recommended_concurrency(
    nominal_rps: int,
    *,
    observed_rps: float | None = None,
    latency_s: float,
    throttle_rate: float = 0.0,
) -> int:
    """Reserved concurrency the consumer Lambda should run, capped at
    MAX_CONCURRENCY. Warm: `observed_rps * latency` is the concurrency that
    actually ran (Little's law); from there AIMD — clean headroom (no 429s) →
    grow (`/ SAFETY_FACTOR`, ~+18%), throttling → back off by the 429 share. Cold
    start (no observed rps) seeds from the `nominal_rps` guess. Advisory only."""
    if observed_rps and observed_rps > 0:
        ran = observed_rps * latency_s
        target = ran * (1 - throttle_rate) if throttle_rate > 0 else ran / SAFETY_FACTOR
    else:
        target = nominal_rps * SAFETY_FACTOR * latency_s
    return min(MAX_CONCURRENCY, max(1, math.ceil(target)))