Add normalized runtime adapters and shared result helpers.

Introduce canonical result/history summary models and QueryResult metadata/record helpers in hotdata-runtime, then lock the expanded contract and behavior with dedicated tests.

Author: eddietejeda

CONTRACT.md

@@ -27,6 +27,8 @@ The supported import surface is:
 - `normalize_host`
 - `pick_workspace`
 - `resolve_workspace_selection`
+- `ResultSummary`
+- `RunHistoryItem`
 - `WorkspaceSelection`
 
 Adapters should import from `hotdata_runtime` and treat this surface as the stable API.
@@ -42,6 +44,8 @@ Adapters should import from `hotdata_runtime` and treat this surface as the stab
 - `connections()` returns the connections API wrapper for adapter UI/status features.
 - `query_runs()` returns the query-runs API wrapper for adapter history views.
 - `results()` returns the results API wrapper for adapter result pickers.
+- `list_recent_results(...)` returns normalized `ResultSummary` entries.
+- `list_run_history(...)` returns normalized `RunHistoryItem` entries.
 - `list_qualified_table_names(...)` returns sorted fully qualified table names.
 - `columns_for_qualified(qualified, connection_id=...)` resolves table columns, and
   adapters should pass `connection_id` when known.
@@ -51,6 +55,8 @@ Adapters should import from `hotdata_runtime` and treat this surface as the stab
 - Canonical tabular result model with `columns`, `rows`, and `row_count`.
 - Carries server identifiers and execution metadata when available.
 - `to_pandas()` converts to a DataFrame with stable column ordering.
+- `to_records(max_rows=...)` returns row dicts keyed by column names.
+- `metadata_dict()` returns normalized result metadata for adapter rendering.
 
 ### Env Resolution
 

hotdata_runtime/__init__.py

@@ -2,7 +2,12 @@
 
 from importlib.metadata import PackageNotFoundError, version
 
-from hotdata_runtime.client import HotdataClient, from_env
+from hotdata_runtime.client import (
+    HotdataClient,
+    ResultSummary,
+    RunHistoryItem,
+    from_env,
+)
 from hotdata_runtime.env import (
     default_api_key,
     default_host,
@@ -36,5 +41,7 @@
     "normalize_host",
     "pick_workspace",
     "resolve_workspace_selection",
+    "ResultSummary",
+    "RunHistoryItem",
     "WorkspaceSelection",
 ]

hotdata_runtime/client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from dataclasses import asdict, dataclass
 import time
 from typing import Any, Iterator
 
@@ -28,6 +29,28 @@
 _RESULT_FAILURE = frozenset({"failed", "cancelled"})
 
 
+@dataclass(frozen=True)
+class ResultSummary:
+    result_id: str
+    status: str
+    created_at: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class RunHistoryItem:
+    query_run_id: str
+    status: str
+    created_at: str | None
+    execution_time_ms: int | None
+    result_id: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
 class HotdataClient:
     """Thin wrapper around the Hotdata Python SDK with query polling helpers."""
 
@@ -109,6 +132,39 @@ def query_runs(self) -> QueryRunsApi:
     def results(self) -> ResultsApi:
         return self._results_api()
 
+    def list_recent_results(
+        self,
+        *,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> list[ResultSummary]:
+        listing = self.results().list_results(limit=limit, offset=offset)
+        return [
+            ResultSummary(
+                result_id=r.id,
+                status=r.status,
+                created_at=r.created_at,
+            )
+            for r in listing.results
+        ]
+
+    def list_run_history(
+        self,
+        *,
+        limit: int = 20,
+    ) -> list[RunHistoryItem]:
+        listing = self.query_runs().list_query_runs(limit=limit)
+        return [
+            RunHistoryItem(
+                query_run_id=r.id,
+                status=r.status,
+                created_at=r.created_at,
+                execution_time_ms=r.execution_time_ms,
+                result_id=r.result_id,
+            )
+            for r in listing.query_runs
+        ]
+
     def iter_tables(
         self,
         *,

hotdata_runtime/result.py

@@ -20,6 +20,25 @@ class QueryResult:
     warning: str | None = None
     error_message: str | None = None
 
+    def to_records(
+        self,
+        *,
+        max_rows: int | None = None,
+    ) -> list[dict[str, Any]]:
+        rows = self.rows if max_rows is None else self.rows[:max_rows]
+        return [dict(zip(self.columns, row)) for row in rows]
+
+    def metadata_dict(self) -> dict[str, Any]:
+        return {
+            "row_count": self.row_count,
+            "column_count": len(self.columns),
+            "result_id": self.result_id,
+            "query_run_id": self.query_run_id,
+            "execution_time_ms": self.execution_time_ms,
+            "warning": self.warning,
+            "error_message": self.error_message,
+        }
+
     def to_pandas(self):  # type: ignore[no-untyped-def]
         import pandas as pd
 

tests/test_client.py

@@ -184,3 +184,48 @@ def information_schema(self, **kwargs):
     id_map.assert_not_called()
     assert cols == [col]
     assert fake_api.kwargs["connection_id"] == "conn_explicit"
+
+
+def test_list_recent_results_returns_normalized_summaries():
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    listing = SimpleNamespace(
+        results=[
+            SimpleNamespace(id="res_1", status="ready", created_at="2026-01-01T00:00:00Z"),
+            SimpleNamespace(id="res_2", status="failed", created_at=None),
+        ]
+    )
+
+    class FakeResultsApi:
+        def list_results(self, *, limit: int, offset: int):
+            return listing
+
+    with patch.object(client, "results", return_value=FakeResultsApi()):
+        out = client.list_recent_results(limit=10, offset=2)
+    assert [r.result_id for r in out] == ["res_1", "res_2"]
+    assert out[0].status == "ready"
+    assert out[0].to_dict()["created_at"] == "2026-01-01T00:00:00Z"
+
+
+def test_list_run_history_returns_normalized_items():
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    listing = SimpleNamespace(
+        query_runs=[
+            SimpleNamespace(
+                id="run_1",
+                status="succeeded",
+                created_at="2026-01-01T00:00:00Z",
+                execution_time_ms=7,
+                result_id="res_1",
+            ),
+        ]
+    )
+
+    class FakeRunsApi:
+        def list_query_runs(self, *, limit: int):
+            return listing
+
+    with patch.object(client, "query_runs", return_value=FakeRunsApi()):
+        out = client.list_run_history(limit=5)
+    assert [r.query_run_id for r in out] == ["run_1"]
+    assert out[0].execution_time_ms == 7
+    assert out[0].to_dict()["result_id"] == "res_1"

tests/test_contract.py

@@ -23,6 +23,8 @@ def test_public_exports_contract():
         "normalize_host",
         "pick_workspace",
         "resolve_workspace_selection",
+        "ResultSummary",
+        "RunHistoryItem",
         "WorkspaceSelection",
     ]
 

tests/test_result.py

@@ -0,0 +1,37 @@
+from hotdata_runtime.result import QueryResult
+
+
+def _result() -> QueryResult:
+    return QueryResult(
+        columns=["a", "b"],
+        rows=[[1, "x"], [2, "y"]],
+        row_count=2,
+        result_id="res_1",
+        query_run_id="run_1",
+        execution_time_ms=12,
+        warning="warn",
+        error_message=None,
+    )
+
+
+def test_to_records_returns_row_dicts():
+    records = _result().to_records()
+    assert records == [{"a": 1, "b": "x"}, {"a": 2, "b": "y"}]
+
+
+def test_to_records_honors_max_rows():
+    records = _result().to_records(max_rows=1)
+    assert records == [{"a": 1, "b": "x"}]
+
+
+def test_metadata_dict_contains_normalized_fields():
+    meta = _result().metadata_dict()
+    assert meta == {
+        "row_count": 2,
+        "column_count": 2,
+        "result_id": "res_1",
+        "query_run_id": "run_1",
+        "execution_time_ms": 12,
+        "warning": "warn",
+        "error_message": None,
+    }