"""`@endpoint` builds one at decoration time and attaches it as `view.__spec__`;
the router reads nothing else off the view. It lives in `auth/` so the
dependency runs `_contract.py` -> `auth/` and never back.
"""

from __future__ import annotations

from dataclasses import dataclass

from controllers.openapi.auth.requirements import Requirement
from enums import DeploymentEdition


@dataclass(frozen=True, slots=True)
class EndpointSpec:
    """`edition` is the endpoint-level gate — a 404 raised before any bearer
    is read, because the route is not exposed on this edition at all. It is
    not `ExternalSsoPipeline`'s own gate, which 403s a token kind after
    authentication.
    """

    requirements: tuple[Requirement, ...]
    edition: frozenset[DeploymentEdition] | None = None