# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-a-bft-quorum-certificate-as-invalid-despite-sufficient-signature-count-the-quorum-intersection-drift-failure.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-a-bft-quorum-certificate-as-invalid-despite-sufficient-signature-count-the-quorum-intersection-drift-failure.warrant.json
# Markdown SHA-256:   a5d8ac82e2f9cc9e6eb4339ca84c9875f965067b13a525c0d023e8a37814f8c0
# Code AST SHA-256:   2b883c5a336a77f5f8d6cde7d92797d63a1c8df46e509163154e4e4fddc84fea
# Verified Classes:   QuorumIntersectionDriftError, QuorumCertificate
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import FrozenSet, Mapping


class QuorumIntersectionDriftError(RuntimeError):
    """Raised when a QC meets its signature threshold but fails cross-epoch intersection."""


@dataclass(frozen=True)
class QuorumCertificate:
    height: int
    signers: FrozenSet[str]
    epoch_id: int
    threshold: int


def assert_qc_operationally_valid(
    qc: QuorumCertificate,
    epoch_membership: Mapping[int, FrozenSet[str]],
    committed_qcs: list[QuorumCertificate],
    fault_tolerance: int,
) -> None:
    if qc.epoch_id not in epoch_membership:
        raise QuorumIntersectionDriftError(
            f"QC at height {qc.height} cites unknown epoch {qc.epoch_id}; "
            "membership view cannot be reconstructed."
        )

    # A signer must actually belong to the epoch the QC claims.
    if not qc.signers.issubset(epoch_membership[qc.epoch_id]):
        stray = qc.signers - epoch_membership[qc.epoch_id]
        raise QuorumIntersectionDriftError(
            f"QC at height {qc.height} claims epoch {qc.epoch_id} but includes "
            f"non-members {sorted(stray)}; signature count is not sufficient."
        )

    if len(qc.signers) < qc.threshold:
        raise QuorumIntersectionDriftError(
            f"QC at height {qc.height} has {len(qc.signers)} signers "
            f"below threshold {qc.threshold}."
        )

    # The non-obvious check: intersection must be computed per-epoch.
    for prior in committed_qcs:
        if prior.height != qc.height:
            continue
        if prior.epoch_id == qc.epoch_id:
            shared = qc.signers & prior.signers
        else:
            # Different epochs: intersect against the smaller membership view.
            smaller = min(
                epoch_membership[qc.epoch_id],
                epoch_membership.get(prior.epoch_id, frozenset()),
                key=len,
            )
            shared = (qc.signers & prior.signers) & smaller
        if len(shared) < fault_tolerance + 1:
            raise QuorumIntersectionDriftError(
                f"QC at height {qc.height} (epoch {qc.epoch_id}) shares only "
                f"{len(shared)} signers with committed QC (epoch {prior.epoch_id}); "
                f"intersection floor is {fault_tolerance + 1}. Rejecting despite "
                f"{len(qc.signers)} valid signatures."
            )
