# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-speculative-cross-branch-resource-reservations-as-invalid-before-arbitration-rather-than-as-advisory-hints.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-speculative-cross-branch-resource-reservations-as-invalid-before-arbitration-rather-than-as-advisory-hints.warrant.json
# Markdown SHA-256:   4f3b73d9ae00fc0072175ccf4a50139a7267e0ea833de2d981b8fb2c745df8de
# Code AST SHA-256:   39405071e4014ef4b161edc3c06b8ff5bbe10df853d40066a9e40f613a96fed4
# Verified Classes:   SpeculativeReservationMisuse, Reservation
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import FrozenSet


class SpeculativeReservationMisuse(RuntimeError):
    """Raised when a conditional (speculative) reservation is admitted as a bid."""


@dataclass(frozen=True)
class Reservation:
    branch_id: str
    units: int
    committed: bool
    claim_set: FrozenSet[str]  # locks/tools/schemas this reservation depends on


def admit_to_arbiter(res: Reservation, sibling_claim_sets: list[FrozenSet[str]]) -> bool:
    """
    Return True only if the reservation may be summed/ranked as a bid.
    Otherwise it must be demoted to a hint (return False) or raise if misused.
    """
    if not res.committed:
        # Speculative: must never reach additive arbitration as a bid.
        if any(res.claim_set & sib for sib in sibling_claim_sets):
            raise SpeculativeReservationMisuse(
                f"branch {res.branch_id!r} is speculative and shares claim set "
                f"{sorted(res.claim_set)} with a sibling; reservation is a hint, "
                f"not a bid — demote before arbitration"
            )
        return False  # demote to hint; do not sum

    if any(res.claim_set & sib for sib in sibling_claim_sets):
        raise SpeculativeReservationMisuse(
            f"committed branch {res.branch_id!r} shares claim set with a sibling; "
            f"mutually exclusive claims cannot both be admitted"
        )
    return True
