refactor(dwh): define adapter contract

harness/tht/ports/dwh.py

@@ -0,0 +1,43 @@
+"""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]: ...