# sid_canonical.py

from typing import List, Tuple


# ---------------------------------------------------------------------
# Canonical string encoder
# ---------------------------------------------------------------------

def encode_str(s: str) -> bytes:
    """
    Encode a string deterministically as length-prefixed UTF-8 bytes.
    """
    b = s.encode("utf-8")
    return len(b).to_bytes(4, "big") + b


# ---------------------------------------------------------------------
# Canonical key-value encoder
# ---------------------------------------------------------------------

def encode_kv_pairs(pairs: List[Tuple[str, str]]) -> bytes:
    """
    Encode sorted key-value pairs deterministically.

    Format:
        [num_pairs][key_len][key_bytes][value_len][value_bytes]...
    """
    out = len(pairs).to_bytes(4, "big")
    for k, v in pairs:
        out += encode_str(k)
        out += encode_str(v)
    return out