"""Funzione pura per calcolare la soglia adattiva del gate IV-RV.

Spec: ``docs/superpowers/specs/2026-05-08-iv-rv-adaptive-gate-design.md``.

Deterministic, no I/O. La selezione della finestra (target_days vs
min_days vs intera storia disponibile) è responsabilità del caller, che
interroga il repository con i parametri corretti e passa qui sia i
valori (``history``) sia il numero di giorni distinti coperti
(``n_days``). Questo permette di mischiare cadenze diverse — tick live a
15 min e backfill daily — senza assumere un fattore costante
``ticks_per_day``.
"""

from __future__ import annotations

from collections.abc import Sequence
from decimal import Decimal

__all__ = ["compute_adaptive_threshold"]


def compute_adaptive_threshold(
    history: Sequence[Decimal],
    *,
    n_days: int,
    percentile: Decimal,
    absolute_floor: Decimal,
) -> Decimal | None:
    """Ritorna la soglia adattiva o ``None`` durante il warmup hard.

    Args:
        history: Sequenza dei valori IV-RV nella finestra scelta dal
            caller. NULL e tick non riusciti devono essere già stati
            filtrati upstream. L'ordine non è significativo per il
            percentile.
        n_days: Numero di giorni distinti coperti dalla storia
            disponibile (calcolato dal caller, tipicamente con
            ``COUNT(DISTINCT date(timestamp))``). ``0`` → warmup hard.
        percentile: Quantile target nella distribuzione (es. ``0.25``).
        absolute_floor: Floor minimo applicato dopo il calcolo del
            percentile. La soglia restituita è
            ``max(P_q, absolute_floor)``.

    Returns:
        ``None`` se ``n_days == 0`` o ``history`` è vuota (warmup hard,
        gate disabilitato), altrimenti il percentile della finestra
        bounded dal floor.
    """
    if not (Decimal(0) <= percentile <= Decimal(1)):
        raise ValueError(
            f"percentile must be in [0, 1], got {percentile}"
        )
    if n_days < 0:
        raise ValueError(f"n_days must be >= 0, got {n_days}")
    if n_days == 0 or not history:
        return None
    return max(_percentile(history, percentile), absolute_floor)


def _percentile(values: Sequence[Decimal], q: Decimal) -> Decimal:
    """Linear-interpolated percentile, NumPy-compatible (method='linear').

    Implementato in Decimal puro per evitare dipendenze numpy nel core.
    """
    if not values:
        raise ValueError("percentile of empty sequence")
    sorted_v = sorted(values)
    n = len(sorted_v)
    k = (Decimal(n) - Decimal(1)) * q
    f = int(k)  # floor
    c = min(f + 1, n - 1)
    if f == c:
        return sorted_v[f]
    frac = k - Decimal(f)
    return sorted_v[f] + (sorted_v[c] - sorted_v[f]) * frac
