# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-opentelemetry-genai-tool-call-spans-as-non-atomic-for-token-accounting.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-opentelemetry-genai-tool-call-spans-as-non-atomic-for-token-accounting.warrant.json
# Markdown SHA-256:   4a8c33306da38f48f985622d7776074c1c77c6bda644024f66a87c111e605579
# Code AST SHA-256:   32973d7ec9a29d7acb336808595ed62cd14b121008ebc4b98bf8c914c953ce32
# Verified Classes:   UsageAccountingError, Span, UsageRecord
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from typing import Iterable, Optional


class UsageAccountingError(RuntimeError):
    """Raised when usage aggregation would violate the tool-span exclusion invariant."""


@dataclass(frozen=True)
class Span:
    span_id: str
    operation_name: Optional[str]  # gen_ai.operation.name
    input_tokens: Optional[int]    # gen_ai.usage.input_tokens
    output_tokens: Optional[int]   # gen_ai.usage.output_tokens


@dataclass(frozen=True)
class UsageRecord:
    input_tokens: Optional[int]
    output_tokens: Optional[int]
    partial: bool
    warnings: tuple[str, ...]


def aggregate_usage(spans: Iterable[Span]) -> UsageRecord:
    """
    Aggregate token usage for a single model call.

    Invariant: only the span with operation_name == "chat" is a usage source.
    Tool spans (operation_name == "execute_tool") are NEVER summed, even if
    they carry gen_ai.usage.* attributes. Absent usage is unknown, not zero.
    """
    spans = list(spans)
    chat_spans = [s for s in spans if s.operation_name == "chat"]
    tool_spans = [s for s in spans if s.operation_name == "execute_tool"]

    if not chat_spans:
        if tool_spans:
            raise UsageAccountingError(
                f"{len(tool_spans)} execute_tool span(s) present with no chat span; "
                "refusing to synthesize usage from tool spans"
            )
        raise UsageAccountingError("no chat span found in span set")

    if len(chat_spans) > 1:
        raise UsageAccountingError(
            f"multiple chat spans ({len(chat_spans)}) in a single aggregation scope; "
            "usage source of record is ambiguous"
        )

    chat = chat_spans[0]
    warnings: list[str] = []

    for tool in tool_spans:
        if tool.input_tokens is not None or tool.output_tokens is not None:
            warnings.append(
                f"tool span {tool.span_id} carries gen_ai.usage.* attributes; "
                "ignored for billing (tool spans are not token-bearing)"
            )

    partial = chat.input_tokens is None or chat.output_tokens is None
    if partial:
        warnings.append(
            f"chat span {chat.span_id} has partial usage "
            f"(input={chat.input_tokens}, output={chat.output_tokens}); "
            "treating missing side as UNKNOWN, not zero"
        )

    return UsageRecord(
        input_tokens=chat.input_tokens,
        output_tokens=chat.output_tokens,
        partial=partial,
        warnings=tuple(warnings),
    )


def enforce_quota(record: UsageRecord, remaining_input: int) -> None:
    """Fail closed: unknown usage must not be treated as zero."""
    if record.partial or record.input_tokens is None:
        raise UsageAccountingError(
            "cannot enforce quota on partial/unknown usage; "
            "defer or deny rather than defaulting to zero"
        )
    if record.input_tokens > remaining_input:
        raise UsageAccountingError(
            f"input token usage {record.input_tokens} exceeds remaining quota {remaining_input}"
        )
