# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/where-must-an-instance-of-a-streamable-mcp-session-re-derive-its-backpressure-credit-after-http-native-resumption-and-why-the-eventsource-last-event-i.md
# Remnant Warrant:    https://corpusfetch.com/c/where-must-an-instance-of-a-streamable-mcp-session-re-derive-its-backpressure-credit-after-http-native-resumption-and-why-the-eventsource-last-event-i.warrant.json
# Markdown SHA-256:   63ee69a0b6facc4e90b881d279161aa4885d056d8568754e539bc552ddf816be
# Code AST SHA-256:   9d7f00123af3e618f2261515625ba2b85cd89e2b81112cb9d93e37d9042e425a
# Verified Classes:   CreditLedgerInvariantError, SessionCreditState
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from dataclasses import dataclass, field
from typing import Optional


class CreditLedgerInvariantError(RuntimeError):
    """Raised when a resumed session's credit ledger cannot be reconstructed
    without violating the sent-watermark / acknowledged-ID boundary."""


@dataclass
class SessionCreditState:
    session_id: str
    window: int
    in_flight: int = 0
    sent_watermark: int = 0
    acknowledged_id: int = 0
    socket_generation: int = 0


def resume_session(
    state: SessionCreditState,
    client_last_event_id: int,
    client_receive_window: Optional[int],
) -> SessionCreditState:
    """Re-derive credit after HTTP-native resumption.

    Invariant: the new socket starts with full credit; pre-disconnect
    emit-time decrements are void. Replay boundary for *delivery* is
    acknowledged_id + 1; replay boundary for *credit* is
    max(acknowledged_id, sent_watermark) + 1.
    """
    if client_last_event_id > state.sent_watermark:
        raise CreditLedgerInvariantError(
            f"session {state.session_id}: client acknowledged event "
            f"{client_last_event_id} beyond server sent-watermark "
            f"{state.sent_watermark}; ledger cannot be trusted, "
            f"refusing to resume"
        )

    if client_last_event_id < 0:
        raise CreditLedgerInvariantError(
            f"session {state.session_id}: negative Last-Event-ID "
            f"{client_last_event_id} is not a valid acknowledgement"
        )

    new_window = state.window
    if client_receive_window is not None:
        if client_receive_window < 0:
            raise CreditLedgerInvariantError(
                f"session {state.session_id}: client advertised negative "
                f"receive window {client_receive_window}"
            )
        new_window = min(state.window, client_receive_window)

    # Credit ledger is per-socket: discard, do not reconcile.
    state.in_flight = 0
    state.window = new_window
    state.acknowledged_id = client_last_event_id
    state.socket_generation += 1
    # sent_watermark is preserved as a *replay* hint, not as a credit
    # source; the first replayed event re-consumes credit at replay time.
    return state
