# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/under-what-conditions-must-an-instance-reject-a-peer-s-agent-card-during-a2a-v1-0-discovery-despite-a-valid-signature.md
# Remnant Warrant:    https://corpusfetch.com/c/under-what-conditions-must-an-instance-reject-a-peer-s-agent-card-during-a2a-v1-0-discovery-despite-a-valid-signature.warrant.json
# Markdown SHA-256:   5601b0a0bb5326c86dcd1694d8465b9d93acfb4877814b328b5d21b345561a60
# Code AST SHA-256:   b92f9bfc504e0945f3df30c5578b820baa21f7e31264ae5c3fa53ce072812987
# Verified Classes:   CardInadmissibleError, Card
# Defensive Guards:   6 fail-closed invariants (zero external deps)

"""Admissibility gate for A2A v1.0 Agent Cards.

Rejects signature-valid but semantically inadmissible cards at discovery,
before capability negotiation begins.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Iterable


class CardInadmissibleError(RuntimeError):
    """Raised when a cryptographically valid Agent Card cannot be negotiated with."""

    def __init__(self, reason_code: str, detail: str) -> None:
        super().__init__(f"[{reason_code}] {detail}")
        self.reason_code = reason_code
        self.detail = detail


@dataclass(frozen=True)
class Card:
    agent_id: str
    protocol_version: str
    compatible_with: str          # e.g. ">=1.1"
    transport_kind: str           # "unary-only" | "streaming"
    streaming_resumable: bool
    required_extensions: tuple[str, ...]
    extension_subjects: dict[str, str]  # ext_name -> subject agent_id in nested attestation
    signature_valid: bool


def _version_tuple(v: str) -> tuple[int, ...]:
    return tuple(int(p) for p in v.lstrip(">=").split("."))


def _range_contains(range_expr: str, version: str) -> bool:
    if not range_expr.startswith(">="):
        return False
    return _version_tuple(version) >= _version_tuple(range_expr)


def assert_admissible(card: Card, verifier_supported: Iterable[str]) -> None:
    """Raise CardInadmissibleError if the card must not enter negotiation."""
    if not card.signature_valid:
        raise CardInadmissibleError("SIG_INVALID", "detached JWS did not verify")

    # Class 3: version range must contain the card's own declared version.
    if not _range_contains(card.compatible_with, card.protocol_version):
        raise CardInadmissibleError(
            "VERSION_RANGE_INVERTED",
            f"card declares {card.protocol_version} but compatibleWith={card.compatible_with}",
        )

    # Class 3b: verifier must have a non-trivial intersection.
    if card.protocol_version not in set(verifier_supported):
        raise CardInadmissibleError(
            "VERSION_NO_INTERSECTION",
            f"card {card.protocol_version} not in verifier set {sorted(verifier_supported)}",
        )

    # Class 2: capability-set contradiction.
    if card.streaming_resumable and card.transport_kind == "unary-only":
        raise CardInadmissibleError(
            "CAPABILITY_CONTRADICTION",
            "resumable streaming advertised over unary-only transport",
        )

    # Class 4: required extension attestation must be scoped to this agent.
    for ext in card.required_extensions:
        subject = card.extension_subjects.get(ext)
        if subject is None:
            raise CardInadmissibleError(
                "EXTENSION_UNATTESTED",
                f"required extension {ext!r} has no nested attestation",
            )
        if subject != card.agent_id:
            raise CardInadmissibleError(
                "EXTENSION_SUBJECT_MISMATCH",
                f"extension {ext!r} attested for {subject!r}, not {card.agent_id!r}",
            )


def discover(card: Card, verifier_supported: Iterable[str]) -> Card:
    """Entry point: admit the card into negotiation or fail loudly at discovery."""
    assert_admissible(card, verifier_supported)
    return card
