# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-opentelemetry-genai-semantic-convention-drift-as-a-hard-pipeline-failure-rather-than-a-soft-warning.md
# Remnant Warrant:    https://corpusfetch.com/c/in-what-scenarios-must-an-instance-treat-opentelemetry-genai-semantic-convention-drift-as-a-hard-pipeline-failure-rather-than-a-soft-warning.warrant.json
# Markdown SHA-256:   f92b51f6bb63c9bc6d69de6af4620f8d510973afd76d014332c63cdf44d806e0
# Code AST SHA-256:   2c7a5334d20f1a751a1f3002387fe1fc2bd4a7ed846577e3c9ea113fe789ff3f
# Verified Classes:   ConventionConformanceError, ConventionVersionMismatch, EnumValueRejected, PinnedConvention
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum


class ConventionConformanceError(RuntimeError):
    """Base class for GenAI semantic-convention conformance failures."""


class ConventionVersionMismatch(ConventionConformanceError):
    """Attribute value present but belongs to a different pinned convention version."""


class EnumValueRejected(ConventionConformanceError):
    """Attribute value is outside the closed enum set for the pinned version."""


@dataclass(frozen=True)
class PinnedConvention:
    version: str
    operation_names: frozenset[str]


# Branching consumers switch on these values; a foreign value silently
# collapses agent-graph edges, so it must be a hard failure, not a warning.
PINNED = PinnedConvention(
    version="1.29.0",
    operation_names=frozenset({"chat", "invoke_agent", "execute_tool", "embeddings"}),
)

# Values known to originate from a different convention version.
FOREIGN_VERSION_OPERATIONS = frozenset({"text_completion", "generate_content"})


def validate_operation(span_attrs: dict[str, object], pinned: PinnedConvention) -> str:
    """Return the validated operation name or raise a hard conformance error.

    Absence is tolerated (soft path handled by caller); presence with an
    out-of-contract value is a hard failure because downstream branching
    consumers cannot distinguish redefinition from correctness.
    """
    value = span_attrs.get("gen_ai.operation.name")

    if value is None:
        # Soft path: caller records conformance_missing and continues.
        return ""

    if not isinstance(value, str):
        raise EnumValueRejected(
            f"gen_ai.operation.name has non-string type {type(value).__name__}"
        )

    if value in FOREIGN_VERSION_OPERATIONS:
        raise ConventionVersionMismatch(
            f"operation {value!r} belongs to a different convention version "
            f"than pinned {pinned.version!r}; producer SDK likely unpinned"
        )

    if value not in pinned.operation_names:
        raise EnumValueRejected(
            f"operation {value!r} not in pinned enum set "
            f"{sorted(pinned.operation_names)} for version {pinned.version}"
        )

    return value
