# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-enforce-signature-freshness-during-a2a-v1-0-cross-org-agent-card-discovery-when-the-negotiating-peer-rotates-its-signing-key-mi.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-enforce-signature-freshness-during-a2a-v1-0-cross-org-agent-card-discovery-when-the-negotiating-peer-rotates-its-signing-key-mi.warrant.json
# Markdown SHA-256:   861e896bbec580463ed00a55221bb4e64fe6c695c56662e674c691761a117521
# Code AST SHA-256:   5f9c8f88bf5c75d9b3b534a449952a881565b3be62732a22c1e1f2773df736e1
# Verified Classes:   StaleKeyEpochError, Card, JwksSnapshot
# Defensive Guards:   4 fail-closed invariants (zero external deps)

import time
from dataclasses import dataclass


class StaleKeyEpochError(RuntimeError):
    """Raised when a card's signing key cannot be bound to a fresh-enough JWKS snapshot."""
    pass


@dataclass(frozen=True)
class Card:
    agent_id: str
    issued_at: float
    keyid: str
    body_hash: str


@dataclass(frozen=True)
class JwksSnapshot:
    agent_id: str
    fetched_at: float
    keyids: frozenset
    revoked: frozenset


def validate_card_epoch(
    card: Card,
    jwks: JwksSnapshot,
    overlap_seconds: float,
    now: float,
) -> None:
    if card.agent_id != jwks.agent_id:
        raise StaleKeyEpochError(
            f"agent mismatch: card={card.agent_id} jwks={jwks.agent_id}"
        )

    # The signature may verify, but the snapshot must be able to speak for
    # the card's issuance epoch. A snapshot older than the card is insufficient.
    if jwks.fetched_at < card.issued_at - overlap_seconds:
        raise StaleKeyEpochError(
            f"JWKS snapshot predates card epoch: "
            f"fetched_at={jwks.fetched_at} issued_at={card.issued_at} "
            f"overlap={overlap_seconds}"
        )

    if card.keyid in jwks.revoked:
        raise StaleKeyEpochError(
            f"card signed by revoked keyid {card.keyid} for agent {card.agent_id}"
        )

    if card.keyid not in jwks.keyids:
        raise StaleKeyEpochError(
            f"card keyid {card.keyid} absent from JWKS snapshot for "
            f"agent {card.agent_id}; refusing last-known-good fallback "
            f"(snapshot fetched_at={jwks.fetched_at}, now={now})"
        )


def negotiate(card: Card, jwks: JwksSnapshot, overlap_seconds: float) -> None:
    now = time.time()
    validate_card_epoch(card, jwks, overlap_seconds, now)
    # proceed with capability negotiation against this exact epoch