feat: wrap wire EncodeError as client-level DataError

Out-of-range ints, unsupported types, and other wire-layer parameter
encoding failures surfaced as dqlitewire.exceptions.EncodeError —
leaking wire-library implementation detail across the abstraction
boundary. Application code catching DqliteError to log/alert missed
them entirely.

Introduce DataError in dqliteclient.exceptions and wrap EncodeError at
_run_protocol's entry. Connection stays usable (nothing was sent on
the wire).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: antoineleclair

src/dqliteclient/__init__.py

@@ -10,6 +10,7 @@
 from dqliteclient.connection import DqliteConnection
 from dqliteclient.exceptions import (
     ClusterError,
+    DataError,
     DqliteConnectionError,
     DqliteError,
     InterfaceError,
@@ -34,6 +35,7 @@
     "ProtocolError",
     "ClusterError",
     "OperationalError",
+    "DataError",
 ]
 
 __version__ = "0.1.0"

src/dqliteclient/connection.py

@@ -7,12 +7,14 @@
 from typing import Any
 
 from dqliteclient.exceptions import (
+    DataError,
     DqliteConnectionError,
     InterfaceError,
     OperationalError,
     ProtocolError,
 )
 from dqliteclient.protocol import DqliteProtocol
+from dqlitewire.exceptions import EncodeError as _WireEncodeError
 
 # dqlite error codes that indicate a leader change (SQLite extended error codes)
 # SQLITE_IOERR_NOT_LEADER = SQLITE_IOERR | (40 << 8) = 10250
@@ -259,6 +261,11 @@ async def _run_protocol[T](self, fn: Callable[[DqliteProtocol, int], Awaitable[T
         self._in_use = True
         try:
             return await fn(protocol, db_id)
+        except _WireEncodeError as e:
+            # Client-side parameter-encoding error. The wire bytes were
+            # never written, so the connection is still usable — convert
+            # into the client-level DataError and let it propagate.
+            raise DataError(str(e)) from e
         except (DqliteConnectionError, ProtocolError) as e:
             self._invalidate(e)
             raise

src/dqliteclient/exceptions.py

@@ -21,6 +21,15 @@ class ClusterError(DqliteError):
     """Cluster-related error (leader not found, etc)."""
 
 
+class DataError(DqliteError):
+    """Client-side parameter-encoding error.
+
+    Raised when a parameter value cannot be serialized onto the wire —
+    e.g. an int outside ``[-2^63, 2^63)``, an embedded null byte in a
+    TEXT string, or an unsupported Python type.
+    """
+
+
 class OperationalError(DqliteError):
     """Database operation error."""
 

tests/test_connection.py

@@ -850,6 +850,18 @@ async def test_string_params_rejected_with_clear_error(self, connected_connectio
         with pytest.raises(TypeError, match="list or tuple"):
             await conn.execute("SELECT ?", "alice")  # type: ignore[arg-type]
 
+    async def test_int64_overflow_raises_dataerror(self, connected_connection) -> None:
+        """Out-of-range int (|v| >= 2^63) must surface as DataError, not the
+        internal wire-package EncodeError. The connection must remain alive.
+        """
+        from dqliteclient.exceptions import DataError
+
+        conn, _, _ = connected_connection
+        huge = 2**70
+        with pytest.raises(DataError):
+            await conn.execute("INSERT INTO t VALUES (?)", [huge])
+        assert conn.is_connected
+
     async def test_cross_event_loop_raises_interface_error(self) -> None:
         """Using a connection from a different event loop must raise InterfaceError."""
         import asyncio