"""Null definition -> retry with the next K evidence chunks.

After the last round the entry is KEPT, flagged `no_definition_found`, and
passed to review anyway. A term we found but could not define is still useful
information for the expert — dropping it would hide a known unknown, and no
downstream stage would ever recover it.
"""

from __future__ import annotations

from ..models import TermCluster
from ..settings import MAX_ESCALATION_ROUNDS


def rounds_available(cluster: TermCluster, k: int) -> int:
    """How many escalation rounds this cluster actually has evidence for.

    Frequently 0 on short documents: a cluster with a single evidence chunk has
    nowhere to escalate. An escalation count of zero is therefore not by itself
    evidence that the loop is broken.
    """
    extra = max(0, len(cluster.evidence_chunk_ids) - k)
    return min(MAX_ESCALATION_ROUNDS, -(-extra // k))  # ceil division