from __future__ import annotations

from typing import Any, Protocol


class StateBackendError(RuntimeError):
    """Base exception for state backend failures."""


class StateCodecCompatibilityError(StateBackendError):
    """Raised when stored state is incompatible with current runtime codec version."""


class StateBackend(Protocol):
    def get(self, namespace: str, key: str) -> Any | None:
        ...

    def put(
        self,
        namespace: str,
        key: str,
        value: Any,
        ttl_seconds: float | None = None,
    ) -> None:
        ...

    def delete(self, namespace: str, key: str) -> None:
        ...

    def scan(
        self,
        namespace: str,
        *,
        prefix: str | None = None,
        limit: int | None = None,
    ) -> list[tuple[str, Any]]:
        ...

    def close(self) -> None:
        ...


__all__ = [
    "StateBackend",
    "StateBackendError",
    "StateCodecCompatibilityError",
]
