# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-treat-a-reconstructed-causal-trace-as-authoritative-rather-than-advisory.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-treat-a-reconstructed-causal-trace-as-authoritative-rather-than-advisory.warrant.json
# Markdown SHA-256:   5fb3c24c070bc955fe92de32fbdd2a6defdfcc64fa00f96735e85adceaaf63f1
# Code AST SHA-256:   8fa7e9dc1960efd6614874fdd20a72d9a25664f4a7182e36d94cb8b952f816d6
# Verified Classes:   AuthorityError, EdgeAuthority, AdvisoryReason, CausalEdge, Span
# Defensive Guards:   1 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from enum import Enum


class AuthorityError(RuntimeError):
    """Raised when a causal action is gated on a non-authoritative edge."""


class EdgeAuthority(Enum):
    AUTHORITATIVE = "authoritative"
    ADVISORY = "advisory"


class AdvisoryReason(Enum):
    TOKEN_VERIFIED = "token_verified"
    REPLAY_OVERLAY = "replay_overlay"
    TIMESTAMP_INFERRED = "timestamp_inferred"
    REKEYED = "rekeyed"


@dataclass(frozen=True)
class CausalEdge:
    parent_span_id: str
    child_span_id: str
    authority: EdgeAuthority
    reason: AdvisoryReason


@dataclass(frozen=True)
class Span:
    span_id: str
    parent_span_id: str | None
    trace_id: str
    is_replay: bool
    token_verified: bool
    rekeyed_at_federation: bool


def classify_edge(parent: Span, child: Span) -> CausalEdge:
    if child.parent_span_id != parent.span_id:
        # No explicit token linking child to parent: inferred, not causal.
        return CausalEdge(parent.span_id, child.span_id,
                          EdgeAuthority.ADVISORY, AdvisoryReason.TIMESTAMP_INFERRED)
    if child.rekeyed_at_federation or parent.rekeyed_at_federation:
        return CausalEdge(parent.span_id, child.span_id,
                          EdgeAuthority.ADVISORY, AdvisoryReason.REKEYED)
    if child.is_replay or parent.is_replay:
        # Replay spans do not participate in the live causal partial order.
        return CausalEdge(parent.span_id, child.span_id,
                          EdgeAuthority.ADVISORY, AdvisoryReason.REPLAY_OVERLAY)
    if not (child.token_verified and parent.token_verified):
        return CausalEdge(parent.span_id, child.span_id,
                          EdgeAuthority.ADVISORY, AdvisoryReason.TIMESTAMP_INFERRED)
    return CausalEdge(parent.span_id, child.span_id,
                      EdgeAuthority.AUTHORITATIVE, AdvisoryReason.TOKEN_VERIFIED)


def require_authoritative_causality(edges: list[CausalEdge], action: str) -> None:
    """Gate a causal-direction action on every edge being authoritative."""
    bad = [e for e in edges if e.authority is not EdgeAuthority.AUTHORITATIVE]
    if bad:
        raise AuthorityError(
            f"action {action!r} requires authoritative causality across "
            f"{len(edges)} edges; {len(bad)} are advisory: "
            + ", ".join(f"{e.parent_span_id}->{e.child_span_id}:{e.reason.value}" for e in bad)
        )


def suppress_policy_check(edges: list[CausalEdge]) -> None:
    # The action that caused the incident: only safe if causality is real.
    require_authoritative_causality(edges, action="suppress_policy_check")
    # ... suppression proceeds only when every edge is token-verified and live.
