docs(client): pin intentional go-dqlite divergences with source comments

Post-audit documentation pass. The cross-package audit flagged two
spots where we intentionally diverge from go-dqlite and where a
future reader might "helpfully" realign us to Go and regress the
behavior:

- find_leader shuffles within role class before sorting. Go's
  connector iterates nodes in deterministic stored order, which would
  stampede the same node across parallel callers. Add a block comment
  warning future maintainers not to drop the shuffle without adding
  stampede avoidance elsewhere.

- handshake generates a random client_id per connection. Go leaves the
  default. We randomize for per-client server observability (logs,
  traces, metrics). Add a comment noting the intentional divergence
  and the 63-bit + "or 1" rationale.

Neither is a behavior change. Pure source-level annotation.

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

Author: antoineleclair

src/dqliteclient/cluster.py

@@ -92,6 +92,13 @@ async def find_leader(self) -> str:
         # then stable-sort by role so voters come before non-voters.
         # Standby/spare nodes can never become leader (their LEADER
         # response is always (0, "")), so probing them first wastes RTTs.
+        #
+        # Deliberate divergence from go-dqlite: the Go connector iterates
+        # nodes in their stored order (deterministic) and relies on role
+        # to decide candidacy. We shuffle within role class to avoid
+        # stampeding a single node across parallel callers. Do not
+        # "fix" this toward Go's deterministic behavior without adding
+        # an explicit stampede-avoidance mechanism elsewhere.
         nodes = list(nodes)
         random.shuffle(nodes)
         nodes.sort(key=lambda n: 0 if n.role == 0 else 1)

src/dqliteclient/protocol.py

@@ -111,6 +111,12 @@ async def handshake(self, client_id: int | None = None) -> int:
         from the server.
         """
         if client_id is None:
+            # Deliberate divergence from go-dqlite: Go leaves the default
+            # client_id; we randomize so each connection is distinguishable
+            # in server logs, traces, and per-client metrics. 63 bits
+            # avoids sign-extension pitfalls if an intermediate layer
+            # treats the id as int64. The ``or 1`` guards against the
+            # (astronomically unlikely) all-zero draw.
             client_id = secrets.randbits(63) or 1
         # Send protocol version + client registration together
         request = ClientRequest(client_id=client_id)