# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/which-invariants-prevent-silent-event-loss-in-mcp-http-native-streaming-transports-with-resumable-sse-session-negotiation-for-stateless-agent-clients.md
# Remnant Warrant:    https://corpusfetch.com/c/which-invariants-prevent-silent-event-loss-in-mcp-http-native-streaming-transports-with-resumable-sse-session-negotiation-for-stateless-agent-clients.warrant.json
# Markdown SHA-256:   760c96e03142610dccaf176584e2c1289684e76b2bedec889d5c18554a484d70
# Code AST SHA-256:   2e494e3d7a5fe8277a0b12dd90a01896017b8b6861701fffa8dc13a675f68dfe
# Verified Classes:   ResumeGapError, SessionBuffer
# Defensive Guards:   4 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass


class ResumeGapError(RuntimeError):
    """Raised when a stateless client requests an SSE resume point the server
    can no longer honor. This must propagate, never be swallowed into a
    best-effort truncation, because silent truncation is undetectable by the
    client and violates the continuity invariant."""


@dataclass(frozen=True)
class SessionBuffer:
    first_retained_id: int
    last_emitted_id: int

    def can_resume_from(self, last_event_id: int) -> bool:
        # Safe iff the requested ID is still within the retained window.
        return self.first_retained_id <= last_event_id <= self.last_emitted_id


def negotiate_resume(
    session_id: str,
    last_event_id: int | None,
    buffer: SessionBuffer,
    session_is_live: bool,
) -> int:
    """Return the event ID the resumed stream will start after.

    Raises ResumeGapError if the client's durable position is unrecoverable.
    Never returns a 'nearest retained' position, which would silently drop
    events the client has not yet processed.
    """
    if not session_is_live:
        raise ResumeGapError(
            f"session {session_id!r} is no longer live; client must "
            f"re-negotiate and re-hydrate state"
        )

    if last_event_id is None:
        # Fresh stream, no prior position claimed.
        return buffer.last_emitted_id

    if last_event_id < buffer.first_retained_id:
        raise ResumeGapError(
            f"requested Last-Event-ID {last_event_id} for session "
            f"{session_id!r} was evicted; retained window is "
            f"[{buffer.first_retained_id}, {buffer.last_emitted_id}]. "
            f"Client must re-negotiate a fresh session."
        )

    if last_event_id > buffer.last_emitted_id:
        raise ResumeGapError(
            f"requested Last-Event-ID {last_event_id} for session "
            f"{session_id!r} is ahead of server position "
            f"{buffer.last_emitted_id}; client state is inconsistent."
        )

    return last_event_id


def handle_streamable_http_reconnect(
    headers: dict[str, str],
    buffer: SessionBuffer,
    session_is_live: bool,
) -> int:
    session_id = headers.get("Mcp-Session-Id")
    if not session_id:
        raise ResumeGapError("missing Mcp-Session-Id on reconnect")

    raw = headers.get("Last-Event-ID")
    last_event_id = int(raw) if raw is not None else None

    return negotiate_resume(session_id, last_event_id, buffer, session_is_live)
