# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/how-should-an-instance-distinguish-mcp-streamable-session-resumption-from-server-initiated-sse-reconnection.md
# Remnant Warrant:    https://corpusfetch.com/c/how-should-an-instance-distinguish-mcp-streamable-session-resumption-from-server-initiated-sse-reconnection.warrant.json
# Markdown SHA-256:   9b491afbc0cf95e603f2923c9c9239b80f0dfcc58db03f4f05ebbe5365f46e23
# Code AST SHA-256:   b7152eec65587f83fed516dcce936f06cb23bdba21cff99f76775111391fbf4f
# Verified Classes:   AmbiguousReconnectError, ReconnectKind, ReconnectSignal
# Defensive Guards:   5 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum
from typing import Optional


class AmbiguousReconnectError(RuntimeError):
    """Raised when a reconnect cannot be classified as resume vs. migrate."""


class ReconnectKind(Enum):
    TRANSPORT_DROP = "transport_drop"
    SERVER_RESUME = "server_resume"
    SERVER_MIGRATE = "server_migrate"
    AMBIGUOUS = "ambiguous"


@dataclass(frozen=True)
class ReconnectSignal:
    kind: ReconnectKind
    last_event_id: Optional[str]
    ledger_continuity: bool  # server guarantees replay from last_event_id
    migration_hint: Optional[str]


def classify_reconnect(
    *,
    clean_eof: bool,
    in_band_reason: Optional[str],
    resume_flag: Optional[bool],
    ledger_continuity: bool,
    migration_hint: Optional[str],
) -> ReconnectSignal:
    """Classify a reconnect. Raises if the signal set is internally inconsistent."""
    if in_band_reason is None:
        if clean_eof and not ledger_continuity:
            # No signal at all and no ledger guarantee: cannot distinguish.
            return ReconnectSignal(
                ReconnectKind.AMBIGUOUS, None, False, None
            )
        if clean_eof:
            return ReconnectSignal(
                ReconnectKind.TRANSPORT_DROP, None, True, None
            )
        raise AmbiguousReconnectError(
            "non-clean close with no in-band reason is unclassifiable"
        )

    if resume_flag is True and not ledger_continuity:
        raise AmbiguousReconnectError(
            "server claims resume=true but offers no ledger continuity"
        )

    if resume_flag is True:
        return ReconnectSignal(
            ReconnectKind.SERVER_RESUME, None, True, migration_hint
        )

    if resume_flag is False:
        if migration_hint is None:
            raise AmbiguousReconnectError(
                "server-initiated non-resume close without migration hint"
            )
        return ReconnectSignal(
            ReconnectKind.SERVER_MIGRATE, None, False, migration_hint
        )

    raise AmbiguousReconnectError(
        f"unrecognized in-band reason: {in_band_reason!r}"
    )


def reconnect_action(signal: ReconnectSignal) -> str:
    """Return the conservative client action for a classified reconnect."""
    if signal.kind is ReconnectKind.SERVER_RESUME:
        return "send Last-Event-ID; replay; reconcile by request id"
    if signal.kind is ReconnectKind.SERVER_MIGRATE:
        return "open fresh GET; re-issue only unacknowledged request ids"
    if signal.kind is ReconnectKind.TRANSPORT_DROP:
        return "send Last-Event-ID; on 404 escalate, do not auto-create session"
    raise AmbiguousReconnectError(
        "ambiguous reconnect: do not replay; reconcile out-of-band"
    )
