feat!: remove session/sandbox support (#57)

HotdataClient no longer accepts session_id=, the session_id property is gone,
default_session_id() and the HOTDATA_SANDBOX read are removed, the workspace
helpers lose their session_id parameter, and health output no longer emits a
sandbox line.

The server stopped enforcing session scoping some time ago, so the value
already reached nothing. What makes removal necessary rather than tidy is that
the SDK is dropping the SessionId security scheme: against that release
Configuration(session_id=...) raises TypeError instead of setting a header, and
this package passed it unconditionally -- so every HotdataClient(...) would
fail at construction. Measured against hotdata built from sdk-python@main, this
suite goes to 97 failed / 28 passed before this change.

The dependency is capped at hotdata<0.9, so nothing is broken today. This is
what lets the cap be raised later without a second breaking release.

TESTS ASSERT THE WIRE, NOT THE SIGNATURE. The first version of these tests was
close to worthless, and a sabotage audit proved it: reviving the whole feature
from the ENVIRONMENT -- read HOTDATA_SANDBOX, pass it to Configuration, restore
the property and the health line -- left the suite fully green. A signature
check cannot see that, because no signature changes.

So the assertions are on Configuration.api_keys, which is where the generated
client records the schemes it will attach, and HOTDATA_SANDBOX is set
deliberately in each test so an environment-sourced revival has something to
find. Three sabotages that previously passed now fail:

  revive from the environment          0 -> 4 failures
  session_id back as a 3rd positional  0 -> 1 failure
  leave from_env's body stale          0 -> 1 failure

Specific repairs to the earlier tests:

  * the `sandbox` assertion was dead -- it built a client with no session, so on
    an honest revert the `if client.session_id:` guard was false and nothing was
    emitted. It now sets the env var, which is the only way the assertion is
    reachable.
  * pytest.raises(TypeError) had no match=, so it passed for any unrecognised
    keyword. It was a typo detector.
  * from_env's body had no coverage at all -- the module-level test patches the
    classmethod out -- while this change rewrote two of its lines. It now
    asserts pick_workspace is called with exactly two positional arguments.
  * list_workspaces builds its own Configuration, a second place the header can
    return, and the pre-auth one. Covered separately.

Also drops "session" from the package description, which ships to PyPI.

125 -> 130 passed. ruff and mypy counts unchanged from main (2 and 158, both
pre-existing; CI runs pytest only).

Review follow-ups: assert on the resulting Configuration rather than the kwargs
it was handed, because Configuration(api_keys={"SessionId": ...}) is a
documented escape hatch that re-attaches the header with no session_id keyword
at all -- a kwargs-only check waved it through. Sabotaged that exact vector: 3
tests now fail on it. Also switched to the public client.api.configuration
accessor instead of reaching into _config.

Author: anoop-narang

CHANGELOG.md

@@ -16,6 +16,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   in this package, in versions already published. Raise the cap deliberately
   after running the suite against the new minor.
 
+### Removed
+
+- **Breaking:** session/sandbox support is gone. `HotdataClient` no longer accepts
+  `session_id=`, `HotdataClient.session_id` is removed, `default_session_id()` and
+  the `HOTDATA_SANDBOX` read are gone, and `list_workspaces()`,
+  `resolve_workspace_selection()` and `pick_workspace()` lose their `session_id`
+  parameter — note that loss is **positional**, so a three-argument call raises an
+  arity `TypeError` rather than an unexpected-keyword one.
+  `workspace_health_lines()` no longer emits a `sandbox` line.
+
+  **Why now.** The server stopped enforcing session scoping some time ago, so the
+  value already reached nothing. What makes removal urgent rather than tidy is
+  that the SDK is dropping the `SessionId` security scheme: against that release
+  `Configuration(session_id=...)` raises `TypeError` instead of setting a header,
+  and this package passed it unconditionally — so every `HotdataClient(...)`
+  would fail at construction. This package still pins `hotdata<0.9`, so nothing
+  is broken today; the change is what lets the cap be raised later without a
+  second breaking release.
+
+  **Migrating.** Drop `session_id=` from `HotdataClient(...)`, stop reading
+  `client.session_id`, stop setting `HOTDATA_SANDBOX`, and pass two arguments to
+  the workspace helpers. Adapters that re-export session context in their own
+  signatures — a `session_id=` parameter, a `session_id` metadata key — need to
+  remove it from theirs too, which makes their own release breaking in turn.
+
 
 ## [0.10.0] - 2026-08-07
 

CONTRACT.md

@@ -21,7 +21,6 @@ The supported import surface is:
 - `workspace_health_lines`
 - `default_api_key`
 - `default_host`
-- `default_session_id`
 - `explicit_workspace_id`
 - `list_workspaces`
 - `normalize_host`
@@ -43,7 +42,7 @@ Adapters should import from `hotdata_framework` and treat this surface as the st
 
 ### `HotdataClient`
 
-- Represents runtime context: API key, host, workspace, optional session.
+- Represents runtime context: API key, host, workspace.
 - `from_env()` resolves runtime context from env vars and selected workspace.
 - `execute_sql(sql)` returns `QueryResult` or raises `RuntimeError`/`TimeoutError`.
 - `get_result(result_id)` returns a ready `QueryResult` and waits for readiness when needed.
@@ -79,7 +78,6 @@ Adapters should import from `hotdata_framework` and treat this surface as the st
 
 - `default_api_key()` reads `HOTDATA_API_KEY`.
 - `default_host()` reads `HOTDATA_API_URL` (default: `https://api.hotdata.dev`) and normalizes it.
-- `default_session_id()` reads `HOTDATA_SANDBOX`.
 - `explicit_workspace_id()` reads `HOTDATA_WORKSPACE` (workspace public id).
 - `pick_workspace()` prefers explicit env workspace, then active workspace, then first workspace.
 - `resolve_workspace_selection()` is the canonical workspace selection algorithm. It returns `WorkspaceSelection` with selected workspace id, selection source, and discovered workspaces when auto-selected.

README.md

@@ -2,15 +2,14 @@
 
 **A Python framework for building Hotdata integrations.**
 
-Shared runtime primitives for Hotdata integrations: workspace/session semantics, execution context, query state, run history, and replayable result handles. Framework packages (Marimo, Jupyter, Streamlit, LangGraph) depend on this package.
+Shared runtime primitives for Hotdata integrations: workspace semantics, execution context, query state, run history, and replayable result handles. Framework packages (Marimo, Jupyter, Streamlit, LangGraph) depend on this package.
 
 Runtime boundary and guarantees are defined in `CONTRACT.md`.
 
 ## Features
 
-- **Environment-driven client setup** — create clients from `HOTDATA_API_KEY`, optional `HOTDATA_API_URL`, `HOTDATA_WORKSPACE`, and `HOTDATA_SANDBOX`.
+- **Environment-driven client setup** — create clients from `HOTDATA_API_KEY`, optional `HOTDATA_API_URL`, and `HOTDATA_WORKSPACE`.
 - **Workspace resolution** — choose an explicit workspace from env, otherwise discover workspaces and select the active workspace or first available workspace.
-- **Sandbox/session propagation** — pass sandbox session context through the SDK via `X-Session-Id`.
 - **HTTP resilience** — configure SDK retries for transient connection failures and retry SQL execution on stale pooled sockets.
 - **SQL execution helper** — run SQL through `POST /v1/query`, poll async query runs when needed, and return a `QueryResult`.
 - **Result utilities** — convert query results to records, pandas DataFrames, or metadata dictionaries for adapter display layers.

hotdata_framework/__init__.py

@@ -20,7 +20,6 @@
     WorkspaceSelection,
     default_api_key,
     default_host,
-    default_session_id,
     explicit_workspace_id,
     list_workspaces,
     normalize_host,
@@ -61,7 +60,6 @@
     "classify_sdk_error",
     "default_api_key",
     "default_host",
-    "default_session_id",
     "explicit_workspace_id",
     "from_env",
     "is_parquet_path",

hotdata_framework/client.py

@@ -49,7 +49,6 @@
 from hotdata_framework.env import (
     default_api_key,
     default_host,
-    default_session_id,
     normalize_host,
     pick_workspace,
 )
@@ -150,18 +149,15 @@ def __init__(
         workspace_id: str,
         *,
         host: str | None = None,
-        session_id: str | None = None,
         request_timeout: float | tuple[float, float] | None = None,
     ) -> None:
         self._host = normalize_host(host) if host else default_host()
         self._api_key = api_key
         self._workspace_id = workspace_id
-        self._session_id = session_id
         self._config = Configuration(
             host=self._host,
             api_key=api_key,
             workspace_id=workspace_id,
-            session_id=session_id,
             retries=default_http_retries(),
         )
         self._api = ApiClient(self._config)
@@ -174,9 +170,8 @@ def from_env(cls) -> HotdataClient:
         if not api_key:
             raise RuntimeError("HOTDATA_API_KEY must be set.")
         host = default_host()
-        session = default_session_id()
-        workspace_id = pick_workspace(api_key, host, session)
-        return cls(api_key, workspace_id, host=host, session_id=session)
+        workspace_id = pick_workspace(api_key, host)
+        return cls(api_key, workspace_id, host=host)
 
     @property
     def workspace_id(self) -> str:
@@ -186,10 +181,6 @@ def workspace_id(self) -> str:
     def host(self) -> str:
         return self._host
 
-    @property
-    def session_id(self) -> str | None:
-        return self._session_id
-
     @property
     def api(self) -> ApiClient:
         return self._api

hotdata_framework/env.py

@@ -31,16 +31,11 @@ def default_host() -> str:
     return normalize_host(raw)
 
 
-def default_session_id() -> str | None:
-    return os.environ.get("HOTDATA_SANDBOX")
-
-
-def list_workspaces(api_key: str, host: str, session_id: str | None):
+def list_workspaces(api_key: str, host: str):
     cfg = Configuration(
         host=host,
         api_key=api_key,
         workspace_id=None,
-        session_id=session_id,
     )
     with ApiClient(cfg) as api:
         listing = WorkspacesApi(api).list_workspaces()
@@ -54,17 +49,15 @@ class WorkspaceSelection:
     workspaces: list
 
 
-def resolve_workspace_selection(
-    api_key: str, host: str, session_id: str | None
-) -> WorkspaceSelection:
+def resolve_workspace_selection(api_key: str, host: str) -> WorkspaceSelection:
     explicit = explicit_workspace_id()
     if explicit:
         return WorkspaceSelection(
             workspace_id=explicit,
             source="explicit_env",
             workspaces=[],
         )
-    workspaces = list_workspaces(api_key, host, session_id)
+    workspaces = list_workspaces(api_key, host)
     if not workspaces:
         raise RuntimeError("No Hotdata workspaces found for this API key.")
     active = [w for w in workspaces if w.active]
@@ -76,6 +69,6 @@ def resolve_workspace_selection(
     )
 
 
-def pick_workspace(api_key: str, host: str, session_id: str | None) -> str:
-    selection = resolve_workspace_selection(api_key, host, session_id)
+def pick_workspace(api_key: str, host: str) -> str:
+    selection = resolve_workspace_selection(api_key, host)
     return selection.workspace_id

hotdata_framework/health.py

@@ -18,8 +18,6 @@ def workspace_health_lines(client: HotdataClient) -> tuple[bool, list[str]]:
             f"**workspace** `{client.workspace_id}`",
             f"**connections** {n}",
         ]
-        if client.session_id:
-            lines.append(f"**sandbox** `{client.session_id}`")
         return True, lines
     except ApiException as e:
         return False, [e.reason or str(e)]

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "hotdata-framework"
 version = "0.10.0"
-description = "Python framework for building Hotdata integrations: workspace/session runtime, query execution, and managed databases"
+description = "Python framework for building Hotdata integrations: workspace runtime, query execution, and managed databases"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }

tests/test_client.py

@@ -4,6 +4,7 @@
 from unittest.mock import patch
 
 import pytest
+from hotdata import Configuration
 from hotdata.exceptions import ForbiddenException
 
 from hotdata_framework.client import HotdataClient
@@ -153,15 +154,15 @@ def test_normalize_host(raw: str, expected: str):
 
 def test_pick_workspace_prefers_env(monkeypatch: pytest.MonkeyPatch):
     monkeypatch.setenv("HOTDATA_WORKSPACE", "ws_explicit")
-    assert pick_workspace("k", "https://api.hotdata.dev", None) == "ws_explicit"
+    assert pick_workspace("k", "https://api.hotdata.dev") == "ws_explicit"
 
 
 def test_resolve_workspace_selection_prefers_env_without_listing(
     monkeypatch: pytest.MonkeyPatch,
 ):
     monkeypatch.setenv("HOTDATA_WORKSPACE", "ws_explicit")
     with patch("hotdata_framework.env.list_workspaces") as listing:
-        resolved = resolve_workspace_selection("k", "https://api.hotdata.dev", None)
+        resolved = resolve_workspace_selection("k", "https://api.hotdata.dev")
     listing.assert_not_called()
     assert resolved.workspace_id == "ws_explicit"
     assert resolved.source == "explicit_env"
@@ -180,7 +181,7 @@ def test_pick_workspace_chooses_first_active(monkeypatch: pytest.MonkeyPatch):
 
     with patch("hotdata_framework.env.WorkspacesApi") as Api:
         Api.return_value.list_workspaces.return_value = listing
-        assert pick_workspace("k", "https://api.hotdata.dev", None) == "ws_2"
+        assert pick_workspace("k", "https://api.hotdata.dev") == "ws_2"
 
 
 def test_pick_workspace_falls_back_to_first(monkeypatch: pytest.MonkeyPatch):
@@ -194,7 +195,7 @@ def test_pick_workspace_falls_back_to_first(monkeypatch: pytest.MonkeyPatch):
 
     with patch("hotdata_framework.env.WorkspacesApi") as Api:
         Api.return_value.list_workspaces.return_value = listing
-        assert pick_workspace("k", "https://api.hotdata.dev", None) == "ws_1"
+        assert pick_workspace("k", "https://api.hotdata.dev") == "ws_1"
 
 
 def test_resolve_workspace_selection_source_first(monkeypatch: pytest.MonkeyPatch):
@@ -206,7 +207,7 @@ def test_resolve_workspace_selection_source_first(monkeypatch: pytest.MonkeyPatc
     listing = SimpleNamespace(workspaces=items)
     with patch("hotdata_framework.env.WorkspacesApi") as Api:
         Api.return_value.list_workspaces.return_value = listing
-        resolved = resolve_workspace_selection("k", "https://api.hotdata.dev", None)
+        resolved = resolve_workspace_selection("k", "https://api.hotdata.dev")
     assert resolved.workspace_id == "ws_1"
     assert resolved.source == "first"
     assert resolved.workspaces == items
@@ -225,7 +226,7 @@ def test_resolve_workspace_selection_returns_workspaces_and_source(
 
     with patch("hotdata_framework.env.WorkspacesApi") as Api:
         Api.return_value.list_workspaces.return_value = listing
-        resolved = resolve_workspace_selection("k", "https://api.hotdata.dev", None)
+        resolved = resolve_workspace_selection("k", "https://api.hotdata.dev")
     assert resolved.workspace_id == "ws_2"
     assert resolved.source == "active"
     assert resolved.workspaces == items
@@ -447,3 +448,99 @@ def list_query_runs(self, *, limit: int):
     assert out[0].execution_time_ms == 7
     assert out[0].to_dict()["result_id"] == "res_1"
     assert fake_runs.kwargs == {"limit": 5}
+
+
+# ---------------------------------------------------------------------------
+# Session removal — asserted at the wire, not at the signature
+#
+# A signature-shaped check ("does __init__ accept session_id?") is satisfied by
+# any unrecognised keyword and says nothing about what goes on the request. The
+# feature was proven revivable from the ENVIRONMENT with the whole suite green:
+# read HOTDATA_SANDBOX, pass it to Configuration, and the X-Session-Id header is
+# back on every call with no signature change to notice. So these assert on
+# `Configuration.api_keys`, which is where the generated client actually decides
+# to send the header, and they set HOTDATA_SANDBOX so an environment-sourced
+# revival has something to find.
+
+
+def _sandbox_set(monkeypatch: pytest.MonkeyPatch) -> str:
+    value = "sb_should_reach_nothing"
+    monkeypatch.setenv("HOTDATA_SANDBOX", value)
+    return value
+
+
+def test_client_registers_no_session_header(monkeypatch: pytest.MonkeyPatch):
+    """The removal's observable contract: no X-Session-Id on anything this client
+    sends. `api_keys` is the SDK's own record of which security schemes it will
+    attach, so an empty SessionId slot is the header being absent."""
+    _sandbox_set(monkeypatch)
+    client = HotdataClient("k", "ws", host="https://api.hotdata.dev")
+    assert "SessionId" not in client.api.configuration.api_keys
+    assert client.api.configuration.api_keys == {"WorkspaceId": "ws"}
+
+
+def test_client_rejects_session_id_by_name(monkeypatch: pytest.MonkeyPatch):
+    """`match=` matters: without it the assertion passes for ANY unknown keyword,
+    making it a typo detector rather than a statement about `session_id`."""
+    _sandbox_set(monkeypatch)
+    with pytest.raises(TypeError, match="session_id"):
+        HotdataClient("k", "ws", host="https://api.hotdata.dev", session_id="sb_x")
+    # The property is gone too — the CHANGELOG says so, and an adapter reading it
+    # should get AttributeError rather than a stale value.
+    assert not hasattr(HotdataClient("k", "ws", host="https://api.hotdata.dev"), "session_id")
+
+
+def test_workspace_listing_registers_no_session_header(monkeypatch: pytest.MonkeyPatch):
+    """`list_workspaces` builds its OWN Configuration, so it is a second place the
+    header can come back — and it is the pre-auth call, made before any workspace
+    is known."""
+    _clear_workspace_env(monkeypatch)
+    _sandbox_set(monkeypatch)
+    seen: list[Configuration] = []
+
+    def spy(*args: object, **kwargs: object) -> Configuration:
+        # Assert on the CONFIG, not on the kwargs. `session_id=` is only one way
+        # back: `Configuration(api_keys={"SessionId": ...})` is a documented
+        # escape hatch that re-attaches the header with no such keyword, and a
+        # kwargs-only check waves it through.
+        cfg = Configuration(*args, **kwargs)
+        seen.append(cfg)
+        return cfg
+
+    listing = SimpleNamespace(workspaces=[SimpleNamespace(public_id="ws_1", active=True)])
+    with patch("hotdata_framework.env.Configuration", spy), patch(
+        "hotdata_framework.env.WorkspacesApi"
+    ) as Api:
+        Api.return_value.list_workspaces.return_value = listing
+        assert pick_workspace("k", "https://api.hotdata.dev") == "ws_1"
+    assert seen, "list_workspaces built no Configuration — the spy never fired"
+    for cfg in seen:
+        assert "SessionId" not in cfg.api_keys
+
+
+def test_from_env_builds_a_client_without_a_session(monkeypatch: pytest.MonkeyPatch):
+    """`from_env` is the entry point every adapter uses, and its body had no
+    coverage at all: the module-level `from_env` test patches this classmethod
+    out. Leaving a stale 3-argument `pick_workspace(...)` call here broke it
+    unconditionally while the suite stayed green."""
+    _clear_workspace_env(monkeypatch)
+    _sandbox_set(monkeypatch)
+    monkeypatch.setenv("HOTDATA_API_KEY", "k_env")
+    monkeypatch.setenv("HOTDATA_API_URL", "https://api.hotdata.dev")
+
+    with patch("hotdata_framework.client.pick_workspace") as picked:
+        picked.return_value = "ws_from_env"
+        client = HotdataClient.from_env()
+
+    # Two arguments, positionally — the signature this change trimmed.
+    assert picked.call_args.args == ("k_env", "https://api.hotdata.dev")
+    assert picked.call_args.kwargs == {}
+    assert client.workspace_id == "ws_from_env"
+    assert client.host == "https://api.hotdata.dev"
+    assert "SessionId" not in client.api.configuration.api_keys
+
+
+def test_from_env_requires_an_api_key(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("HOTDATA_API_KEY", raising=False)
+    with pytest.raises(RuntimeError, match="HOTDATA_API_KEY"):
+        HotdataClient.from_env()

tests/test_contract.py

@@ -28,7 +28,6 @@ def test_public_exports_contract():
         "classify_sdk_error",
         "default_api_key",
         "default_host",
-        "default_session_id",
         "explicit_workspace_id",
         "from_env",
         "is_parquet_path",