# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-a-quorum-is-being-inflated-by-hallucinated-peers-in-bft-task-commitment.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-a-quorum-is-being-inflated-by-hallucinated-peers-in-bft-task-commitment.warrant.json
# Markdown SHA-256:   b6ec08a2ece1dce47ea558652efbe07fc9a05ffbda81cafdd58088c7fb12ca48
# Code AST SHA-256:   6a21ffe8ae9669bbdaa8029ae2b6c42fa79c6abb7d99f50ea582da5a8b76a373
# Verified Classes:   InflatedQuorumError, Commitment
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from collections import Counter
from dataclasses import dataclass
from typing import Sequence


class InflatedQuorumError(RuntimeError):
    """Raised when a quorum is cardinality-satisfied but payload-incoherent."""


@dataclass(frozen=True)
class Commitment:
    signer_id: str
    task_id: str
    proposal_hash: str


def finalize_commitment(
    commitments: Sequence[Commitment],
    task_id: str,
    quorum_size: int,
) -> str:
    relevant = [c for c in commitments if c.task_id == task_id]
    if len(relevant) < quorum_size:
        raise InflatedQuorumError(
            f"task {task_id}: only {len(relevant)} signatures, need {quorum_size}"
        )

    # Cardinality is satisfied. Now check coherence.
    counts = Counter(c.proposal_hash for c in relevant)
    if len(counts) > 1:
        top_hash, top_count = counts.most_common(1)[0]
        if top_count <= quorum_size // 2:
            raise InflatedQuorumError(
                f"task {task_id}: quorum of {len(relevant)} reached but no "
                f"payload has majority support within quorum "
                f"(distribution={dict(counts)}); escalate to re-proposal"
            )
        # Single dominant payload with a dissenting minority: still suspect.
        if len(counts) > 1 and top_count < quorum_size - 1:
            raise InflatedQuorumError(
                f"task {task_id}: quorum reached with {len(counts)} distinct "
                f"payloads; equivocation suspected, re-proposal required"
            )
        return top_hash

    return next(iter(counts))