# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-mcp-server-push-notifications-arriving-during-a-resumed-sse-stream-as-duplicates-versus-fresh-events.md
# Remnant Warrant:    https://corpusfetch.com/c/under-what-conditions-must-an-instance-treat-mcp-server-push-notifications-arriving-during-a-resumed-sse-stream-as-duplicates-versus-fresh-events.warrant.json
# Markdown SHA-256:   2dc69bf94a41ace57224d7cb0c25f94c51879fad63bc211c10c3aff7d8280199
# Code AST SHA-256:   9ce524739dec14f14bf8f276c0eca0f58f85e8c314ada4d3014f83ee38b49112
# Verified Classes:   NonIdempotentResumptionError, NotificationHandler
# Defensive Guards:   2 fail-closed invariants (zero external deps)

class NonIdempotentResumptionError(RuntimeError):
    """Raised when a client attempts to resume a stream whose notifications
    cannot be safely reconciled by a fixed-point handler."""
    pass


class NotificationHandler:
    def __init__(self, reconcile_is_fixed_point: bool):
        self._fixed_point = reconcile_is_fixed_point
        self._seen_event_ids: set[int] = set()

    def on_resume(self, last_event_id: int, buffered: list[dict]) -> None:
        if not self._fixed_point:
            # Resumption is unsafe: a replayed or coalesced notification
            # cannot be distinguished from a fresh one by payload alone,
            # and our reconciliation is order-sensitive / incremental.
            raise NonIdempotentResumptionError(
                f"refusing to resume from Last-Event-ID={last_event_id}: "
                f"notification handler is not a fixed point; "
                f"re-initialize the session instead"
            )
        for ev in buffered:
            eid = ev["id"]
            if eid in self._seen_event_ids:
                continue  # transport-level duplicate; safe to drop
            self._seen_event_ids.add(eid)
            self._reconcile(ev["payload"])

    def _reconcile(self, payload: dict) -> None:
        # Fixed-point reconciliation: invalidate + refetch, not apply-delta.
        uri = payload.get("uri")
        if uri is None:
            raise NonIdempotentResumptionError(
                f"notification without snapshot-reference URI cannot be "
                f"reconciled idempotently: {payload!r}"
            )
        self._invalidate(uri)

    def _invalidate(self, uri: str) -> None:
        ...
