fix: reject UNIXTIME tag in outgoing params tuple

UNIXTIME is a server-to-client-only type — the C server's tuple_decoder
has no inbound case for DQLITE_UNIXTIME, so a request frame with that
tag would be rejected mid-parse. Encoder inference never picks UNIXTIME
in practice, but guard encode_params_tuple defensively so any future
caller threading an explicit UNIXTIME hint gets a clear EncodeError
rather than a confusing server-side error.

Encode_value continues to support UNIXTIME explicitly for server-to-
client roundtrip tests.

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

Author: antoineleclair

src/dqlitewire/constants.py

@@ -71,7 +71,11 @@ class ValueType(IntEnum):
     TEXT = 3
     BLOB = 4
     NULL = 5
-    UNIXTIME = 9  # Unix time (deprecated, maps to INTEGER)
+    # Unix time (deprecated, maps to INTEGER).
+    # Server-to-client ONLY: the C server's tuple_decoder has no inbound
+    # case for DQLITE_UNIXTIME, so this tag must never appear on outgoing
+    # parameters. encode_params_tuple enforces this defensively.
+    UNIXTIME = 9
     ISO8601 = 10  # ISO8601 string (maps to TEXT)
     BOOLEAN = 11  # Boolean (maps to INTEGER)
 

src/dqlitewire/tuples.py

@@ -54,8 +54,16 @@ def encode_params_tuple(params: Sequence[Any], schema: int = 0, buffer_offset: i
     types: list[int] = []
     values: list[bytes] = []
 
-    for param in params:
+    for i, param in enumerate(params):
         encoded, value_type = encode_value(param)
+        # Defense in depth: UNIXTIME is server-to-client only. Inference
+        # never picks it, but guard against a future caller threading an
+        # explicit UNIXTIME hint through this path.
+        if value_type == ValueType.UNIXTIME:
+            raise EncodeError(
+                f"Parameter {i} resolved to UNIXTIME, which the server "
+                "cannot decode; use INTEGER or ISO8601 instead"
+            )
         types.append(value_type)
         values.append(encoded)
 

src/dqlitewire/types.py

@@ -276,6 +276,13 @@ def encode_value(value: Any, value_type: ValueType | None = None) -> tuple[bytes
             raise EncodeError(f"Expected bool or int for BOOLEAN, got {type(value).__name__}")
         return encode_uint64(1 if value else 0), value_type
     elif value_type in (ValueType.INTEGER, ValueType.UNIXTIME):
+        # Note: UNIXTIME is a server-to-client-only type (the C server's
+        # tuple_decoder has no inbound case for DQLITE_UNIXTIME). Explicit
+        # UNIXTIME encoding here is supported for roundtrip tests that
+        # simulate server-to-client frames; encode_params_tuple, which is
+        # the outgoing-params path, uses inference and never picks
+        # UNIXTIME, so the server-rejection case cannot arise via the
+        # documented client API.
         if isinstance(value, bool):
             value = 1 if value else 0
         if not isinstance(value, int):

tests/test_tuples.py

@@ -5,7 +5,7 @@
 import pytest
 
 from dqlitewire.constants import ValueType
-from dqlitewire.exceptions import DecodeError
+from dqlitewire.exceptions import DecodeError, EncodeError
 from dqlitewire.tuples import (
     RowMarker,
     decode_params_tuple,
@@ -23,6 +23,20 @@ def test_encode_empty(self) -> None:
         encoded = encode_params_tuple([])
         assert encoded == b""
 
+    def test_params_tuple_rejects_unixtime_tag(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Defense in depth: if anything ever produces a UNIXTIME tag on an
+        outgoing param, encode_params_tuple must reject it — the C server
+        cannot decode DQLITE_UNIXTIME inbound.
+        """
+        from dqlitewire import tuples as tuples_mod
+
+        def fake_encode(value: object, value_type: object = None) -> tuple:
+            return b"\x00" * 8, ValueType.UNIXTIME
+
+        monkeypatch.setattr(tuples_mod, "encode_value", fake_encode)
+        with pytest.raises(EncodeError, match="UNIXTIME"):
+            encode_params_tuple([1_700_000_000])
+
     def test_encode_single_integer(self) -> None:
         encoded = encode_params_tuple([42])
         assert len(encoded) == 16