# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-does-an-instance-detect-trace-context-divergence-when-a-federated-peer-silently-re-roots-spans-under-a-different-trace-id.md
# Remnant Warrant:    https://corpusfetch.com/c/how-does-an-instance-detect-trace-context-divergence-when-a-federated-peer-silently-re-roots-spans-under-a-different-trace-id.warrant.json
# Markdown SHA-256:   dbe57c0747f092a1d2f95e659f13a7e957b0be5e55e6d45062504e4d473e26e3
# Code AST SHA-256:   abeaf2c521ec75ed09f693d1a1d44be609ec6dede37fb4416ccb6ec0e85fe13f
# Verified Classes:   TraceRootingDivergence, Span, FederationIndex
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass, field


class TraceRootingDivergence(RuntimeError):
    """Raised when a federated span's parent cannot be resolved in any runtime."""


@dataclass(frozen=True)
class Span:
    trace_id: str
    span_id: str
    parent_span_id: str | None
    runtime: str
    kind: str  # "client" | "server" | "internal"
    root_reason: str | None = None  # federation.root_reason allowlist


@dataclass
class FederationIndex:
    spans: dict[str, Span] = field(default_factory=dict)  # span_id -> Span

    def ingest(self, span: Span) -> None:
        if span.span_id in self.spans:
            raise TraceRootingDivergence(
                f"duplicate span_id {span.span_id} from runtime {span.runtime}"
            )
        self.spans[span.span_id] = span

    def resolve_parent(self, span: Span) -> Span | None:
        if span.parent_span_id is None:
            return None
        return self.spans.get(span.parent_span_id)


def validate_rooting(index: FederationIndex, skew_tolerant_roots: set[str]) -> list[Span]:
    """Return spans that dangle: their parent resolves to nothing in the federation."""
    orphans: list[Span] = []
    for span in index.spans.values():
        if span.parent_span_id is None:
            if span.root_reason not in skew_tolerant_roots:
                orphans.append(span)  # bare root with no declared reason
            continue
        parent = index.resolve_parent(span)
        if parent is None:
            orphans.append(span)
            continue
        if parent.trace_id != span.trace_id:
            # Parent exists but under a different trace: silent re-rooting.
            raise TraceRootingDivergence(
                f"span {span.span_id} (runtime {span.runtime}) claims parent "
                f"{span.parent_span_id} but trace_id diverges: "
                f"parent={parent.trace_id} child={span.trace_id}"
            )
    return orphans


def correlate_pair(client: Span, server: Span) -> None:
    """Enforce client/server pairing invariant at an RPC boundary."""
    if client.kind != "client" or server.kind != "server":
        raise TraceRootingDivergence(
            f"correlate_pair requires client/server kinds, got {client.kind}/{server.kind}"
        )
    if client.trace_id != server.trace_id:
        raise TraceRootingDivergence(
            f"RPC boundary re-rooted: client trace {client.trace_id} "
            f"!= server trace {server.trace_id} (runtime {server.runtime})"
        )
    if server.parent_span_id != client.span_id:
        raise TraceRootingDivergence(
            f"server span {server.span_id} parent {server.parent_span_id} "
            f"does not match client span {client.span_id}"
        )
