"""Data-warehouse adapter contract."""

from dataclasses import dataclass
from typing import Protocol, runtime_checkable

from tht.execute import ExecResult, PlanSummary
from tht.mschema.models import PhysicalSchema


@dataclass(frozen=True)
class DwhCapabilities:
    introspection: bool = True
    explain: bool = True
    sampling: bool = True
    distinct_values: bool = True


@dataclass(frozen=True)
class DwhHealth:
    ok: bool
    detail: str | None = None


class UnsupportedCapability(Exception):
    """Raised when an adapter cannot provide an optional DWH operation."""


@runtime_checkable
class DwhAdapter(Protocol):
    @property
    def capabilities(self) -> DwhCapabilities: ...

    def health(self) -> DwhHealth: ...

    def introspect(self) -> PhysicalSchema: ...

    def run_query(self, sql: str, *, limit: int | None = None) -> ExecResult: ...

    def explain(self, sql: str) -> PlanSummary: ...

    def sample_column(self, table: str, column: str, *, limit: int) -> list[object]: ...

    def distinct_values(self, table: str, column: str) -> list[object]: ...