# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-does-an-instance-of-speculative-decoding-coordination-fail-silently-when-verifier-quorums-are-drawn-from-heterogeneous-pools-with-correlated-draft.md
# Remnant Warrant:    https://corpusfetch.com/c/why-does-an-instance-of-speculative-decoding-coordination-fail-silently-when-verifier-quorums-are-drawn-from-heterogeneous-pools-with-correlated-draft.warrant.json
# Markdown SHA-256:   fcbd327f6d721ed3a7cae5467339ce016bc09a080749953b4004c64bf6860a0c
# Code AST SHA-256:   4db10394ba41ab558d37f2e619c820ed91bd27b82b24fe3a2cbf1590d5880000
# Verified Classes:   QuorumIndependenceError, CorrelationClassRegistry
# Defensive Guards:   2 fail-closed invariants (zero external deps)

class QuorumIndependenceError(RuntimeError):
    """Raised when a quorum satisfies cardinality but violates correlation-class independence."""
    pass


class CorrelationClassRegistry:
    def __init__(self, agreement_threshold: float = 0.15):
        self.threshold = agreement_threshold
        self.class_of = {}  # agent_id -> class_id

    def register(self, agent_id: str, class_id: str) -> None:
        self.class_of[agent_id] = class_id

    def classes_in(self, quorum: list[str]) -> set[str]:
        return {self.class_of.get(a, f"unknown:{a}") for a in quorum}


def validate_quorum(
    quorum: list[str],
    f: int,
    registry: CorrelationClassRegistry,
) -> None:
    required_cardinality = 2 * f + 1
    required_classes = f + 1

    if len(quorum) < required_cardinality:
        raise QuorumIndependenceError(
            f"quorum cardinality {len(quorum)} < required {required_cardinality}"
        )

    classes = registry.classes_in(quorum)
    if len(classes) < required_classes:
        raise QuorumIndependenceError(
            f"quorum spans {len(classes)} correlation classes, "
            f"requires at least {required_classes} for Byzantine safety at f={f}; "
            f"cardinality safety does not imply independence safety"
        )


def select_quorum(
    candidates: list[str],
    f: int,
    registry: CorrelationClassRegistry,
) -> list[str]:
    # Greedy: prefer one agent per class, then fill by remaining latency order.
    chosen: list[str] = []
    seen_classes: set[str] = set()
    for agent in candidates:
        cls = registry.class_of.get(agent, f"unknown:{agent}")
        if cls not in seen_classes:
            chosen.append(agent)
            seen_classes.add(cls)
        if len(chosen) >= 2 * f + 1:
            break
    for agent in candidates:
        if agent not in chosen and len(chosen) < 2 * f + 1:
            chosen.append(agent)
    validate_quorum(chosen, f, registry)
    return chosen
