hypermind 0.11.0__py3-none-any.whl

hypermind/contract_net.py

@@ -0,0 +1,219 @@
+"""Contract-Net Protocol — RFP / Bid / Award / Dispute (spec §27, T3).
+
+Lineage: FIPA Contract Net Protocol (FIPA00029). HyperMind's profile
+adds three things FIPA does not specify:
+
+1. **Cryptographic settlement.** Every RFP, BID, and AWARD is a signed
+   :class:`hypermind.wire.SignedStatement` — no record of the auction
+   exists outside the SCITT log.
+2. **FROST quorum awards.** When a consortium of k-of-n principals must
+   co-sign an AWARD, the AWARD record is signed by a FROST aggregate
+   over the canonical preimage `H("hm:cnp-award:" || rfp_id || winning_bid_kid)`.
+3. **Disputable awards.** A losing bidder can dispute the AWARD via the
+   regular Dispute FSM; the bond's `topic_scope_hash` binds the dispute
+   to ``"rfp:" + rfp_id`` so a wash-trade across topics cannot slash
+   the bond.
+
+This module owns the **scoring** layer. The agent verbs that publish the
+signed records live on :class:`hypermind.agent.HyperMindAgent`.
+
+Scoring is pluggable via the :class:`BidScorer` Protocol so federations
+can swap in domain-specific scoring policies (e.g. resource-cost
+weighted, latency-weighted) without touching the protocol itself. The
+default :class:`ReputationWeightedScorer` combines the bidder's Beta
+posterior on the topic with the bidder's claimed self-score and a
+Brier-derived calibration term — so a high-reputation bidder beats a
+low-reputation bidder at equal self-score.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from hypermind.knowledge.reputation import ReputationKernel
+
+# Domain tag for the FROST award transcript context. v1: length-prefixed
+# encoding (mirrors the witness-quorum tag `:v2` upgrade in dispute.py).
+AWARD_DOMAIN_TAG = b"hypermind:cnp-award:v1"
+
+
+def award_preimage(rfp_id: bytes, winning_bid_kid: bytes) -> bytes:
+    """Canonical preimage every AWARD signer (FROST or single) signs.
+
+    Domain-separated under :data:`AWARD_DOMAIN_TAG` so an AWARD signature
+    cannot be replayed as any other HyperMind signed payload. Both inputs
+    are length-prefixed with a 4-byte big-endian length to defeat boundary
+    ambiguity (mirrors the v2 witness-cosign encoding).
+    """
+
+    def _f(b: bytes) -> bytes:
+        return len(b).to_bytes(4, "big") + b
+
+    h = hashlib.sha256()
+    h.update(_f(AWARD_DOMAIN_TAG))
+    h.update(_f(bytes(rfp_id)))
+    h.update(_f(bytes(winning_bid_kid)))
+    return h.digest()
+
+
+def topic_scope_for_rfp(rfp_id: bytes) -> str:
+    """Bond topic-scope string for disputes filed against an AWARD.
+
+    The dispute FSM hashes this string with `_hash_topic_scope` (BLAKE3)
+    when sealing the bond. The string itself is the stable identifier we
+    use everywhere AWARD disputes are negotiated — so the topic-scope
+    binding is `"rfp:" + hex(rfp_id)`.
+    """
+    return "rfp:" + bytes(rfp_id).hex()
+
+
+# -----------------------------------------------------------------------
+# Records — in-memory views of the signed RFP/BID/AWARD payloads
+# -----------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class RFP:
+    """In-memory view of an RFP_OPEN record's payload + identifiers."""
+
+    rfp_id: bytes
+    issuer_kid: bytes
+    topic: str
+    requirements: dict[str, Any]
+    deadline_hlc_ms: int
+    bidder_filter: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class Bid:
+    """In-memory view of a BID record's payload + identifiers."""
+
+    rfp_id: bytes
+    bid_kid: bytes
+    bidder_kid: bytes
+    payload: dict[str, Any]
+    bid_score_self: float
+
+
+@dataclass(frozen=True)
+class Award:
+    """In-memory view of an AWARD record's payload + identifiers."""
+
+    rfp_id: bytes
+    award_kid: bytes
+    winning_bid_kid: bytes
+    winning_bidder_kid: bytes
+    award_signer_kids: list[bytes] = field(default_factory=list)
+    revoked: bool = False
+
+
+# -----------------------------------------------------------------------
+# Scoring
+# -----------------------------------------------------------------------
+
+
+class BidScorer(Protocol):
+    """Pluggable bid-scoring policy.
+
+    Implementations MUST be pure functions of (bid, requirements,
+    reputation_kernel). The `award()` agent verb invokes the configured
+    scorer for every received bid that passed the bidder_filter, then
+    awards the highest-scoring one.
+    """
+
+    def score(
+        self,
+        bid: Bid,
+        requirements: dict[str, Any],
+        reputation_kernel: ReputationKernel,
+        topic: str,
+    ) -> float:
+        """Return a real-valued score; higher wins ties resolved by bid_kid."""
+        ...
+
+
+class ReputationWeightedScorer:
+    """Default scorer: rep-weighted self-score with calibration shrinkage.
+
+    Score formula (∈ [0, 2.5] in practice):
+
+        score = (rep_score * calibration) * bid_score_self
+                + 0.05 * rep_score             # tie-breaker for equal self-score
+
+    where:
+      - ``rep_score`` is the Beta posterior mean for (bidder, topic) in
+        the supplied :class:`ReputationKernel`.
+      - ``calibration`` is the Brier-derived multiplicative shrinkage
+        in [0.5, 2.0] (same `calibration_adjustment` used by `consult()`),
+        defaulting to 1.0 when the agent has no oracle resolutions yet.
+      - ``bid_score_self`` is the bidder's claimed posterior on
+        delivering the requirement, supplied by the caller of `bid()`.
+
+    The `+ 0.05 * rep_score` term breaks ties when two bidders quote
+    identical self-scores — the higher-reputation bidder wins. This is
+    the property pinned by `tests/test_contract_net_reputation_scoring.py`.
+    """
+
+    def score(
+        self,
+        bid: Bid,
+        requirements: dict[str, Any],
+        reputation_kernel: ReputationKernel,
+        topic: str,
+    ) -> float:
+        rep_score = reputation_kernel.snapshot(bid.bidder_kid, topic).score
+        try:
+            calibration = reputation_kernel.calibration_adjustment(bid.bidder_kid, topic)
+        except Exception:
+            calibration = 1.0
+        weighted = rep_score * calibration * float(bid.bid_score_self)
+        return weighted + 0.05 * rep_score
+
+
+# -----------------------------------------------------------------------
+# Bidder-filter helpers
+# -----------------------------------------------------------------------
+
+
+def passes_bidder_filter(
+    bid: Bid,
+    bidder_filter: dict[str, Any] | None,
+    reputation_kernel: ReputationKernel,
+    topic: str,
+) -> tuple[bool, str | None]:
+    """Return (allowed, reject_rule_id).
+
+    The bidder_filter is an optional dict on the RFP_OPEN record. When
+    set, it carries:
+
+      - ``min_reputation`` (float in [0, 1]) — Sybil floor.
+      - ``topic`` (str) — must match the BID's RFP topic.
+
+    A bid that fails any predicate is rejected with rule_id
+    ``HM-CNP-BIDDER-FILTER`` (Sybil floor) — published as a BID_REJECT
+    record by the auctioneer before the AWARD is computed. This is the
+    SHOULD in spec §27.
+    """
+    if bidder_filter is None:
+        return True, None
+    min_rep = float(bidder_filter.get("min_reputation", 0.0))
+    if min_rep > 0.0:
+        score = reputation_kernel.snapshot(bid.bidder_kid, topic).score
+        if score < min_rep:
+            return False, "HM-CNP-BIDDER-FILTER"
+    return True, None
+
+
+__all__ = [
+    "AWARD_DOMAIN_TAG",
+    "RFP",
+    "Award",
+    "Bid",
+    "BidScorer",
+    "ReputationWeightedScorer",
+    "award_preimage",
+    "passes_bidder_filter",
+    "topic_scope_for_rfp",
+]

hypermind/crypto/__init__.py

@@ -0,0 +1,21 @@
+"""Cryptographic primitives — signing, hashing, HLC, domain tags.
+
+v0.1 emits Ed25519 only. ML-DSA-65 hybrid emission gated to v0.2 but
+`signature_alg` is in the signed COSE preimage from day 1 (A-ALG-BOUND).
+"""
+
+from hypermind.crypto.domain import DomainTag, domain_separated_hash
+from hypermind.crypto.hashing import blake3_32, sha256_kid
+from hypermind.crypto.hlc import HLC, HLCSkewError
+from hypermind.crypto.signing import Keypair, verify_ed25519
+
+__all__ = [
+    "HLC",
+    "DomainTag",
+    "HLCSkewError",
+    "Keypair",
+    "blake3_32",
+    "domain_separated_hash",
+    "sha256_kid",
+    "verify_ed25519",
+]

hypermind/crypto/cose_encrypt.py

@@ -0,0 +1,126 @@
+"""COSE_Encrypt0 (RFC 9052 §5.2) using HPKE-derived AEAD keys.
+
+Single-recipient L3 envelope: a canonical CBOR `[protected, unprotected, ciphertext]`
+where `protected` carries the HPKE suite id (`alg`) and recipient `kid`, while
+`unprotected` carries the encapsulated key (`enc`). AAD is bound by the caller
+and re-bound canonically over the protected header to mirror the A-ALG-BOUND
+discipline of `wire.py`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+import cbor2
+
+from hypermind.crypto import hpke
+
+# COSE header labels (RFC 9052 §3.1)
+_LABEL_ALG = 1
+_LABEL_KID = 4
+# HyperMind-private label for HPKE encapsulated key in the unprotected map.
+_LABEL_ENC = -1000
+
+
+class CoseEncryptError(ValueError):
+    """Raised on malformed or non-canonical COSE_Encrypt0 input."""
+
+
+def _det_cbor(obj: object) -> bytes:
+    return cbor2.dumps(obj, canonical=True)
+
+
+def _kid_for_pub(recipient_pub: bytes) -> bytes:
+    return hashlib.sha256(recipient_pub).digest()
+
+
+def _build_external_aad(protected_bytes: bytes, caller_aad: bytes) -> bytes:
+    # Bind the protected header bytes into the AEAD AAD so any tamper of the
+    # header (alg/kid) flips the tag. Mirrors `canonical_sig_input` in wire.py.
+    return _det_cbor([protected_bytes, caller_aad])
+
+
+def encrypt(suite_id: int, recipient_pub: bytes, aad: bytes, plaintext: bytes) -> bytes:
+    """Encrypt `plaintext` to `recipient_pub` under HPKE suite `suite_id`.
+
+    Args:
+        suite_id: HPKE suite id (see `hpke.SUITE_*`).
+        recipient_pub: Recipient X25519 public key (32 bytes).
+        aad: Caller additional authenticated data, bound by the AEAD.
+        plaintext: Bytes to encrypt.
+
+    Returns:
+        Canonical CBOR-encoded `COSE_Encrypt0` 3-tuple `[protected: bstr,
+        unprotected: map, ciphertext: bstr]`.
+    """
+    protected_map: dict[int, object] = {
+        _LABEL_ALG: int(suite_id),
+        _LABEL_KID: _kid_for_pub(recipient_pub),
+    }
+    protected_bytes = _det_cbor(protected_map)
+
+    external_aad = _build_external_aad(protected_bytes, aad)
+    # HPKE `info` is empty for L3 envelope; suite_id + kid already domain-bound
+    # via the AEAD AAD.
+    enc, ct = hpke.seal(suite_id, recipient_pub, b"", external_aad, plaintext)
+
+    unprotected: dict[int, object] = {_LABEL_ENC: enc}
+    return _det_cbor([protected_bytes, unprotected, ct])
+
+
+def decrypt(recipient_priv: bytes, cose_encrypt0_bytes: bytes, aad: bytes) -> bytes:
+    """Decrypt a COSE_Encrypt0 envelope.
+
+    Args:
+        recipient_priv: Recipient X25519 private key (32 bytes).
+        cose_encrypt0_bytes: Canonical CBOR output of `encrypt()`.
+        aad: Same caller AAD passed to `encrypt()`.
+
+    Returns:
+        Decrypted plaintext bytes.
+
+    Raises:
+        CoseEncryptError: malformed or non-canonical input.
+        cryptography.exceptions.InvalidTag: AEAD verification failed (tampered
+            ciphertext, AAD mismatch, or wrong recipient key).
+    """
+    try:
+        msg = cbor2.loads(cose_encrypt0_bytes)
+    except cbor2.CBORDecodeError as e:
+        raise CoseEncryptError(f"not valid CBOR: {e}") from e
+
+    if not isinstance(msg, list) or len(msg) != 3:
+        raise CoseEncryptError("COSE_Encrypt0 must be a 3-element array")
+    protected_bytes, unprotected, ciphertext = msg
+    if not isinstance(protected_bytes, bytes):
+        raise CoseEncryptError("protected must be bstr")
+    if not isinstance(unprotected, dict):
+        raise CoseEncryptError("unprotected must be a map")
+    if not isinstance(ciphertext, bytes):
+        raise CoseEncryptError("ciphertext must be bstr")
+
+    try:
+        protected = cbor2.loads(protected_bytes)
+    except cbor2.CBORDecodeError as e:
+        raise CoseEncryptError(f"protected header is not valid CBOR: {e}") from e
+    if not isinstance(protected, dict):
+        raise CoseEncryptError("protected header must be a CBOR map")
+
+    # Strict canonical re-encode gate (A-ALG-BOUND parity with wire.py).
+    if _det_cbor(protected) != protected_bytes:
+        raise CoseEncryptError("non-canonical protected header encoding")
+    if _det_cbor(msg) != cose_encrypt0_bytes:
+        raise CoseEncryptError("non-canonical COSE_Encrypt0 encoding")
+
+    if _LABEL_ALG not in protected or _LABEL_KID not in protected:
+        raise CoseEncryptError("protected header missing alg or kid")
+    suite_id = protected[_LABEL_ALG]
+    if not isinstance(suite_id, int):
+        raise CoseEncryptError("alg must be int")
+
+    enc = unprotected.get(_LABEL_ENC)
+    if not isinstance(enc, bytes):
+        raise CoseEncryptError("unprotected map missing HPKE enc bstr")
+
+    external_aad = _build_external_aad(protected_bytes, aad)
+    return hpke.open(suite_id, recipient_priv, enc, b"", external_aad, ciphertext)

hypermind/crypto/dkg.py

@@ -0,0 +1,246 @@
+"""Pedersen distributed key generation (ROADMAP §0.2.3).
+
+Implements the GJKR99 / Pedersen DKG protocol layer on Ed25519. The
+output is a t-of-n share set whose group public key matches the FROST
+trusted-dealer derivation in :mod:`hypermind.crypto.frost`, so an
+existing FROST signer can consume DKG-derived shares without code
+changes.
+
+Protocol (3 rounds):
+
+  Round 1
+      Each participant *i* picks a random degree-(t-1) polynomial
+      ``f_i`` with ``f_i(0)`` as their secret-share contribution.
+      Broadcasts public commitments
+      ``C_i = [f_i.coeff[k] * G for k in 0..t-1]``.
+
+  Round 2
+      Sends ``s_{i→j} = f_i(j)`` privately to each *j*. Receivers verify
+      the share against ``C_i`` by checking
+      ``s_{i→j} * G == sum(j**k * C_i[k] for k in range(t))``.
+      Misbehaving participants are added to a complaint set.
+
+  Round 3
+      The qualifying set ``Q`` excludes any participant who failed share
+      verification or did not deliver. Each remaining participant
+      computes their final share ``s_i = sum(f_j(i) for j in Q)`` and
+      the group public key ``Y = sum(C_j[0] for j in Q)``.
+
+Security properties:
+
+  * No single participant ever sees the group secret.
+  * As long as at least *t* honest participants remain in *Q*, the
+    group key is a valid (t, n) Shamir share of an unbiased random
+    secret in [0, L).
+  * Malicious participants are detected by share verification — every
+    receiver can publicly prove that participant *j* sent a bad share.
+
+This module ships the **protocol layer**. Ceremony tooling (offline
+coordinator, paper-tape transcripts, signed round receipts) lands at
+v0.7 with the witness-onboarding work — see ROADMAP §0.7.
+"""
+
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass, field
+
+from nacl.bindings import (
+    crypto_core_ed25519_add,
+    crypto_core_ed25519_scalar_add,
+    crypto_core_ed25519_scalar_mul,
+    crypto_scalarmult_ed25519_base_noclamp,
+    crypto_scalarmult_ed25519_noclamp,
+)
+
+from hypermind.crypto.frost import (
+    FrostShare,
+    L,
+    _validate_point,
+    _validate_scalar,
+    random_scalar,
+    scalar_from_int,
+)
+
+
+@dataclass(frozen=True)
+class ParticipantState:
+    """Local state held by a single DKG participant.
+
+    Attributes:
+        index: 1-based participant id (matches FROST share index).
+        coefficients: List of *t* secret scalars (private; never leaves
+            the participant). ``coefficients[0]`` is the participant's
+            secret contribution to the group key.
+        commitments: List of *t* public points
+            ``coefficients[k] * G``. Broadcast at end of Round 1.
+    """
+
+    index: int
+    coefficients: tuple[bytes, ...]
+    commitments: tuple[bytes, ...]
+
+
+@dataclass
+class DkgSession:
+    """In-process Pedersen DKG coordinator.
+
+    The session orchestrates all three rounds for ``n`` simulated
+    participants. Real deployments split this across processes; the
+    in-process simulator is suitable for tests, sandboxes, and
+    pre-ceremony rehearsal.
+    """
+
+    threshold: int
+    participants: int
+    _states: dict[int, ParticipantState] = field(default_factory=dict)
+    # round-2 received shares: {receiver_index: {sender_index: scalar}}
+    _received: dict[int, dict[int, bytes]] = field(default_factory=dict)
+    # qualifying set after round 2 (None until round 2 completes)
+    _qualifying: set[int] | None = None
+
+    def __post_init__(self) -> None:
+        if not (1 <= self.threshold <= self.participants):
+            raise ValueError("require 1 <= threshold <= participants")
+        if self.participants < 1:
+            raise ValueError("participants must be >= 1")
+
+    # ---- round 1 ------------------------------------------------------
+
+    def round1(self, *, rng_seed: int | None = None) -> dict[int, tuple[bytes, ...]]:
+        """Generate every participant's polynomial + commitments.
+
+        Returns a public broadcast: ``{participant_index: commitments}``.
+        """
+        rand = secrets.SystemRandom() if rng_seed is None else None
+        for i in range(1, self.participants + 1):
+            coeffs = tuple(random_scalar() for _ in range(self.threshold))
+            commits = tuple(crypto_scalarmult_ed25519_base_noclamp(c) for c in coeffs)
+            self._states[i] = ParticipantState(index=i, coefficients=coeffs, commitments=commits)
+            self._received[i] = {}
+        _ = rand  # unused; future hook for testable RNG injection
+        return {i: s.commitments for i, s in self._states.items()}
+
+    # ---- round 2 ------------------------------------------------------
+
+    def round2(
+        self,
+        *,
+        tampered_shares: dict[tuple[int, int], bytes] | None = None,
+    ) -> set[int]:
+        """Distribute private shares and verify them.
+
+        ``tampered_shares`` simulates a malicious participant: a
+        ``{(sender, receiver): bad_scalar}`` map replaces the otherwise
+        correct ``f_sender(receiver)`` with ``bad_scalar``. Receivers
+        detect the tampering via the public commitments and add the
+        sender to the complaint set.
+
+        Returns the qualifying set *Q* — participants whose shares
+        verified against their commitments.
+        """
+        if not self._states:
+            raise RuntimeError("call round1() before round2()")
+        complaints: set[int] = set()
+        tampered_shares = tampered_shares or {}
+
+        for sender_idx, sender in self._states.items():
+            for receiver_idx in range(1, self.participants + 1):
+                share = tampered_shares.get((sender_idx, receiver_idx)) or _evaluate_polynomial(
+                    sender.coefficients, receiver_idx
+                )
+                # Verify share against sender's public commitments.
+                if not _verify_share(share, receiver_idx, sender.commitments):
+                    complaints.add(sender_idx)
+                    continue
+                self._received[receiver_idx][sender_idx] = share
+
+        qualifying = set(self._states.keys()) - complaints
+        if len(qualifying) < self.threshold:
+            raise ValueError(
+                f"DKG aborted: qualifying set size {len(qualifying)} below "
+                f"threshold {self.threshold} after {len(complaints)} complaint(s)"
+            )
+        self._qualifying = qualifying
+        return qualifying
+
+    # ---- round 3 ------------------------------------------------------
+
+    def finalize(self) -> tuple[bytes, list[FrostShare]]:
+        """Compute the group public key and per-participant FROST shares.
+
+        Only members of the qualifying set *Q* receive a final share.
+        The returned shares are interoperable with
+        :mod:`hypermind.crypto.frost` (same scalar/point encoding,
+        identical Lagrange reconstruction).
+        """
+        if self._qualifying is None:
+            raise RuntimeError("call round2() before finalize()")
+
+        # Group public key Y = sum_{j in Q} C_j[0]
+        group_pk: bytes | None = None
+        for j in sorted(self._qualifying):
+            c0 = self._states[j].commitments[0]
+            group_pk = c0 if group_pk is None else crypto_core_ed25519_add(group_pk, c0)
+        assert group_pk is not None
+        _validate_point(group_pk)
+
+        shares: list[FrostShare] = []
+        for i in sorted(self._qualifying):
+            # s_i = sum_{j in Q} f_j(i)
+            acc = scalar_from_int(0)
+            for j in sorted(self._qualifying):
+                share_ji = self._received[i].get(j)
+                if share_ji is None:
+                    raise RuntimeError(f"participant {i} did not receive share from {j}")
+                acc = crypto_core_ed25519_scalar_add(acc, share_ji)
+            shares.append(FrostShare(index=i, secret=acc, group_public=group_pk))
+        return group_pk, shares
+
+
+# ---- helpers ----------------------------------------------------------
+
+
+def _evaluate_polynomial(coeffs: tuple[bytes, ...], x: int) -> bytes:
+    """Evaluate ``f(x) = sum_k coeffs[k] * x^k`` mod L."""
+    if x <= 0:
+        raise ValueError("polynomial evaluation point must be > 0")
+    x_pow = scalar_from_int(1)
+    x_step = scalar_from_int(x)
+    acc = scalar_from_int(0)
+    for k, a_k in enumerate(coeffs):
+        term = crypto_core_ed25519_scalar_mul(a_k, x_pow)
+        acc = crypto_core_ed25519_scalar_add(acc, term)
+        if k < len(coeffs) - 1:
+            x_pow = crypto_core_ed25519_scalar_mul(x_pow, x_step)
+    return acc
+
+
+def _verify_share(share: bytes, receiver_idx: int, commitments: tuple[bytes, ...]) -> bool:
+    """Check ``share * G == sum_k receiver_idx^k * commitments[k]``."""
+    try:
+        _validate_scalar(share)
+    except ValueError:
+        return False
+
+    # LHS: share * G
+    lhs = crypto_scalarmult_ed25519_base_noclamp(share)
+
+    # RHS: sum_k (receiver_idx^k mod L) * commitments[k]
+    rhs: bytes | None = None
+    x_pow_int = 1
+    for _k, C_k in enumerate(commitments):
+        scalar = scalar_from_int(x_pow_int)
+        term = crypto_scalarmult_ed25519_noclamp(scalar, C_k)
+        rhs = term if rhs is None else crypto_core_ed25519_add(rhs, term)
+        x_pow_int = (x_pow_int * receiver_idx) % L
+    return lhs == rhs
+
+
+def run_dkg(threshold: int, participants: int) -> tuple[bytes, list[FrostShare]]:
+    """One-shot helper: execute all three rounds with no malicious
+    participants. Returns ``(group_public_key, shares)``."""
+    session = DkgSession(threshold=threshold, participants=participants)
+    session.round1()
+    session.round2()
+    return session.finalize()

hypermind/crypto/domain.py

@@ -0,0 +1,59 @@
+"""Domain-separation tags (spec/02-cryptography.md §3.2).
+
+Every cryptographic operation prefixes its preimage with a single byte
+tag from this enum. Verifiers MUST reject any verification where the
+expected tag does not match. This is the WF-DOMAIN refinement lemma —
+it prevents cross-protocol signature substitution.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from enum import IntEnum
+
+
+class DomainTag(IntEnum):
+    """Reserved domain-separation tags."""
+
+    ENVELOPE_SIGNATURE = 0x01
+    KID = 0x02
+    RID = 0x03  # receipt id
+    AGENT_CARD_CID = 0x04
+    RECEIPT_BODY = 0x05
+    ROTATION_RECEIPT = 0x06
+    SUCCESSION = 0x07
+    STH_LEAF = 0x08
+    COUNCIL_COSIG = 0x09
+    VC_ANCHOR = 0x0A
+    PROOF_RECORD = 0x0B
+    STATE_HASH = 0x0C
+    EMBED_RESP = 0x0D
+    MENTOR_SLASH = 0x0E
+    SEAL_REVOKE = 0x0F
+    CIVIC_REPUTATION_ENTRY = 0x10
+    MEMORIAL_BUMP = 0x11
+    # 0x12–0x17 — TAL (room_define, room_join, vouch, vouch_revoke,
+    #               reputation_attestation, trust_query/reply)
+    TAL_ROOM_DEFINE = 0x12
+    TAL_ROOM_JOIN = 0x13
+    TAL_VOUCH = 0x14
+    TAL_VOUCH_REVOKE = 0x15
+    TAL_REPUTATION_ATTESTATION = 0x16
+    TAL_TRUST_QUERY = 0x17
+    # P2-16: KNOWS_DELTA gossip message type
+    KNOWS_DELTA = 0x18
+    # 0x19–0xFF reserved
+
+
+def domain_separated_hash(tag: DomainTag, payload: bytes) -> bytes:
+    """SHA-256 over `tag || payload`. The single canonical hash op."""
+    h = hashlib.sha256()
+    h.update(bytes([int(tag)]))
+    h.update(payload)
+    return h.digest()
+
+
+def reject_unallocated(tag_byte: int) -> None:
+    """Verifier MUST reject envelopes whose first byte is in 0x19..0xFF."""
+    if tag_byte > 0x18:
+        raise ValueError(f"unallocated domain tag 0x{tag_byte:02X}; reject envelope")