Add golden-byte tests to verify wire encoding against protocol spec

Hand-constructed byte sequences for key message types verify that the
Python encoder/decoder matches the dqlite wire protocol specification.
These catch symmetric bugs that round-trip tests cannot detect (wrong
nibble order, padding miscalculation, etc.).

Covers: LeaderRequest, ClientRequest, OpenRequest, FinalizeRequest,
ExecRequest with params tuple, FailureResponse, ResultResponse,
RowsResponse with nibble packing (including BOOLEAN=11 which uses
all 4 bits), handshake, text/blob encoding edge cases.

Fixes #018

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

Author: antoineleclair

tests/test_golden_bytes.py

@@ -0,0 +1,315 @@
+"""Golden-byte tests: verify wire encoding matches the dqlite protocol spec.
+
+Each test contains a hand-constructed byte sequence built from the protocol
+rules (header format, little-endian integers, null-terminated padded text,
+nibble-packed row headers, etc.). These are NOT generated by encoding with
+Python and copying the output — they are independently derived from the spec
+at https://canonical.com/dqlite/docs/reference/wire-protocol and the Go/C
+reference implementations.
+
+This catches symmetric bugs where both encoder and decoder share the same
+mistake (e.g. wrong nibble order, wrong padding base).
+"""
+
+import struct
+
+from dqlitewire.codec import decode_message, encode_message
+from dqlitewire.constants import ValueType
+from dqlitewire.messages import (
+    ClientRequest,
+    ExecRequest,
+    FailureResponse,
+    FinalizeRequest,
+    LeaderRequest,
+    OpenRequest,
+    ResultResponse,
+    RowsResponse,
+)
+
+
+def _header(size_words: int, msg_type: int, schema: int = 0) -> bytes:
+    """Build an 8-byte message header from spec fields."""
+    return struct.pack("<IBBH", size_words, msg_type, schema, 0)
+
+
+def _u64(v: int) -> bytes:
+    """Little-endian uint64."""
+    return struct.pack("<Q", v)
+
+
+def _i64(v: int) -> bytes:
+    """Little-endian int64."""
+    return struct.pack("<q", v)
+
+
+def _u32(v: int) -> bytes:
+    """Little-endian uint32."""
+    return struct.pack("<I", v)
+
+
+def _text(s: str) -> bytes:
+    """Null-terminated UTF-8, padded to 8-byte boundary."""
+    raw = s.encode("utf-8") + b"\x00"
+    pad = (8 - len(raw) % 8) % 8
+    return raw + b"\x00" * pad
+
+
+class TestGoldenRequests:
+    """Verify request message encoding matches hand-built spec bytes."""
+
+    def test_leader_request(self) -> None:
+        """LeaderRequest: type=0, body=uint64(0)."""
+        expected = _header(1, 0) + _u64(0)
+        assert encode_message(LeaderRequest()) == expected
+
+        msg = decode_message(expected, is_request=True)
+        assert isinstance(msg, LeaderRequest)
+
+    def test_client_request(self) -> None:
+        """ClientRequest(client_id=42): type=1, body=uint64(42)."""
+        expected = _header(1, 1) + _u64(42)
+        assert encode_message(ClientRequest(client_id=42)) == expected
+
+        msg = decode_message(expected, is_request=True)
+        assert isinstance(msg, ClientRequest)
+        assert msg.client_id == 42
+
+    def test_open_request(self) -> None:
+        """OpenRequest(name="test.db", flags=0, vfs="unix"): type=3.
+
+        Body: text("test.db") + uint64(0) + text("unix")
+        text("test.db") = b"test.db\\0" = 8 bytes (exact word)
+        text("unix")    = b"unix\\0\\0\\0\\0" = 8 bytes (5+3 pad)
+        Total body = 8 + 8 + 8 = 24 bytes = 3 words
+        """
+        expected = _header(3, 3) + _text("test.db") + _u64(0) + _text("unix")
+        assert encode_message(OpenRequest(name="test.db", flags=0, vfs="unix")) == expected
+
+        msg = decode_message(expected, is_request=True)
+        assert isinstance(msg, OpenRequest)
+        assert msg.name == "test.db"
+        assert msg.vfs == "unix"
+
+    def test_finalize_request(self) -> None:
+        """FinalizeRequest(db_id=1, stmt_id=2): type=7.
+
+        Body: uint32(1) + uint32(2) = 8 bytes = 1 word
+        """
+        expected = _header(1, 7) + _u32(1) + _u32(2)
+        assert encode_message(FinalizeRequest(db_id=1, stmt_id=2)) == expected
+
+        msg = decode_message(expected, is_request=True)
+        assert isinstance(msg, FinalizeRequest)
+        assert msg.db_id == 1
+        assert msg.stmt_id == 2
+
+    def test_exec_request_with_params(self) -> None:
+        """ExecRequest(db_id=1, stmt_id=2, params=[42, "hello"]): type=5, schema=0.
+
+        Body layout:
+          uint32(1) + uint32(2)                    = 8 bytes (offset 0-7)
+          params tuple V0:
+            count=2, types=[INTEGER=1, TEXT=3]      → bytes [0x02, 0x01, 0x03]
+            buffer_offset=8, absolute=8+3=11
+            pad_to_word(11) = 5 → 5 zero bytes      → total header = 8 bytes
+          int64(42)                                 = 8 bytes
+          text("hello") = b"hello\\0\\0\\0"          = 8 bytes
+        Total body = 8 + 8 + 8 + 8 = 32 bytes = 4 words
+        """
+        # Params tuple header: count=2, types INTEGER(1) TEXT(3), padded to word
+        params_header = bytes([0x02, 0x01, 0x03, 0x00, 0x00, 0x00, 0x00, 0x00])
+        expected = (
+            _header(4, 5, schema=0) + _u32(1) + _u32(2) + params_header + _i64(42) + _text("hello")
+        )
+        msg = ExecRequest(db_id=1, stmt_id=2, params=[42, "hello"])
+        assert encode_message(msg) == expected
+
+        decoded = decode_message(expected, is_request=True)
+        assert isinstance(decoded, ExecRequest)
+        assert decoded.db_id == 1
+        assert decoded.stmt_id == 2
+        assert decoded.params == [42, "hello"]
+
+
+class TestGoldenResponses:
+    """Verify response message encoding matches hand-built spec bytes."""
+
+    def test_failure_response(self) -> None:
+        """FailureResponse(code=1, message="not leader"): type=0.
+
+        Body: uint64(1) + text("not leader")
+        text("not leader") = 10 chars + null = 11 bytes, pad to 16
+        Total body = 8 + 16 = 24 = 3 words
+        """
+        expected = _header(3, 0) + _u64(1) + _text("not leader")
+        assert encode_message(FailureResponse(code=1, message="not leader")) == expected
+
+        msg = decode_message(expected, is_request=False)
+        assert isinstance(msg, FailureResponse)
+        assert msg.code == 1
+        assert msg.message == "not leader"
+
+    def test_result_response(self) -> None:
+        """ResultResponse(last_insert_id=5, rows_affected=3): type=6.
+
+        Body: uint64(5) + uint64(3) = 16 bytes = 2 words
+        """
+        expected = _header(2, 6) + _u64(5) + _u64(3)
+        assert encode_message(ResultResponse(last_insert_id=5, rows_affected=3)) == expected
+
+        msg = decode_message(expected, is_request=False)
+        assert isinstance(msg, ResultResponse)
+        assert msg.last_insert_id == 5
+        assert msg.rows_affected == 3
+
+    def test_rows_response_nibble_packing(self) -> None:
+        """RowsResponse with INTEGER and TEXT columns: type=7.
+
+        Verifies row-header nibble packing order: low nibble = first column.
+
+        Body layout:
+          uint64(2)                          = 8 bytes  (column_count)
+          text("id")   = b"id\\0" + 5 pad    = 8 bytes
+          text("name") = b"name\\0" + 3 pad  = 8 bytes
+          row header: 2 cols [INTEGER=1, TEXT=3]
+            byte 0 = (1 & 0x0F) | ((3 & 0x0F) << 4) = 0x31
+            + 7 pad                           = 8 bytes
+          int64(1)                           = 8 bytes
+          text("alice") = b"alice\\0" + 2 pad = 8 bytes
+          DONE marker = uint64(0xFFFFFFFFFFFFFFFF) = 8 bytes
+        Total body = 56 bytes = 7 words
+        """
+        row_header = bytes([0x31, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
+        done_marker = _u64(0xFFFFFFFFFFFFFFFF)
+
+        expected = (
+            _header(7, 7)
+            + _u64(2)
+            + _text("id")
+            + _text("name")
+            + row_header
+            + _i64(1)
+            + _text("alice")
+            + done_marker
+        )
+
+        msg_obj = RowsResponse(
+            column_names=["id", "name"],
+            column_types=[ValueType.INTEGER, ValueType.TEXT],
+            rows=[[1, "alice"]],
+        )
+        assert encode_message(msg_obj) == expected
+
+        msg = decode_message(expected, is_request=False)
+        assert isinstance(msg, RowsResponse)
+        assert msg.column_names == ["id", "name"]
+        assert msg.rows == [[1, "alice"]]
+        assert msg.has_more is False
+
+    def test_rows_response_boolean_nibble(self) -> None:
+        """RowsResponse with BOOLEAN column uses all 4 nibble bits.
+
+        BOOLEAN = 11 = 0x0B. This is the largest type code and uses all 4 bits.
+        A 3-bit truncation bug would turn 0x0B (11) into 0x03 (TEXT).
+
+        Single column: row header byte 0 = 0x0B (low nibble only, high nibble 0)
+        """
+        row_header = bytes([0x0B, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])
+        done_marker = _u64(0xFFFFFFFFFFFFFFFF)
+
+        expected = (
+            _header(5, 7)
+            + _u64(1)  # column_count
+            + _text("flag")
+            + row_header
+            + _i64(1)  # BOOLEAN True encoded as int64(1)
+            + done_marker
+        )
+
+        msg_obj = RowsResponse(
+            column_names=["flag"],
+            column_types=[ValueType.BOOLEAN],
+            rows=[[True]],
+        )
+        assert encode_message(msg_obj) == expected
+
+        msg = decode_message(expected, is_request=False)
+        assert isinstance(msg, RowsResponse)
+        assert msg.rows == [[True]]
+
+
+class TestGoldenHandshake:
+    """Verify handshake encoding."""
+
+    def test_protocol_version_handshake(self) -> None:
+        """Protocol version 1 is sent as 8-byte little-endian uint64."""
+        from dqlitewire.codec import MessageEncoder
+
+        expected = b"\x01\x00\x00\x00\x00\x00\x00\x00"
+        assert MessageEncoder().encode_handshake() == expected
+
+    def test_legacy_version_handshake(self) -> None:
+        """Legacy version 0x86104dd760433fe5."""
+        from dqlitewire.codec import MessageEncoder
+        from dqlitewire.constants import PROTOCOL_VERSION_LEGACY
+
+        expected = struct.pack("<Q", 0x86104DD760433FE5)
+        assert MessageEncoder(version=PROTOCOL_VERSION_LEGACY).encode_handshake() == expected
+
+
+class TestGoldenTextEncoding:
+    """Verify text encoding edge cases against spec."""
+
+    def test_text_exact_word_boundary(self) -> None:
+        """7-char string + null = 8 bytes = exactly 1 word, no extra padding."""
+        from dqlitewire.types import encode_text
+
+        # "abcdefg" = 7 bytes + null = 8 bytes
+        result = encode_text("abcdefg")
+        assert result == b"abcdefg\x00"
+        assert len(result) == 8
+
+    def test_text_needs_padding(self) -> None:
+        """8-char string + null = 9 bytes, padded to 16."""
+        from dqlitewire.types import encode_text
+
+        result = encode_text("abcdefgh")
+        assert result == b"abcdefgh\x00" + b"\x00" * 7
+        assert len(result) == 16
+
+    def test_empty_text(self) -> None:
+        """Empty string = null byte + 7 pad = 8 bytes."""
+        from dqlitewire.types import encode_text
+
+        result = encode_text("")
+        assert result == b"\x00" + b"\x00" * 7
+        assert len(result) == 8
+
+
+class TestGoldenBlobEncoding:
+    """Verify blob encoding against spec."""
+
+    def test_blob_with_padding(self) -> None:
+        """Blob: uint64 length prefix + data + padding to word boundary."""
+        from dqlitewire.types import decode_blob, encode_blob
+
+        data = b"\xde\xad"  # 2 bytes
+        result = encode_blob(data)
+        # uint64(2) + 2 data bytes + 6 pad bytes = 16
+        expected = _u64(2) + b"\xde\xad" + b"\x00" * 6
+        assert result == expected
+        assert len(result) == 16
+
+        decoded_data, consumed = decode_blob(result)
+        assert decoded_data == data
+        assert consumed == 16
+
+    def test_blob_exact_word(self) -> None:
+        """8-byte blob needs no padding after data."""
+        from dqlitewire.types import encode_blob
+
+        data = b"\x01\x02\x03\x04\x05\x06\x07\x08"
+        result = encode_blob(data)
+        expected = _u64(8) + data
+        assert result == expected
+        assert len(result) == 16