# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-reject-a-contract-net-award-when-the-winning-bid-s-execution-receipt-commits-to-a-state-root-the-awarder-cannot-ind.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-reject-a-contract-net-award-when-the-winning-bid-s-execution-receipt-commits-to-a-state-root-the-awarder-cannot-ind.warrant.json
# Markdown SHA-256:   746072f964f5d824d60bb8ea0f300bb94accee8c4bd8a1656c6114a38062322d
# Code AST SHA-256:   3bf42aa9e36b96310c9f8371285bd1aae455e0364d666946d95ecfb33b60b960
# Verified Classes:   UnrecomputableReceiptError, Receipt, Bid
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Optional


class UnrecomputableReceiptError(RuntimeError):
    """Raised when a winning bid's receipt commits to a state root the
    awarder cannot independently recompute and no trust delegation applies."""
    pass


@dataclass
class Receipt:
    canonicalizer_id: str
    verifier_manifest: str
    state_root: str
    signature_valid: bool


@dataclass
class Bid:
    agent_id: str
    cost: float
    receipt: Receipt


def award_contract(
    bids: list[Bid],
    local_canonicalizers: set[str],
    trusted_verifiers: set[str],
    allow_best_effort: bool = False,
) -> Bid:
    if not bids:
        raise UnrecomputableReceiptError("no bids to award")

    # Rank by cost; cheapest first.
    winner = min(bids, key=lambda b: b.cost)

    if not winner.receipt.signature_valid:
        raise UnrecomputableReceiptError(
            f"winning bid from {winner.agent_id} has invalid signature"
        )

    recomputable = winner.receipt.canonicalizer_id in local_canonicalizers
    delegated = winner.receipt.verifier_manifest in trusted_verifiers

    if not (recomputable or delegated):
        if allow_best_effort:
            # Explicit, priced downgrade: award but record unverified mode.
            winner.best_effort = True  # type: ignore[attr-defined]
            return winner
        raise UnrecomputableReceiptError(
            f"winning bid from {winner.agent_id} commits to state_root "
            f"{winner.receipt.state_root} under canonicalizer "
            f"'{winner.receipt.canonicalizer_id}', which is not in the local "
            f"verification registry, and verifier manifest "
            f"'{winner.receipt.verifier_manifest}' is not trust-delegated. "
            f"Bid is valid but award-invalid; reject and re-bid."
        )

    return winner