# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-reject-a-negotiated-capability-downgrade-during-a2a-v1-0-tool-contract-renegotiation.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-reject-a-negotiated-capability-downgrade-during-a2a-v1-0-tool-contract-renegotiation.warrant.json
# Markdown SHA-256:   4352d1436abd02a0a49b8854d399fe6c5aa68f8d9f44ad439b0190e87e1d3e78
# Code AST SHA-256:   9cda6c37e4780215922788633eedc0d11641b358106c181fa1db48adcb2611b3
# Verified Classes:   CapabilityDowngradeError, AgentCard
# Defensive Guards:   1 fail-closed invariants (zero external deps)

import hashlib
import json
from dataclasses import dataclass
from typing import FrozenSet


class CapabilityDowngradeError(RuntimeError):
    """Raised when a card refresh would subtract a granted capability or break the contract hash."""
    pass


@dataclass(frozen=True)
class AgentCard:
    agent_id: str
    tool_contract_version: str
    contract_hash: str
    capabilities: FrozenSet[str]


def _hash_payload(obj) -> str:
    return hashlib.sha256(json.dumps(obj, sort_keys=True).encode()).hexdigest()


def _version_lt(a: str, b: str) -> bool:
    # Ordinal comparison only; never used as a compatibility predicate by itself.
    pa = tuple(int(x) for x in a.split("."))
    pb = tuple(int(x) for x in b.split("."))
    return pa < pb


def renegotiate(granted: AgentCard, refreshed: AgentCard) -> AgentCard:
    if refreshed.contract_hash == granted.contract_hash:
        return refreshed  # identity preserved; safe in place

    additive = (
        not _version_lt(refreshed.tool_contract_version, granted.tool_contract_version)
        and granted.capabilities.issubset(refreshed.capabilities)
    )
    if additive:
        return refreshed

    raise CapabilityDowngradeError(
        f"rejecting subtractive downgrade for {granted.agent_id}: "
        f"granted={granted.tool_contract_version}/{granted.contract_hash[:8]} "
        f"caps={sorted(granted.capabilities)} -> "
        f"refreshed={refreshed.tool_contract_version}/{refreshed.contract_hash[:8]} "
        f"caps={sorted(refreshed.capabilities)}; re-handshake required"
    )
