"""
Dial Plan — Emergency-number guard and extension allocation.

Emergency numbers are never dialable through the gateway's API/MCP
surfaces: an outbound emergency call must come from a human on a real
phone whose trunk provider has E911 location data, not from an AI agent
or a REST request. See the README caution.
"""


# Dialled forms and their E.164 mappings — both sides are refused.
EMERGENCY_NUMBERS: dict[str, str] = {
    "911": "+1911",   # North American emergency
    "9911": "+1911",  # Mis-dial with phantom '9' prefix
    "112": "+112",   # International GSM emergency
}

_BLOCKED = frozenset(EMERGENCY_NUMBERS) | frozenset(EMERGENCY_NUMBERS.values())


def is_emergency_number(number: str) -> bool:
    """True if the dialled string is an emergency number (any known form)."""
    cleaned = number.strip().replace(" ", "").replace("-", "").replace(".", "")
    return cleaned in _BLOCKED


# ================================================================
# Extension allocation (2XX range)
# ================================================================

EXTENSION_FIRST = 221
EXTENSION_LAST = 299


def next_extension(used: set[int]) -> int | None:
    """
    Return the lowest available extension in the 2XX range.

    Args:
        used: Set of already-assigned extension numbers.

    Returns:
        Next free extension, or None if the range is exhausted.
    """
    for ext in range(EXTENSION_FIRST, EXTENSION_LAST + 1):
        if ext not in used:
            return ext
    return None