Extract leader-change error codes into dqlitewire.constants

Move the 10250/10506 magic numbers (SQLITE_IOERR_NOT_LEADER,
SQLITE_IOERR_LEADERSHIP_LOST) into dqlitewire, where the rest of the
protocol constants live, and re-export them from the package root.
Downstream packages (dqliteclient, sqlalchemy-dqlite) can now import a
single authoritative definition instead of duplicating the tuple.

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

Author: antoineleclair

src/dqlitewire/__init__.py

@@ -41,12 +41,16 @@
 from dqlitewire.buffer import ReadBuffer, WriteBuffer
 from dqlitewire.codec import MessageDecoder, MessageEncoder, decode_message, encode_message
 from dqlitewire.constants import (
+    LEADER_ERROR_CODES,
     PROTOCOL_VERSION,
     PROTOCOL_VERSION_LEGACY,
     ROW_DONE_BYTE,
     ROW_DONE_MARKER,
     ROW_PART_BYTE,
     ROW_PART_MARKER,
+    SQLITE_IOERR,
+    SQLITE_IOERR_LEADERSHIP_LOST,
+    SQLITE_IOERR_NOT_LEADER,
     NodeRole,
     RequestType,
     ResponseType,
@@ -68,6 +72,7 @@
     "DecodeError",
     "EncodeError",
     "HandshakeError",
+    "LEADER_ERROR_CODES",
     "MessageDecoder",
     "MessageEncoder",
     "NodeRole",
@@ -82,6 +87,9 @@
     "ReadBuffer",
     "RequestType",
     "ResponseType",
+    "SQLITE_IOERR",
+    "SQLITE_IOERR_LEADERSHIP_LOST",
+    "SQLITE_IOERR_NOT_LEADER",
     "ServerFailure",
     "StreamError",
     "ValueType",

src/dqlitewire/constants.py

@@ -97,3 +97,20 @@ class NodeRole(IntEnum):
     VOTER = 0
     STANDBY = 1
     SPARE = 2
+
+
+# SQLite extended error codes that signal leader changes in a dqlite
+# cluster. Upstream definitions in ``dqlite-upstream/include/dqlite.h``:
+#
+#     #define SQLITE_IOERR_NOT_LEADER       (SQLITE_IOERR | (40 << 8))
+#     #define SQLITE_IOERR_LEADERSHIP_LOST  (SQLITE_IOERR | (41 << 8))
+#
+# where ``SQLITE_IOERR = 10``. Callers (``dqliteclient`` and
+# ``sqlalchemy-dqlite``) import these to decide whether to invalidate a
+# connection and retry against a fresh leader.
+SQLITE_IOERR = 10
+SQLITE_IOERR_NOT_LEADER = SQLITE_IOERR | (40 << 8)  # 10250
+SQLITE_IOERR_LEADERSHIP_LOST = SQLITE_IOERR | (41 << 8)  # 10506
+LEADER_ERROR_CODES: frozenset[int] = frozenset(
+    {SQLITE_IOERR_NOT_LEADER, SQLITE_IOERR_LEADERSHIP_LOST}
+)

tests/test_constants.py

@@ -175,3 +175,49 @@ def test_response_types_covers_all_enum_members(self) -> None:
             assert member.value in RESPONSE_TYPES, (
                 f"ResponseType.{member.name} ({member.value}) has no entry in RESPONSE_TYPES"
             )
+
+
+class TestLeaderErrorCodes:
+    """Pin the SQLite extended error codes that signal leader changes."""
+
+    def test_sqlite_ioerr_base(self) -> None:
+        from dqlitewire.constants import SQLITE_IOERR
+
+        assert SQLITE_IOERR == 10
+
+    def test_not_leader_code_value(self) -> None:
+        from dqlitewire.constants import SQLITE_IOERR, SQLITE_IOERR_NOT_LEADER
+
+        assert SQLITE_IOERR_NOT_LEADER == 10250
+        assert SQLITE_IOERR_NOT_LEADER == SQLITE_IOERR | (40 << 8)
+
+    def test_leadership_lost_code_value(self) -> None:
+        from dqlitewire.constants import SQLITE_IOERR, SQLITE_IOERR_LEADERSHIP_LOST
+
+        assert SQLITE_IOERR_LEADERSHIP_LOST == 10506
+        assert SQLITE_IOERR_LEADERSHIP_LOST == SQLITE_IOERR | (41 << 8)
+
+    def test_leader_error_codes_is_a_frozenset_of_both(self) -> None:
+        from dqlitewire.constants import (
+            LEADER_ERROR_CODES,
+            SQLITE_IOERR_LEADERSHIP_LOST,
+            SQLITE_IOERR_NOT_LEADER,
+        )
+
+        assert isinstance(LEADER_ERROR_CODES, frozenset)
+        expected = frozenset({SQLITE_IOERR_NOT_LEADER, SQLITE_IOERR_LEADERSHIP_LOST})
+        assert expected == LEADER_ERROR_CODES
+
+    def test_leader_error_codes_importable_from_top_level(self) -> None:
+        from dqlitewire import (
+            LEADER_ERROR_CODES,
+            SQLITE_IOERR,
+            SQLITE_IOERR_LEADERSHIP_LOST,
+            SQLITE_IOERR_NOT_LEADER,
+        )
+
+        assert SQLITE_IOERR == 10
+        assert SQLITE_IOERR_NOT_LEADER == 10250
+        assert SQLITE_IOERR_LEADERSHIP_LOST == 10506
+        expected = frozenset({10250, 10506})
+        assert expected == LEADER_ERROR_CODES