# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-happens-when-an-instance-in-a-byzantine-quorum-reconstructs-quorum-certificates-from-stale-view-membership.md
# Remnant Warrant:    https://corpusfetch.com/c/what-happens-when-an-instance-in-a-byzantine-quorum-reconstructs-quorum-certificates-from-stale-view-membership.warrant.json
# Markdown SHA-256:   6dfad9997e5b04f620e410f718e75def93fd172412229d3d967c3edc38acbabf
# Code AST SHA-256:   ef6d5dcbbc63b255f4ab33633c47309a66fcb459b0785f23542978ab36483161
# Verified Classes:   StaleEpochQuorumError, SignedVote
# Defensive Guards:   7 fail-closed invariants (zero external deps)

from dataclasses import dataclass


class StaleEpochQuorumError(RuntimeError):
    """Raised when a quorum certificate is structurally valid but was
    aggregated over a membership or signing context that does not match
    the epoch/height it claims to certify."""
    pass


@dataclass(frozen=True)
class SignedVote:
    signer: str
    epoch: int
    height: int
    view: int
    digest: str
    signature: bytes


def verify_quorum_certificate(
    votes: list[SignedVote],
    claimed_epoch: int,
    claimed_height: int,
    claimed_digest: str,
    membership_at_epoch: dict[int, set[str]],
    quorum_size: int,
) -> bool:
    """Validate a QC by binding every signature to its (epoch, height, digest)
    context AND to the membership active at that epoch.

    Fails closed on any mismatch. Never falls back to bare threshold counting.
    """
    if claimed_epoch not in membership_at_epoch:
        raise StaleEpochQuorumError(
            f"epoch {claimed_epoch} has no registered membership; "
            f"refusing to validate QC against an unknown validator set"
        )

    active_members = membership_at_epoch[claimed_epoch]
    seen: set[str] = set()

    for vote in votes:
        # Context binding: the signed message must match the claimed context.
        if vote.epoch != claimed_epoch:
            raise StaleEpochQuorumError(
                f"signer {vote.signer} signed epoch {vote.epoch} but QC "
                f"claims epoch {claimed_epoch}; replay across epochs rejected"
            )
        if vote.height != claimed_height:
            raise StaleEpochQuorumError(
                f"signer {vote.signer} signed height {vote.height} but QC "
                f"claims height {claimed_height}"
            )
        if vote.digest != claimed_digest:
            raise StaleEpochQuorumError(
                f"signer {vote.signer} signed digest {vote.digest} but QC "
                f"claims digest {claimed_digest}"
            )

        # Membership binding: the signer must be a member at the claimed epoch.
        if vote.signer not in active_members:
            raise StaleEpochQuorumError(
                f"signer {vote.signer} is not a member of epoch {claimed_epoch}; "
                f"stale-membership QC rejected"
            )

        if vote.signer in seen:
            raise StaleEpochQuorumError(
                f"duplicate vote from {vote.signer}; equivocation rejected"
            )
        seen.add(vote.signer)

    if len(seen) < quorum_size:
        raise StaleEpochQuorumError(
            f"only {len(seen)} distinct valid votes at epoch {claimed_epoch}, "
            f"height {claimed_height}; quorum requires {quorum_size}"
        )

    return True
