# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-does-an-instance-of-a-runaway-agent-loop-appear-healthy-under-genai-semantic-convention-trace-level-anomaly-detection.md
# Remnant Warrant:    https://corpusfetch.com/c/why-does-an-instance-of-a-runaway-agent-loop-appear-healthy-under-genai-semantic-convention-trace-level-anomaly-detection.warrant.json
# Markdown SHA-256:   d4be5d610c2d05f9345395752b2a806c814058e5cc31c1a0cbc0db7132fca2b6
# Code AST SHA-256:   d2ca600da2d5799ff19a7d04222fb2d078256fc2c8a8a91281d7c66feec9c90e
# Verified Classes:   RunawayLoopDetected
# Defensive Guards:   1 fail-closed invariants (zero external deps)

import hashlib
import json
from collections import Counter
from typing import Any, Iterable


class RunawayLoopDetected(RuntimeError):
    """Raised when a single trace repeats an identical tool-call motif beyond its permitted cardinality."""
    pass


def _canonical_tool_arguments(arguments: dict[str, Any]) -> str:
    # Sort keys, drop volatile fields that never indicate semantic change.
    volatile = {"request_id", "trace_id", "timestamp", "nonce", "attempt"}
    cleaned = {k: v for k, v in arguments.items() if k not in volatile}
    return json.dumps(cleaned, sort_keys=True, separators=(",", ":"))


def _motif_key(span: dict[str, Any]) -> str | None:
    if span.get("gen_ai.operation.name") != "execute_tool":
        return None
    tool = span.get("gen_ai.tool.name")
    raw_args = span.get("gen_ai.tool.call.arguments", {})
    if tool is None:
        return None
    digest = hashlib.sha256(_canonical_tool_arguments(raw_args).encode()).hexdigest()[:16]
    return f"{tool}:{digest}"


def assert_no_runaway_loop(
    spans: Iterable[dict[str, Any]],
    max_repeats: int = 5,
) -> None:
    """
    Enforce the trace-internal motif-cardinality invariant.

    Scalar aggregates (latency, tokens, error rate) cannot see this pathology;
    only repeated identical (tool_name, canonicalized_arguments) tuples reveal it.
    """
    counts: Counter[str] = Counter()
    for span in spans:
        key = _motif_key(span)
        if key is not None:
            counts[key] += 1

    for motif, n in counts.items():
        if n > max_repeats:
            raise RunawayLoopDetected(
                f"Runaway agent loop: motif {motif!r} repeated {n} times "
                f"in a single trace (limit {max_repeats}). "
                f"Scalar trace metrics are expected to be nominal; "
                f"this predicate is the only signal."
            )
