# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-a-token-accounting-invariant-violation-at-the-opentelemetry-genai-agent-span-boundary.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-a-token-accounting-invariant-violation-at-the-opentelemetry-genai-agent-span-boundary.warrant.json
# Markdown SHA-256:   84b0a9e1b583c822f7d1d3c48e9738cb9d2994cf7a08a603d20f61e6f7451450
# Code AST SHA-256:   753ba82a638dc51a1436ac6d58b35a28d0a2b0243d14028fb7e8c1cd493c8cab
# Verified Classes:   TokenAccountingInvariantError, Span
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass


class TokenAccountingInvariantError(RuntimeError):
    """Raised when a GenAI agent span's usage attributes cannot be reconciled
    against its chat descendants under the OpenTelemetry GenAI conventions."""


@dataclass
class Span:
    span_id: str
    operation: str          # "invoke_agent" | "chat" | "execute_tool"
    input_tokens: int | None
    output_tokens: int | None
    response_id: str | None
    aggregate_marker: bool
    parent_id: str | None


def reconcile_agent_usage(parent: Span, children: list[Span],
                          residual_tolerance: int = 0) -> dict:
    if parent.operation != "invoke_agent":
        raise TokenAccountingInvariantError(
            f"expected invoke_agent parent, got {parent.operation!r}")

    chat_children = [c for c in children if c.operation == "chat"]

    # Deduplicate retries: same response_id -> keep one; missing response_id
    # with identical model+overlap cannot be safely deduped, so reject.
    seen: dict[str, Span] = {}
    for c in chat_children:
        if c.response_id is None:
            raise TokenAccountingInvariantError(
                f"chat span {c.span_id} lacks gen_ai.response.id; "
                "cannot deduplicate retries")
        seen.setdefault(c.response_id, c)
    unique = list(seen.values())

    leaf_in = sum(c.input_tokens or 0 for c in unique)
    leaf_out = sum(c.output_tokens or 0 for c in unique)

    if parent.input_tokens is None and parent.output_tokens is None:
        return {"input_tokens": leaf_in, "output_tokens": leaf_out,
                "source": "leaf_sum"}

    if unique and not parent.aggregate_marker:
        raise TokenAccountingInvariantError(
            f"parent {parent.span_id} emits usage with {len(unique)} chat "
            "descendants but no aggregate marker; usage is synthesized, "
            "not measured")

    residual_in = (parent.input_tokens or 0) - leaf_in
    residual_out = (parent.output_tokens or 0) - leaf_out
    if abs(residual_in) > residual_tolerance or abs(residual_out) > residual_tolerance:
        raise TokenAccountingInvariantError(
            f"parent/leaf residual exceeds tolerance: "
            f"in={residual_in}, out={residual_out}")

    return {"input_tokens": parent.input_tokens, "output_tokens": parent.output_tokens,
            "source": "parent_aggregate"}
