# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-does-an-instance-level-causal-span-link-fail-silently-when-a-subagent-re-emits-an-inherited-trace-context-after-a-fan-out-barrier.md
# Remnant Warrant:    https://corpusfetch.com/c/why-does-an-instance-level-causal-span-link-fail-silently-when-a-subagent-re-emits-an-inherited-trace-context-after-a-fan-out-barrier.warrant.json
# Markdown SHA-256:   9ccc53d5f4f61b28a80f6dba3314adca7fa8aeb3a440a6352855e6385741138e
# Code AST SHA-256:   41420df30fa8bc071d401b316f096f97004231bdfe3729ef1de30056e605cef0
# Verified Classes:   CausalLinkViolation, Span
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from dataclasses import dataclass
from typing import Optional


class CausalLinkViolation(RuntimeError):
    """Raised when a span's declared parent violates causal containment."""


@dataclass
class Span:
    trace_id: str
    span_id: str
    parent_span_id: Optional[str]
    name: str
    start_time: float
    end_time: float
    is_barrier: bool = False


def validate_causal_link(span: Span, parent: Optional[Span]) -> None:
    if parent is None:
        # Root span: no causal parent to check.
        return

    if parent.trace_id != span.trace_id:
        raise CausalLinkViolation(
            f"span {span.span_id} ({span.name}) declares parent {parent.span_id} "
            f"from a different trace ({parent.trace_id} != {span.trace_id})"
        )

    if span.start_time < parent.start_time:
        raise CausalLinkViolation(
            f"span {span.span_id} ({span.name}) starts at {span.start_time} "
            f"before its declared parent {parent.span_id} ({parent.name}) "
            f"starts at {parent.start_time}"
        )

    if span.start_time > parent.end_time:
        raise CausalLinkViolation(
            f"span {span.span_id} ({span.name}) starts at {span.start_time} "
            f"after its declared parent {parent.span_id} ({parent.name}) "
            f"ended at {parent.end_time}"
        )


def repair_post_barrier_parent(
    span: Span,
    declared_parent: Span,
    barrier: Span,
    sibling_children: list[Span],
) -> Span:
    """If a post-barrier span was mis-parented to a pre-barrier ancestor,
    re-parent it to the barrier. Detects the signature: the span starts
    before some sibling child of its declared parent has ended.
    """
    if not declared_parent.is_barrier:
        latest_sibling_end = max(
            (c.end_time for c in sibling_children if c.span_id != span.span_id),
            default=declared_parent.start_time,
        )
        if span.start_time < latest_sibling_end:
            if not barrier.is_barrier:
                raise CausalLinkViolation(
                    f"span {span.span_id} ({span.name}) appears to be post-barrier "
                    f"but candidate barrier {barrier.span_id} is not marked as a barrier"
                )
            return Span(
                trace_id=span.trace_id,
                span_id=span.span_id,
                parent_span_id=barrier.span_id,
                name=span.name,
                start_time=span.start_time,
                end_time=span.end_time,
            )
    return span
