docs(wire): clarify protocol-ambiguous fields and pin header reserved

- ISSUE-62: add regression test pinning Header.reserved/extra to 0 on
  encode. Upstream C (message.h) names this field ``extra`` and reserves
  it for future protocol extensions — if upstream ever repurposes it
  (e.g. compression flags), this test fails and forces a conscious
  update rather than silent mis-decode.
- ISSUE-64: OpenRequest.flags and OpenRequest.vfs are ignored by the
  upstream dqlite server (gateway.c/handle_open never reads them).
  Document that they exist for protocol compatibility only — users
  should keep the defaults.
- ISSUE-68: document the ValueType.UNIXTIME asymmetry explicitly.
  Upstream C server emits UNIXTIME from query.c for DATETIME columns,
  upstream C client (tuple.c) rejects UNIXTIME with DQLITE_PARSE, and
  our Python decoder accepts it — strictly more permissive than the C
  client. Mock servers must not send UNIXTIME to real C clients.
- ISSUE-69: document the ``tail_offset``-drives-schema derivation on
  StmtResponse. ``tail_offset=None`` → schema=0 (V0 body);
  ``tail_offset`` set to any int → schema=1 (V1 body). Mock-server
  authors must match to the request schema byte.

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

Author: antoineleclair

src/dqlitewire/constants.py

@@ -72,9 +72,16 @@ class ValueType(IntEnum):
     BLOB = 4
     NULL = 5
     # 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.
+    # Server-to-client ONLY: the upstream C server emits UNIXTIME from
+    # ``query.c`` for DATETIME columns, but the upstream C tuple_decoder
+    # (``tuple.c``) has no inbound case for DQLITE_UNIXTIME and rejects
+    # it with DQLITE_PARSE. This Python decoder is strictly more
+    # permissive than the C client — it accepts UNIXTIME on incoming row
+    # values and returns int64 seconds-since-epoch. Mock servers built
+    # on this encoder must NOT send UNIXTIME to real C clients.
+    # ``encode_params_tuple`` additionally enforces that this tag never
+    # appears on outgoing parameters (the server's parameter parser
+    # rejects it too).
     UNIXTIME = 9
     ISO8601 = 10  # ISO8601 string (maps to TEXT)
     BOOLEAN = 11  # Boolean (maps to INTEGER)

src/dqlitewire/messages/requests.py

@@ -108,6 +108,12 @@ class OpenRequest(Message):
     """Open a database.
 
     Body: text name, uint64 flags, text vfs
+
+    Note: the upstream dqlite server (``gateway.c``/``handle_open``)
+    currently IGNORES both ``flags`` and ``vfs`` fields. They are encoded
+    on the wire for protocol compatibility but have no server-side effect.
+    Keep the defaults (flags=0, vfs="") unless you're intentionally
+    exercising a future server version or building a mock server.
     """
 
     MSG_TYPE: ClassVar[int] = RequestType.OPEN

src/dqlitewire/messages/responses.py

@@ -153,6 +153,13 @@ class StmtResponse(Message):
     V0 body: uint32 db_id, uint32 stmt_id, uint64 num_params
     V1 body: uint32 db_id, uint32 stmt_id, uint64 num_params, uint64 tail_offset
 
+    Schema selection: ``_get_schema()`` derives the header schema byte from
+    ``tail_offset``. ``tail_offset=None`` (default) → schema=0 (V0 body);
+    ``tail_offset`` set to any int (including ``0``) → schema=1 (V1 body).
+    Mock-server authors must match this to the schema byte of the inbound
+    :class:`PrepareRequest`, since upstream dqlite servers dispatch on the
+    request's schema byte, not on any reply-side field.
+
     Note: V1 tail_offset is not present in the canonical Go client
     (go-dqlite). The Go EncodePrepare always uses schema=0 and DecodeStmt
     does not read tail_offset. This feature may be supported by the C

tests/test_messages_requests.py

@@ -28,6 +28,29 @@
 )
 
 
+class TestHeaderReservedField:
+    """Pin the header's reserved/extra uint16 to zero (ISSUE-62).
+
+    Upstream C (``message.h``) names this field ``extra`` and reserves it
+    for future protocol extensions. All current upstream servers send 0.
+    If upstream ever repurposes the field (compression flag, extended
+    schema, etc.), this test fails — forcing a conscious decision rather
+    than silent mis-decode.
+    """
+
+    def test_encoded_reserved_is_zero(self) -> None:
+        cases = [LeaderRequest(), HeartbeatRequest(timestamp=0), OpenRequest(name="db")]
+        for msg in cases:
+            encoded = msg.encode()
+            header = Header.decode(encoded[:HEADER_SIZE])
+            assert header.reserved == 0, f"{type(msg).__name__} emitted non-zero reserved"
+
+    def test_decoded_reserved_is_zero_after_encode_decode(self) -> None:
+        msg = LeaderRequest()
+        header = Header.decode(msg.encode()[:HEADER_SIZE])
+        assert header.reserved == 0
+
+
 class TestLeaderRequest:
     def test_encode_has_body(self) -> None:
         """LeaderRequest body must contain a reserved uint64 per Go spec."""