# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-invariants-prevent-tool-call-span-corruption-under-opentelemetry-genai-semantic-conventions.md
# Remnant Warrant:    https://corpusfetch.com/c/which-invariants-prevent-tool-call-span-corruption-under-opentelemetry-genai-semantic-conventions.warrant.json
# Markdown SHA-256:   d22e9e4311aee8368d9198f059ebcd47c7bed4648c2723f75090241e1f5448d0
# Code AST SHA-256:   9eeee49902c96d02d58fffbb2084dea8f1754e36cb0003938394dcd156b5a089
# Verified Classes:   ToolCallParentageError, TurnSpan
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass, field


class ToolCallParentageError(RuntimeError):
    """Raised when a tool-call span violates the one-span-per-call-id,
    parented-to-requesting-turn invariant of the GenAI conventions."""


@dataclass
class TurnSpan:
    span_id: str
    finish_reasons: list[str] = field(default_factory=list)
    requested_call_ids: set[str] = field(default_factory=set)
    child_call_ids: set[str] = field(default_factory=set)


def register_tool_span(
    turn: TurnSpan,
    *,
    call_id: str,
    parent_span_id: str,
    tool_name: str,
) -> None:
    if not call_id:
        raise ToolCallParentageError(
            "tool-call span emitted without gen_ai.tool.call.id; "
            "parentage cannot be verified"
        )
    if parent_span_id != turn.span_id:
        raise ToolCallParentageError(
            f"tool call {call_id!r} parented to {parent_span_id!r}, "
            f"but requesting turn is {turn.span_id!r}"
        )
    if call_id in turn.child_call_ids:
        raise ToolCallParentageError(
            f"duplicate tool-call span for call id {call_id!r} under turn "
            f"{turn.span_id!r}; exactly one span per call id is required"
        )
    if call_id not in turn.requested_call_ids:
        raise ToolCallParentageError(
            f"tool call {call_id!r} has no matching request on turn "
            f"{turn.span_id!r}; finish_reasons={turn.finish_reasons!r}"
        )
    turn.child_call_ids.add(call_id)


def close_turn(turn: TurnSpan) -> None:
    if "tool_calls" in turn.finish_reasons:
        missing = turn.requested_call_ids - turn.child_call_ids
        if missing:
            raise ToolCallParentageError(
                f"turn {turn.span_id!r} closed with finish_reason 'tool_calls' "
                f"but call ids {sorted(missing)!r} have no child span; "
                "emit an errored tool span or an explicit drop event"
            )
