# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distinguish-a-failed-tool-call-from-a-successful-tool-call-that-returned-an-error-payload-in-opentelemetry-genai-agent-spans.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distinguish-a-failed-tool-call-from-a-successful-tool-call-that-returned-an-error-payload-in-opentelemetry-genai-agent-spans.warrant.json
# Markdown SHA-256:   0d37a08d1d8f230e29cdef8114c67ff3c802f1afca738e5909afcf65dcd43d25
# Code AST SHA-256:   927429f5d77ad3c2511fe2c6881c075f9fbb9574695960560f324a7a13322129
# Verified Classes:   ToolOutcomeAmbiguityError, ToolCallSpan
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from typing import Any, Mapping


class ToolOutcomeAmbiguityError(RuntimeError):
    """Raised when a tool-call span's status cannot be reconciled with its result payload."""


@dataclass(frozen=True)
class ToolCallSpan:
    name: str
    status: str  # "OK" | "ERROR"
    result: Any
    converted_from_exception: bool = False

    def semantic_outcome(self) -> str:
        if self.status == "ERROR":
            return "transport_failure"
        if self.converted_from_exception:
            return "swallowed_exception"
        if isinstance(self.result, Mapping) and "error" in self.result:
            return "semantic_error"
        return "success"


def classify(span: ToolCallSpan) -> str:
    outcome = span.semantic_outcome()
    if outcome == "swallowed_exception" and not span.converted_from_exception:
        # Defensive: the flag must be set at the catch site, not inferred later.
        raise ToolOutcomeAmbiguityError(
            f"tool {span.name!r} produced an exception-derived payload without "
            f"converted_from_exception=True; status={span.status} is unreliable"
        )
    if span.status == "OK" and outcome == "transport_failure":
        raise ToolOutcomeAmbiguityError(
            f"tool {span.name!r} has status=OK but classifies as transport_failure"
        )
    if span.status == "ERROR" and outcome == "success":
        raise ToolOutcomeAmbiguityError(
            f"tool {span.name!r} has status=ERROR but payload indicates success; "
            f"likely mis-instrumented empty-result handling"
        )
    return outcome


def success_rate(spans: list[ToolCallSpan]) -> float:
    if not spans:
        return 0.0
    successes = sum(1 for s in spans if classify(s) == "success")
    return successes / len(spans)
