# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/why-does-an-instance-lose-mcp-stream-resumption-when-the-transport-applies-backpressure-mid-chunk.md
# Remnant Warrant:    https://corpusfetch.com/c/why-does-an-instance-lose-mcp-stream-resumption-when-the-transport-applies-backpressure-mid-chunk.warrant.json
# Markdown SHA-256:   036a298da91eddb1e915be7692c2cc44d972561fbde7aa1f650aede4a1055860
# Code AST SHA-256:   9c5bd05961d53cc9b46c52f21dd42cd4c9efa114e622d7bccef9ab0eca1efd37
# Verified Classes:   StreamResumptionInvariantError, ReplayEntry, ReplayLog
# Defensive Guards:   4 fail-closed invariants (zero external deps)

import hashlib
from dataclasses import dataclass


class StreamResumptionInvariantError(RuntimeError):
    """Raised when an MCP stream resume would violate event payload durability."""
    pass


@dataclass(frozen=True)
class ReplayEntry:
    event_id: int
    payload: bytes

    @property
    def digest(self) -> str:
        return hashlib.sha256(self.payload).hexdigest()


class ReplayLog:
    """Authoritative, non-evicting-while-unacked replay log for one MCP session."""

    def __init__(self, hard_cap_bytes: int) -> None:
        self._entries: dict[int, ReplayEntry] = {}
        self._watermark: int = 0
        self._cap = hard_cap_bytes
        self._bytes = 0

    def append_flushed(self, payload: bytes) -> ReplayEntry:
        # ID assigned ONLY after the frame is durably flushed.
        self._watermark += 1
        entry = ReplayEntry(self._watermark, payload)
        if self._bytes + len(payload) > self._cap:
            raise StreamResumptionInvariantError(
                f"replay log cap {self._cap}B exceeded at event {entry.event_id}; "
                "emit event:overflow and close session"
            )
        self._entries[entry.event_id] = entry
        self._bytes += len(payload)
        return entry

    def resume_from(self, last_event_id: int) -> list[ReplayEntry]:
        if last_event_id > self._watermark:
            raise StreamResumptionInvariantError(
                f"client claims Last-Event-ID {last_event_id} > watermark "
                f"{self._watermark}; client state is ahead of server, refuse resume"
            )
        missing = [n for n in range(last_event_id + 1, self._watermark + 1)
                   if n not in self._entries]
        if missing:
            # This is the exact bug class: watermark advanced, payload evicted.
            raise StreamResumptionInvariantError(
                f"watermark {self._watermark} advanced past retained payloads; "
                f"missing event ids {missing[:5]}... — invariant violated"
            )
        return [self._entries[n] for n in range(last_event_id + 1, self._watermark + 1)]


def handle_resume(log: ReplayLog, last_event_id: int, expected_digest: str | None) -> list[ReplayEntry]:
    entries = log.resume_from(last_event_id)
    if expected_digest is not None and entries:
        if entries[0].digest != expected_digest:
            raise StreamResumptionInvariantError(
                f"resume digest mismatch at event {entries[0].event_id}: "
                f"client expected {expected_digest}, server has {entries[0].digest}"
            )
    return entries
