# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-a2a-v1-0-task-delegation-is-about-to-fail-at-the-cross-vendor-handshake-boundary.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-a2a-v1-0-task-delegation-is-about-to-fail-at-the-cross-vendor-handshake-boundary.warrant.json
# Markdown SHA-256:   f404c613531b172e9bb16c6ccf4c8b0b0bab5dfb2abf7f4cf40b663c0c44faab
# Code AST SHA-256:   6d889c03d4c0db551a18273600f82bda653b9f9c8dee0266638fe1a84862fdd1
# Verified Classes:   HandshakeConformanceError, AgentCard
# Defensive Guards:   2 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any


class HandshakeConformanceError(RuntimeError):
    """Raised when a cross-vendor A2A v1.0 handshake cannot be safely bound."""


@dataclass
class AgentCard:
    default_input_modes: list[str] = field(default_factory=list)
    security_schemes: set[str] = field(default_factory=set)
    capabilities: dict[str, bool] = field(default_factory=dict)
    skills: list[dict[str, Any]] = field(default_factory=list)


def preflight_structural_check(card: AgentCard, challenge_scheme: str | None = None) -> list[str]:
    """Return structural warning signals; empty list means the card is safe to probe."""
    signals: list[str] = []

    # Signal 1: skill-level re-declaration of a card-scope field.
    for skill in card.skills:
        if "inputModes" in skill or "outputModes" in skill:
            signals.append(f"skill '{skill.get('id', '?')}' re-declares card-scope modes")

    # Signal 2: auth challenge names a scheme absent from the card.
    if challenge_scheme is not None and challenge_scheme not in card.security_schemes:
        signals.append(f"WWW-Authenticate scheme '{challenge_scheme}' not in securitySchemes")

    # Signal 3: capability flag with no reachable method (caller supplies reachability map).
    return signals


def gate_delegation(
    card: AgentCard,
    challenge_scheme: str | None,
    probe: callable,
) -> None:
    """Gate a real delegation on a capability probe when structural signals fire."""
    signals = preflight_structural_check(card, challenge_scheme)
    if not signals:
        return  # card surface is consistent; proceed to bind

    # Signals fired: do not bind blind. Probe the minimum surface.
    try:
        probe_ok = probe()
    except Exception as exc:  # probe transport failure
        raise HandshakeConformanceError(
            f"capability probe failed for cross-vendor delegate: {exc!r}; signals={signals}"
        ) from exc

    if not probe_ok:
        raise HandshakeConformanceError(
            "advertised capability surface not enforced by delegate runtime; "
            f"refusing to bind task. structural signals: {signals}"
        )
    # Probe passed: caller may proceed, but only on the verified intersection.