# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-detect-equivocation-induced-commitment-divergence-before-quorum-finality-in-byzantine-multi-agent-task-commitment.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-detect-equivocation-induced-commitment-divergence-before-quorum-finality-in-byzantine-multi-agent-task-commitment.warrant.json
# Markdown SHA-256:   19b05f1377a4be990a37f00092e27c552b03f6be0a0d9f3c0f1fc5940b5d627b
# Code AST SHA-256:   9ba4bd3fe3e2071224d65e428c7a0d847fa51f34d5a62fe08e893a25a848e5c7
# Verified Classes:   CommitmentDivergenceError
# Defensive Guards:   5 fail-closed invariants (zero external deps)

class CommitmentDivergenceError(RuntimeError):
    """Raised when two valid supermajority certificates assert conflicting
    commitments for the same (task_id, epoch). Certificate validity does NOT
    imply commitment uniqueness; this is the equivocation boundary."""
    pass


def reconcile_commitment(cert_a: dict, cert_b: dict, quorum_size: int) -> str:
    # Each cert: {"task_id", "epoch", "value", "signers": set, "lock_digests": dict}
    if cert_a["task_id"] != cert_b["task_id"]:
        return "distinct_tasks"

    if cert_a["epoch"] != cert_b["epoch"]:
        # Different epochs are not equivocation, but finalization requires
        # an epoch-advance proof; refuse to guess.
        raise CommitmentDivergenceError(
            f"cross-epoch certificates for task {cert_a['task_id']}: "
            f"{cert_a['epoch']} vs {cert_b['epoch']}; epoch-advance proof required"
        )

    if cert_a["value"] == cert_b["value"]:
        return "agree"

    # Same task, same epoch, different values, both quorum-sized: equivocation.
    if len(cert_a["signers"]) >= quorum_size and len(cert_b["signers"]) >= quorum_size:
        overlap = cert_a["signers"] & cert_b["signers"]
        double_signers = {
            s for s in overlap
            if cert_a["lock_digests"].get(s) != cert_b["lock_digests"].get(s)
        }
        raise CommitmentDivergenceError(
            f"equivocation on task {cert_a['task_id']} epoch {cert_a['epoch']}: "
            f"values {cert_a['value']!r} vs {cert_b['value']!r}; "
            f"double-signers={sorted(double_signers)}"
        )

    # One side below quorum: provisional, do not finalize, do not raise.
    return "provisional"


def finalize(cert: dict, quorum_size: int, epoch_advance_proof: dict | None) -> str:
    if "epoch" not in cert or "lock_digests" not in cert:
        raise CommitmentDivergenceError(
            "certificate lacks epoch binding or lock proof; cannot finalize"
        )
    if len(cert["signers"]) < quorum_size:
        raise CommitmentDivergenceError(
            f"insufficient signers: {len(cert['signers'])} < {quorum_size}"
        )
    if epoch_advance_proof is None:
        raise CommitmentDivergenceError(
            f"no epoch-advance proof for epoch {cert['epoch']}; "
            "refusing to finalize (reopenable epoch)"
        )
    return cert["value"]
