fix(dwh): align adapter sampling contract

harness/tests/l0/test_db_sampling.py

@@ -6,7 +6,7 @@ import pytest
 
 from tht.config import LshConfig
 from tht.db.introspect import introspect
-from tht.db.sampling import is_text_type, unique_values_for_lsh
+from tht.db.sampling import distinct_values, is_text_type, sample_column, unique_values_for_lsh
 
 pytestmark = [pytest.mark.l0]
 
@@ -52,3 +52,16 @@ def test_unique_values_for_lsh_truncation_reported(admin_engine):
     truncated_cols = {(t.table, t.column) for t in truncated}
     # fct_ricoveri has several eligible text columns with distinct values
     assert any(t[0] == "fct_ricoveri" for t in truncated_cols)
+
+
+def test_adapter_sampling_is_distinct_and_frequency_ranked(admin_engine):
+    values = sample_column(admin_engine, "dw", "fct_ricoveri", "reparto", limit=2)
+    assert values == ["cardiologia", "pronto soccorso"]
+
+
+def test_adapter_distinct_values_reports_truncation(admin_engine):
+    result = distinct_values(
+        admin_engine, "dw", "fct_ricoveri", "reparto", max_values=1
+    )
+    assert result.values == ["cardiologia"]
+    assert result.truncated is True

harness/tests/test_dwh_adapters.py

@@ -1,8 +1,10 @@
 import pytest
+from sqlalchemy.exc import OperationalError
 
 from tht.config import DatabaseConfig, RestConfig
 from tht.execute import ExecutionError
-from tht.ports import DwhAdapter
+from tht.ports import DistinctValues, DwhAdapter
+from tht.rest.client import RestError
 
 
 def postgres_factory():
@@ -32,7 +34,7 @@ def rest_factory():
 @pytest.mark.parametrize("factory", [postgres_factory, rest_factory])
 def test_adapter_rejects_write_sql_without_using_transport(factory):
     with pytest.raises(ExecutionError, match="read-only enforcement"):
-        factory().run_query("delete from fact_sales")
+        factory().run_query("delete from fact_sales", limit=10)
 
 
 @pytest.mark.parametrize("factory", [postgres_factory, rest_factory])
@@ -40,3 +42,85 @@ def test_adapter_satisfies_dwh_protocol(factory):
     adapter = factory()
     assert isinstance(adapter, DwhAdapter)
     assert adapter.capabilities.introspection is True
+
+
+@pytest.mark.parametrize("factory", [postgres_factory, rest_factory])
+def test_run_query_requires_explicit_positive_limit(factory):
+    adapter = factory()
+    with pytest.raises(TypeError):
+        adapter.run_query("select 1")
+    with pytest.raises(ValueError, match="positive"):
+        adapter.run_query("select 1", limit=0)
+
+
+def test_postgres_sampling_delegates_to_paired_sampling_functions(monkeypatch):
+    adapter = postgres_factory()
+    calls = []
+    expected = DistinctValues(values=["A"], truncated=True)
+
+    monkeypatch.setattr(
+        "tht.adapters.dwh.postgres.sampling.sample_column",
+        lambda engine, schema, table, column, *, limit: calls.append(
+            (engine, schema, table, column, limit)
+        )
+        or ["A", "B"],
+    )
+    monkeypatch.setattr(
+        "tht.adapters.dwh.postgres.sampling.distinct_values",
+        lambda engine, schema, table, column: expected,
+    )
+
+    assert adapter.sample_column("sales", "region", limit=2) == ["A", "B"]
+    assert calls == [(adapter._engine, "dw", "sales", "region", 2)]
+    assert adapter.distinct_values("sales", "region") is expected
+
+
+def test_rest_sampling_delegates_and_translates_transport_errors(monkeypatch):
+    adapter = rest_factory()
+    expected = DistinctValues(values=["A", "B"], truncated=False)
+    monkeypatch.setattr(
+        "tht.adapters.dwh.thoth_rest.sampling.sample_column_rest",
+        lambda client, schema, table, column, *, limit: ["A", "B"],
+    )
+    monkeypatch.setattr(
+        "tht.adapters.dwh.thoth_rest.sampling.distinct_values_rest",
+        lambda client, schema, table, column: expected,
+    )
+    assert adapter.sample_column("sales", "region", limit=2) == ["A", "B"]
+    assert adapter.distinct_values("sales", "region") is expected
+
+    def fail(*args, **kwargs):
+        raise RestError("transport failed")
+
+    monkeypatch.setattr("tht.adapters.dwh.thoth_rest.sampling.sample_column_rest", fail)
+    monkeypatch.setattr("tht.adapters.dwh.thoth_rest.sampling.distinct_values_rest", fail)
+    with pytest.raises(ExecutionError, match="transport failed"):
+        adapter.sample_column("sales", "region", limit=2)
+    with pytest.raises(ExecutionError, match="transport failed"):
+        adapter.distinct_values("sales", "region")
+
+
+def test_rest_distinct_values_reports_transport_truncation():
+    from tht.db.sampling import distinct_values_rest
+
+    class Client:
+        def top_values(self, schema, table, column, limit):
+            assert (schema, table, column, limit) == ("dw", "sales", "region", 3)
+            return [{"value": "A"}, {"value": "B"}, {"value": "C"}]
+
+    result = distinct_values_rest(Client(), "dw", "sales", "region", max_values=2)
+    assert result == DistinctValues(values=["A", "B"], truncated=True)
+
+
+def test_postgres_health_only_normalizes_database_errors(monkeypatch):
+    adapter = postgres_factory()
+    database_error = OperationalError("select 1", {}, Exception("offline"))
+    monkeypatch.setattr("tht.adapters.dwh.postgres.ping", lambda engine: (_ for _ in ()).throw(database_error))
+    assert adapter.health().ok is False
+
+    monkeypatch.setattr(
+        "tht.adapters.dwh.postgres.ping",
+        lambda engine: (_ for _ in ()).throw(ValueError("programming bug")),
+    )
+    with pytest.raises(ValueError, match="programming bug"):
+        adapter.health()

harness/tests/test_dwh_port_contract.py

@@ -1,9 +1,14 @@
+from dataclasses import FrozenInstanceError
+
+import pytest
+
 from tht.execute import ExecResult, PlanSummary
 from tht.mschema.models import PhysicalSchema
 from tht.ports.dwh import (
     DwhAdapter,
     DwhCapabilities,
     DwhHealth,
+    DistinctValues,
     UnsupportedCapability,
 )
 
@@ -17,7 +22,7 @@ class FakeDwhAdapter:
     def introspect(self) -> PhysicalSchema:
         raise NotImplementedError
 
-    def run_query(self, sql: str, *, limit: int | None = None) -> ExecResult:
+    def run_query(self, sql: str, *, limit: int) -> ExecResult:
         raise NotImplementedError
 
     def explain(self, sql: str) -> PlanSummary:
@@ -26,7 +31,7 @@ class FakeDwhAdapter:
     def sample_column(self, table: str, column: str, *, limit: int) -> list[object]:
         raise NotImplementedError
 
-    def distinct_values(self, table: str, column: str) -> list[object]:
+    def distinct_values(self, table: str, column: str) -> DistinctValues:
         raise NotImplementedError
 
 
@@ -45,3 +50,13 @@ def test_contract_types_are_public_and_capabilities_are_immutable():
     assert capabilities.sampling is True
     assert capabilities.distinct_values is True
     assert issubclass(UnsupportedCapability, Exception)
+    with pytest.raises(FrozenInstanceError):
+        capabilities.explain = False
+
+
+def test_all_contract_types_are_exported_from_public_package():
+    from tht.ports import DistinctValues as PublicDistinctValues
+
+    result = PublicDistinctValues(values=["a"], truncated=True)
+    assert result.values == ["a"]
+    assert result.truncated is True