# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-when-genai-observability-exemplars-stop-linking-traces-to-eval-regressions.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-when-genai-observability-exemplars-stop-linking-traces-to-eval-regressions.warrant.json
# Markdown SHA-256:   b8f78ca892dd724cf37ac2ee96276b70b3a7838966cca2136eb810bcfea31c16
# Code AST SHA-256:   ba7820164972db25ac5d96baa460ad6fac39405668769f7ad8a04ed3e279fc81
# Verified Classes:   ExemplarLinkageError, Exemplar, TraceRecord
# Defensive Guards:   3 fail-closed invariants (zero external deps)

import hashlib
from dataclasses import dataclass


class ExemplarLinkageError(RuntimeError):
    """Raised when an eval-regression exemplar cannot be validly resolved to a trace."""
    pass


@dataclass(frozen=True)
class Exemplar:
    trace_id: str
    span_id: str
    prompt_template_hash: str
    model_config_version: str


@dataclass(frozen=True)
class TraceRecord:
    trace_id: str
    span_id: str
    prompt_template_hash: str
    model_config_version: str


def resolve_exemplar(exemplar: Exemplar, trace_store: dict) -> TraceRecord:
    key = (exemplar.trace_id, exemplar.span_id)
    record = trace_store.get(key)

    if record is None:
        raise ExemplarLinkageError(
            f"orphan exemplar: no trace for key={key}; "
            f"likely retention eviction or re-sharding"
        )

    if record.prompt_template_hash != exemplar.prompt_template_hash:
        raise ExemplarLinkageError(
            f"fingerprint drift on {key}: exemplar template "
            f"{exemplar.prompt_template_hash} != resolved "
            f"{record.prompt_template_hash}; treat as config-skew, "
            f"not retention fault"
        )

    if record.model_config_version != exemplar.model_config_version:
        raise ExemplarLinkageError(
            f"config-version skew on {key}: exemplar {exemplar.model_config_version} "
            f"!= resolved {record.model_config_version}; possible span-ID recycling "
            f"— halt attribution until resolver is fixed"
        )

    return record


def orphan_ratio(exemplars, trace_store) -> float:
    if not exemplars:
        return 0.0
    orphans = 0
    for ex in exemplars:
        if (ex.trace_id, ex.span_id) not in trace_store:
            orphans += 1
    return orphans / len(exemplars)
