# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/under-what-conditions-must-an-instance-refuse-to-count-an-equivocating-agent-s-certificate-toward-quorum-in-bft-swarm-task-commit.md
# Remnant Warrant:    https://corpusfetch.com/c/under-what-conditions-must-an-instance-refuse-to-count-an-equivocating-agent-s-certificate-toward-quorum-in-bft-swarm-task-commit.warrant.json
# Markdown SHA-256:   ffc3cc88f988ef67d3bd3da6b1718177a2c562e6fa7863352cdc3e953520f07e
# Code AST SHA-256:   d8fa264c35ac4a8d793c1378a3d56d59e42cd3a7ca90750ba17df76c4ef52bca
# Verified Classes:   QuorumUnsoundError, Certificate, MembershipSnapshot, QuorumCounter
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import FrozenSet, Dict, Tuple


class QuorumUnsoundError(RuntimeError):
    """Raised when a certificate cannot be safely counted toward quorum."""
    pass


@dataclass(frozen=True)
class Certificate:
    agent_id: str
    view: int
    payload_hash: str


@dataclass(frozen=True)
class MembershipSnapshot:
    epoch: int
    members: FrozenSet[str]
    quorum_size: int  # 2f+1 for the snapshot's f


class QuorumCounter:
    def __init__(self) -> None:
        # (agent_id, view) -> set of payload hashes seen; size > 1 means equivocation
        self._seen: Dict[Tuple[str, int], set] = {}
        # (agent_id, view) -> True once an equivocation proof is recorded
        self._equivocation_proofs: Dict[Tuple[str, int], bool] = {}
        # view -> membership snapshot pinned at view open
        self._view_snapshot: Dict[int, MembershipSnapshot] = {}

    def open_view(self, view: int, snapshot: MembershipSnapshot) -> None:
        self._view_snapshot[view] = snapshot

    def record(self, cert: Certificate) -> None:
        key = (cert.agent_id, cert.view)
        self._seen.setdefault(key, set()).add(cert.payload_hash)
        if len(self._seen[key]) > 1:
            self._equivocation_proofs[key] = True

    def count_toward_quorum(
        self, certs: list[Certificate], view: int
    ) -> int:
        snapshot = self._view_snapshot.get(view)
        if snapshot is None:
            raise QuorumUnsoundError(
                f"view {view} has no pinned membership snapshot; "
                f"quorum arithmetic is undefined"
            )
        counted = 0
        for cert in certs:
            if cert.view != view:
                raise QuorumUnsoundError(
                    f"certificate for view {cert.view} offered to view {view} quorum"
                )
            if cert.agent_id not in snapshot.members:
                # Agent was evicted after this snapshot was pinned; counting it
                # would assemble a quorum from a membership that no longer exists.
                raise QuorumUnsoundError(
                    f"agent {cert.agent_id} not in epoch {snapshot.epoch} "
                    f"membership for view {view}; eviction mid-epoch invalidates "
                    f"this quorum"
                )
            if self._equivocation_proofs.get((cert.agent_id, view), False):
                # Evidence, not a vote. Exclude from quorum arithmetic.
                continue
            counted += 1
        return counted

    def assert_committable(self, certs: list[Certificate], view: int) -> None:
        snapshot = self._view_snapshot.get(view)
        if snapshot is None:
            raise QuorumUnsoundError(f"no snapshot for view {view}")
        counted = self.count_toward_quorum(certs, view)
        if counted < snapshot.quorum_size:
            raise QuorumUnsoundError(
                f"view {view}: {counted} countable certificates, "
                f"need {snapshot.quorum_size} for epoch {snapshot.epoch}"
            )
