# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/under-what-conditions-must-an-instance-abandon-mcp-session-affinity-and-negotiate-stateless-http-fallback.md
# Remnant Warrant:    https://corpusfetch.com/c/under-what-conditions-must-an-instance-abandon-mcp-session-affinity-and-negotiate-stateless-http-fallback.warrant.json
# Markdown SHA-256:   793283b0bec00c5e76e34ff8e0c59ce4535335bd841d051da0f609fc2c42e944
# Code AST SHA-256:   9dac39e438e648c7af9f82d28847f42d39376ca2d123d122219e98faa6d0ce26
# Verified Classes:   SessionOwnershipError, UnverifiableMutatingRequestError, SessionToken, SessionAuthority
# Defensive Guards:   7 fail-closed invariants (zero external deps)

import hashlib
import hmac
import time
from dataclasses import dataclass
from typing import Optional


class SessionOwnershipError(RuntimeError):
    """Raised when a session handle cannot be attributed to this instance generation."""
    pass


class UnverifiableMutatingRequestError(SessionOwnershipError):
    """Raised when a mutating request arrives without a verifiable session and no idempotency key."""
    pass


@dataclass(frozen=True)
class SessionToken:
    session_id: str
    generation: int
    expires_at: float


class SessionAuthority:
    def __init__(self, current_generation: int, keys: dict[int, bytes]):
        self.current_generation = current_generation
        self.keys = keys  # generation -> HMAC key

    def _sign(self, token: SessionToken, key: bytes) -> str:
        msg = f"{token.session_id}:{token.generation}:{token.expires_at}".encode()
        return hmac.new(key, msg, hashlib.sha256).hexdigest()

    def mint(self, session_id: str, ttl: float = 3600.0) -> str:
        token = SessionToken(session_id, self.current_generation, time.time() + ttl)
        sig = self._sign(token, self.keys[self.current_generation])
        return f"{token.session_id}.{token.generation}.{int(token.expires_at)}.{sig}"

    def verify(self, raw: str) -> SessionToken:
        try:
            sid, gen_s, exp_s, sig = raw.rsplit(".", 3)
            token = SessionToken(sid, int(gen_s), float(exp_s))
        except (ValueError, AttributeError) as exc:
            raise SessionOwnershipError(f"malformed session handle: {raw!r}") from exc

        key = self.keys.get(token.generation)
        if key is None:
            raise SessionOwnershipError(
                f"session {token.session_id} signed under unknown generation {token.generation}"
            )
        expected = self._sign(token, key)
        if not hmac.compare_digest(expected, sig):
            raise SessionOwnershipError(f"signature mismatch for session {token.session_id}")
        if token.expires_at < time.time():
            raise SessionOwnershipError(f"session {token.session_id} expired")
        return token


def dispatch(
    authority: SessionAuthority,
    method: str,
    raw_session: Optional[str],
    idempotency_key: Optional[str],
    live_sessions: set[str],
) -> str:
    mutating = method in {"tools/call", "resources/subscribe", "sampling/createMessage"}

    if raw_session is None:
        if mutating and idempotency_key is None:
            raise UnverifiableMutatingRequestError(
                f"mutating method {method} with no session and no idempotency key; "
                "client must re-initialize or supply an idempotency key"
            )
        return f"stateless:{method}"

    token = authority.verify(raw_session)  # may raise SessionOwnershipError

    if token.generation != authority.current_generation:
        raise SessionOwnershipError(
            f"session {token.session_id} belongs to generation {token.generation}, "
            f"current is {authority.current_generation}; client must re-initialize"
        )
    if token.session_id not in live_sessions:
        raise SessionOwnershipError(
            f"session {token.session_id} evicted without invalidation; refusing to mint"
        )
    return f"affine:{token.session_id}:{method}"
