# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-must-an-instance-pin-collation-to-prevent-cross-host-sort-divergence.md
# Remnant Warrant:    https://corpusfetch.com/c/how-must-an-instance-pin-collation-to-prevent-cross-host-sort-divergence.warrant.json
# Markdown SHA-256:   ef3d1c9edb7f8b01562d6deb06533a69468510b635d9835b4caed625d00123ed
# Code AST SHA-256:   88d5aa48166c2613568bcaf713831c69446def6363b753e5f2c775d3b6dd17c2
# Verified Classes:   LocaleSortError, CollationGate
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass


class LocaleSortError(RuntimeError):
    """Raised when string order is not reproducible across hosts."""


@dataclass(frozen=True)
class CollationGate:
    collation: str  # "binary", "versioned", "locale-name"
    pinned_version: str = ""

    def verify(self) -> bool:
        if self.collation == "binary":
            return True
        if self.collation == "versioned" and self.pinned_version:
            return True
        if self.collation == "locale-name":
            raise LocaleSortError(
                "locale-name collation without pinned version: order varies across library upgrades"
            )
        raise LocaleSortError(f"collation {self.collation!r} is not reproducible")


def dispatch_collation(gate: CollationGate) -> str:
    try:
        gate.verify()
    except LocaleSortError:
        return "binary"
    return gate.collation