# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distinguish-equivocating-plan-commitment-from-benign-view-change-churn-in-byzantine-fault-tolerant-multi-agent-consensus.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distinguish-equivocating-plan-commitment-from-benign-view-change-churn-in-byzantine-fault-tolerant-multi-agent-consensus.warrant.json
# Markdown SHA-256:   6662cb38e66f164b0e0663a0156deb1e474eac0127a3d8b676654dba6ea00def
# Code AST SHA-256:   233d736a0193b4b4faba5656b66b6f035ecabf501d8d50a305e7e061081ddd5e
# Verified Classes:   EquivocationVerdictError, CommitCertStore
# Defensive Guards:   2 fail-closed invariants (zero external deps)

class EquivocationVerdictError(RuntimeError):
    """Raised when an equivocation check cannot be resolved from available evidence."""
    pass


class CommitCertStore:
    def __init__(self):
        self._certs = {}

    def has_commit_cert(self, seq: int, plan_hash: str) -> bool:
        return self._certs.get((seq, plan_hash)) is not None

    def record(self, seq: int, plan_hash: str) -> None:
        self._certs[(seq, plan_hash)] = True


def classify_conflict(
    agent_id: str,
    seq: int,
    view_a: int,
    hash_a: str,
    view_b: int,
    hash_b: str,
    quorum_observed: bool,
    certs: CommitCertStore,
) -> str:
    if hash_a == hash_b and view_a == view_b:
        return "duplicate_delivery"

    if hash_a == hash_b:
        return "benign_reproposal"

    if view_a == view_b:
        if not quorum_observed:
            return "duplicate_delivery"
        return "equivocation"

    # Different hashes, different views: must consult commit certificates.
    earlier_view, earlier_hash = (view_a, hash_a) if view_a < view_b else (view_b, hash_b)
    later_view, later_hash = (view_b, hash_b) if view_a < view_b else (view_a, hash_a)

    if certs.has_commit_cert(seq, earlier_hash):
        return "post_commit_double_sign"

    if certs.has_commit_cert(seq, later_hash):
        # The later hash committed; the earlier one was never finalized.
        return "benign_reproposal"

    # No certificate for either hash: the earlier proposal never reached quorum,
    # so the later hash is legal. But we cannot be certain without the prepare cert.
    raise EquivocationVerdictError(
        f"ambiguous conflict for agent={agent_id} seq={seq}: "
        f"view {earlier_view} hash {earlier_hash} vs view {later_view} hash {later_hash}; "
        f"no commit certificate in store — require prepare certificate from earlier view"
    )


def audit_pair(agent_id: str, seq: int, msg_a: dict, msg_b: dict,
               quorum_observed: bool, certs: CommitCertStore) -> str:
    verdict = classify_conflict(
        agent_id=agent_id,
        seq=seq,
        view_a=msg_a["view"],
        hash_a=msg_a["plan_hash"],
        view_b=msg_b["view"],
        hash_b=msg_b["plan_hash"],
        quorum_observed=quorum_observed,
        certs=certs,
    )
    if verdict == "equivocation":
        raise EquivocationVerdictError(
            f"confirmed equivocation: agent={agent_id} seq={seq} view={msg_a['view']} "
            f"hashes {msg_a['plan_hash']} and {msg_b['plan_hash']}"
        )
    return verdict
