# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-resolve-capability-negotiation-in-cross-protocol-bridging-between-mcp-tool-servers-and-a2a-agent-meshes.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-resolve-capability-negotiation-in-cross-protocol-bridging-between-mcp-tool-servers-and-a2a-agent-meshes.warrant.json
# Markdown SHA-256:   df182db5e727285c4c3558593b652f9764538c12398032709e81340a7fe04f28
# Code AST SHA-256:   6ed344935881a4b98d0e56132e2f9cdabd97a45bb77ba8b7b32f2eccd3745f8b
# Verified Classes:   CapabilityNegotiationError, SkillClaim, ToolClaim
# Defensive Guards:   6 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Mapping


class CapabilityNegotiationError(RuntimeError):
    """Raised when an A2A skill cannot be validly joined to an MCP tool."""


@dataclass(frozen=True)
class SkillClaim:
    peer_id: str
    skill: str
    input_modes: frozenset[str]
    epoch: int


@dataclass(frozen=True)
class ToolClaim:
    name: str
    accepted_modes: frozenset[str]
    required_fields: frozenset[str]
    epoch: int
    is_deprecated_alias: bool = False


def resolve_route(
    inbound_peer: str,
    inbound_skill: str,
    inbound_modes: frozenset[str],
    skills: Mapping[tuple[str, str], SkillClaim],
    tools: Mapping[str, ToolClaim],
) -> ToolClaim:
    key = (inbound_peer, inbound_skill)
    claim = skills.get(key)
    if claim is None:
        raise CapabilityNegotiationError(
            f"no skill {inbound_skill!r} registered for peer {inbound_peer!r}"
        )

    tool = tools.get(claim.skill)
    if tool is None:
        raise CapabilityNegotiationError(
            f"skill {claim.skill!r} has no backing MCP tool"
        )

    if tool.is_deprecated_alias:
        raise CapabilityNegotiationError(
            f"skill {claim.skill!r} resolves to deprecated alias; "
            f"refusing to route through narrowing alias"
        )

    if claim.epoch != tool.epoch:
        raise CapabilityNegotiationError(
            f"epoch skew: skill epoch {claim.epoch} != tool epoch {tool.epoch}"
        )

    if not inbound_modes.issubset(tool.accepted_modes):
        raise CapabilityNegotiationError(
            f"modality mismatch: inbound {sorted(inbound_modes)} "
            f"not accepted by tool {sorted(tool.accepted_modes)}"
        )

    if not tool.required_fields:
        raise CapabilityNegotiationError(
            f"tool {tool.name!r} declares no required fields; "
            f"schema join is unverifiable"
        )

    return tool
