# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/what-structural-signals-indicate-broken-trace-to-eval-exemplar-linkage-under-genai-semantic-conventions.md
# Remnant Warrant:    https://corpusfetch.com/c/what-structural-signals-indicate-broken-trace-to-eval-exemplar-linkage-under-genai-semantic-conventions.warrant.json
# Markdown SHA-256:   822af2c94545ccea623f93b5062a5ad8088e63d9bc063221764dd47a2aefc996
# Code AST SHA-256:   20c5a99febca2e0ccfe5ebc5df76d1f53577716049df20e8cbe023f82a666f41
# Verified Classes:   ExemplarLinkIntegrityError, SpanRecord, EvalRecord
# Defensive Guards:   6 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime, timedelta


class ExemplarLinkIntegrityError(RuntimeError):
    """Raised when an eval/safety exemplar link resolves but is semantically broken."""
    pass


@dataclass(frozen=True)
class SpanRecord:
    trace_id: str
    span_id: str
    response_id: str          # terminal completion identity, post-reassembly/retry
    end_time: datetime
    model_revision: str
    decoding: dict            # temperature, top_p, seed, ...


@dataclass(frozen=True)
class EvalRecord:
    trace_id: str
    span_id: str
    response_id: str          # completion the eval actually judged
    evaluated_at: datetime
    model_revision: str
    decoding: dict
    verdict: str


CLOCK_SKEW = timedelta(seconds=2)


def assert_link_valid(span: SpanRecord, ev: EvalRecord) -> None:
    """Enforce semantic integrity of a trace->eval exemplar link.

    Referential integrity (trace_id/span_id match) is assumed already checked.
    This function enforces the four validity conditions; any failure is a hard
    error so a reconciliation job cannot silently coerce an untrusted link.
    """
    if (span.trace_id, span.span_id) != (ev.trace_id, ev.span_id):
        raise ExemplarLinkIntegrityError(
            "referential mismatch: eval does not resolve to this span"
        )

    # Condition 1: response-identity equality.
    if span.response_id != ev.response_id:
        raise ExemplarLinkIntegrityError(
            f"response-identity divergence: span={span.response_id!r} "
            f"eval={ev.response_id!r}; eval judged a different completion"
        )

    # Condition 2: temporal ordering (no eval before terminal end, modulo skew).
    if ev.evaluated_at < span.end_time - CLOCK_SKEW:
        raise ExemplarLinkIntegrityError(
            f"temporal inversion: evaluated_at={ev.evaluated_at.isoformat()} "
            f"precedes end_time={span.end_time.isoformat()}; completion swap suspected"
        )

    # Condition 3: generation-condition subset match.
    if ev.model_revision != span.model_revision:
        raise ExemplarLinkIntegrityError(
            f"model revision drift: span={span.model_revision!r} eval={ev.model_revision!r}"
        )
    for k, v in ev.decoding.items():
        if span.decoding.get(k) != v:
            raise ExemplarLinkIntegrityError(
                f"decoding drift on {k!r}: span={span.decoding.get(k)!r} eval={v!r}"
            )


def reconcile(span: SpanRecord, evals: list[EvalRecord]) -> list[EvalRecord]:
    """Return only links that pass semantic integrity; quarantine the rest."""
    trusted: list[EvalRecord] = []
    for ev in evals:
        try:
            assert_link_valid(span, ev)
        except ExemplarLinkIntegrityError:
            # Quarantine: retain as orphan with untrusted status, never auto-join.
            continue
        trusted.append(ev)
    # Condition 4: fan-out ambiguity — a single terminal completion must not
    # carry multiple trusted evals with differing response identities.
    if len({ev.response_id for ev in trusted}) > 1:
        raise ExemplarLinkIntegrityError(
            "fan-out ambiguity: span absorbed multiple completions; link is ambiguous"
        )
    return trusted
