# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-refuse-to-resume-an-mcp-streamable-http-session-after-a-transport-level-backpressure-stall.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-refuse-to-resume-an-mcp-streamable-http-session-after-a-transport-level-backpressure-stall.warrant.json
# Markdown SHA-256:   0d32c41d79c22c610e112083b7fa2eb0462f9e2143f7c71f055835fb8c57f154
# Code AST SHA-256:   d6a5e59f4f4f6a7a2bfb2de9c93f13973a2f8dd654005a2be33bc3a3a267ab1e
# Verified Classes:   McpResumeBoundaryError, McpSession
# Defensive Guards:   3 fail-closed invariants (zero external deps)

class McpResumeBoundaryError(RuntimeError):
    """Raised when an MCP streamable HTTP session cannot be safely resumed
    because the client's cursor has fallen below the server's retention floor,
    or because resumption would double-serve a connection still under
    intentional backpressure."""


class McpSession:
    def __init__(self, retention_floor: int, current_cursor: int, has_blocked_orphan: bool):
        self.retention_floor = retention_floor
        self.current_cursor = current_cursor
        self.has_blocked_orphan = has_blocked_orphan

    def resume(self, last_event_id: int) -> list:
        if last_event_id > self.current_cursor:
            raise McpResumeBoundaryError(
                f"cursor ahead of server: client={last_event_id} server={self.current_cursor}"
            )
        if last_event_id < self.retention_floor:
            # Gap is unavoidable; resuming would silently skip events.
            raise McpResumeBoundaryError(
                f"cursor {last_event_id} below retention floor {self.retention_floor}; "
                "session must be re-initialized, not resumed"
            )
        if self.has_blocked_orphan:
            # A prior connection is still open and blocked on backpressure.
            # Replaying now would double-serve and race the orphan's cleanup.
            raise McpResumeBoundaryError(
                "cannot resume while an orphaned connection holds pending "
                "backpressured writes; close orphan and drain first"
            )
        return list(range(last_event_id + 1, self.current_cursor + 1))
