fix(managed): raise on a query reply shape this client cannot read

The last route by which "I do not know" could read as "no rows". If an
SDK release adds a third reply model for the query endpoint, neither
`isinstance` branch matches, `_query_database_scoped` returns `None`,
`fetch_table` returns `None`, and `fetch_table_rows` turns that into `[]`
-- the same answer it gives for a table that is not synced. A merge or
append load would then write only its new batch over rows it believed
were absent.

Same collapse the previous commit closed for a succeeded run that saved
nothing, by the other path into it. `HotdataClient` already raised here,
so this also settles a disagreement between the two clients.

A `None` from `fetch_table` now carries exactly one meaning: the table is
not synced.

Author: anoop-narang

CHANGELOG.md

@@ -31,9 +31,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   table. `fetch_table` answered `None` for it, which `fetch_table_rows` turns
   into `[]`, the same answer both give for a table that is not synced. A
   read-modify-write load would have read no existing rows and written only its
-  new batch, dropping every row already there. Arrow stays the only path the
-  data travels, so column types come from the server's schema rather than being
-  inferred from JSON.
+  new batch, dropping every row already there. A reply shape this client does not
+  recognise raises for the same reason, as `HotdataClient` already did — so a
+  `None` from `fetch_table` now means one thing only: the table is not synced.
+  Arrow stays the only path the data travels, so column types come from the
+  server's schema rather than being inferred from JSON.
 
   Costs one extra round trip on a query that would have answered synchronously,
   in exchange for not transferring the result twice.

hotdata_framework/managed_client.py

@@ -162,7 +162,13 @@ def _query_database_scoped(self, sql: str, *, database_id: str) -> str | None:
         # in the background, so it is not the finish line either.
         if isinstance(raw, (QueryResponse, AsyncQueryResponse)):
             return self._await_query_run(raw.query_run_id, database_id=database_id)
-        return None
+        # Returning nothing here would read as an empty table: `fetch_table`
+        # answers `None`, `fetch_table_rows` turns that into `[]`, and a
+        # read-modify-write load would write only its new batch over rows it
+        # believed were not there. A reply shape this client does not know is a
+        # reason to stop, not to report emptiness. `HotdataClient` raises on the
+        # same condition.
+        raise RuntimeError(f"Unexpected query response type: {type(raw)!r}")
 
     def _await_query_run(self, query_run_id: str, *, database_id: str) -> str | None:
         """Wait for a query run to finish; return the result id it produced.

tests/test_managed_client.py

@@ -926,3 +926,44 @@ def test_query_run_model_carries_every_field_this_client_reads() -> None:
     """
     for field in ("status", "result_id", "error_message", "warning_message"):
         assert field in QueryRunInfo.model_fields, field
+
+
+def test_an_unknown_query_reply_shape_raises_rather_than_reading_empty(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The last route by which "I do not know" could have read as "no rows".
+
+    If an SDK release adds a third reply model for the query endpoint, neither
+    `isinstance` branch matches. Falling through to `None` would surface as an
+    empty table -- and `fetch_table_rows` maps `None` to `[]`, the same answer it
+    gives for a table that is not synced -- so a merge or append load would drop
+    every row already there. `HotdataClient` raises on this condition; now both
+    do.
+
+    After this, a `None` from `fetch_table` means one thing only: the table is
+    not synced.
+    """
+
+    class FakeQueryApi:
+        def __init__(self, api: object) -> None:
+            pass
+
+        def query(self, request: object, *, x_database_id: str) -> Any:
+            # A shape from neither branch -- a future reply model, as far as
+            # this client is concerned.
+            return SimpleNamespace(something_new="?")
+
+    monkeypatch.setattr(mc, "QueryApi", FakeQueryApi)
+    monkeypatch.setattr(mc.time, "sleep", lambda _seconds: None)
+
+    client = mc.ManagedDatabaseClient(
+        api_key="k",
+        workspace_id="w",
+        api_base_url="https://example.test",
+        max_retries=1,
+        retry_backoff_seconds=0.0,
+    )
+    client._runtime = _fake_runtime()
+
+    with pytest.raises(HotdataTerminalError, match="Unexpected query response type"):
+        client.fetch_table_rows(database="mydb", schema="public", table="orders")