@@ -678,6 +678,19 @@ async def find_leader(
         single-flight collapse is a deliberate trade-off: the alternative
         (re-poll the node store between probes) costs an extra await
         per probe to close a window most callers do not exercise.
+
+        Address-only return: go-dqlite's connector adopts the probe
+        socket on success and returns the open ``*Protocol``;
+        Python's ``find_leader`` returns just an address string,
+        and high-level callers (:meth:`connect`,
+        :meth:`ConnectionPool._create_connection`,
+        :meth:`open_admin_connection`) re-dial. The cost is one
+        extra TCP three-way + handshake RTT per success path on
+        the leader — the leader pays N round-trips for N
+        concurrent acquirers if no single-flight collapse applies,
+        and one round-trip for N collapsed acquirers if it does.
+        Operators sizing ``attempt_timeout`` on high-RTT WAN
+        deployments should budget for the extra round trip.
         """
         self._check_pid()
         # Resolve ``policy=None`` to ``self._redirect_policy`` BEFORE
@@ -1608,6 +1621,43 @@ async def connect(
         enable debug logging to diagnose cluster churn instead of
         seeing only the final exception.
 
+        Comparison to go-dqlite
+        -----------------------
+
+        Two structural divergences from go-dqlite's
+        ``Connector.Connect`` (``/internal/protocol/connector.go``)
+        operators porting code should know about:
+
+        1. Cancel-propagation discipline. go-dqlite checks
+           ``ctx.Done()`` only at the TOP of each retry iteration
+           (``attempt > 1``), so the FIRST attempt always runs even
+           if the context was already cancelled when ``Connect``
+           was invoked. Python's asyncio cancel propagates through
+           every ``await`` checkpoint, so an outer
+           ``asyncio.timeout(0)`` wrapping ``cluster.connect()``
+           lands the cancel BEFORE the first attempt. The first
+           attempt never runs; the caller sees a bare
+           ``TimeoutError`` with no per-attempt log breadcrumb.
+           This is the CORRECT shape for the Python ecosystem
+           (asyncio's structured-concurrency cancel contract is the
+           source of truth); callers porting from Go that rely on
+           "one attempt is always made" semantics must adapt.
+
+        2. Discovery vs. connection: double-dial cost. go-dqlite's
+           ``connectAttemptOne`` adopts the probe socket on success
+           (``case address:`` arm at ``connector.go:392-409`` sends
+           ``EncodeClient`` on the OPEN socket). Python's design
+           returns an address from ``_query_leader`` and re-dials
+           in ``_connect_impl`` — every successful
+           ``ClusterClient.connect()`` pays one extra TCP three-way
+           + handshake RTT to the leader. The single-flight slot
+           amortises the probe sweep across N concurrent
+           ``connect()`` callers, so the cost grows linearly with
+           ``max_size`` for pool warm-up but not per-acquire when
+           probes overlap. Operators sizing ``attempt_timeout`` on
+           high-RTT WAN deployments should budget for the extra
+           round trip.
+
         Args:
             close_timeout: Budget (seconds) for the transport-drain
                 during ``close()``. After ``writer.close()`` the
 
@@ -302,12 +302,49 @@ async def handshake(self, client_id: int | None = None) -> int:
         lighter :meth:`negotiate_protocol_only` instead.
         """
         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.
+            # Deliberate divergence from go-dqlite. Go declares
+            # ``Connector.clientID uint64`` (``connector.go:75-83``)
+            # default-zero and never assigns; every Go connection
+            # registers with ``id=0``. The server-side
+            # ``handle_client`` (``gateway.c:300-309``) stores
+            # ``g->client_id = request.id`` verbatim — used only
+            # for ``tracef`` records and per-connection
+            # ``handle_interrupt`` keying, neither of which requires
+            # a unique id per connection.
+            #
+            # Python randomises so each connection is distinguishable
+            # in server logs, traces, and per-client metrics — useful
+            # for operators tailing a busy server and filtering by
+            # connection id. 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 — preserved deliberately so an
+            # operator's ``client_id != 0`` filter is reliable.
+            #
+            # Operational trade-offs:
+            #
+            # * Mixed-client clusters: an operator filtering server
+            #   logs by ``client_id`` sees Python connections with
+            #   random 63-bit ids while Go connections all show id 0;
+            #   the same filter cannot apply uniformly across both
+            #   client implementations.
+            # * No cross-reconnect correlation: a Python client that
+            #   loses connection and reconnects gets a FRESH random
+            #   id, so server-side per-client metrics see one
+            #   connection per attempt rather than one client with
+            #   several attempts. Go's id=0 doesn't solve this either,
+            #   but the current Python design forecloses a future
+            #   operator-supplied stable id without an API change.
+            # * ``secrets.randbits`` (CSPRNG-backed via
+            #   ``getrandom(2)`` on Linux) is the choice over the
+            #   faster ``random.getrandbits`` because the
+            #   ``random._inst`` PRNG state is process-global and
+            #   not fork-aware (see ``retry._retry_random`` and
+            #   ``cluster._cluster_random`` for the same reasoning
+            #   at sibling sites). The per-handshake cost is
+            #   sub-microsecond and negligible against handshake
+            #   RTT; the fork-safety property is the load-bearing
+            #   reason for this choice.
             client_id = secrets.randbits(63) or 1
         # Send protocol version + client registration together
         request = ClientRequest(client_id=client_id)
@@ -1183,15 +1220,41 @@ def _operation_deadline(self) -> float:
         order of ``2 × timeout`` (send + read+drain), and a fresh
         ``connect → query`` flow can stack ``handshake`` +
         ``open_database`` + ``query_sql`` for proportionally more.
-        Callers needing an absolute end-to-end bound should wrap the
-        outer call in ``asyncio.timeout`` / ``asyncio.wait_for``.
+        Concrete worst-case quantification: a continuation-paginated
+        result with N frames pays N × ``timeout`` because each
+        continuation frame consumes its own per-read deadline (no
+        cumulative budget bounds the read sequence). With
+        ``timeout=10s`` and a 10-frame continuation, end-to-end
+        wall-clock can reach ~120 s (send + read + 10 × continuation
+        read) while every individual phase stayed within the
+        operator's configured budget. Callers needing an absolute
+        end-to-end bound should wrap the outer call in
+        ``asyncio.timeout`` / ``asyncio.wait_for``.
+
+        Server-heartbeat amplification: when
+        ``trust_server_heartbeat=True`` widens ``_read_timeout`` up
+        to the 300 s hard cap, the PER-PHASE budget grows; the
+        end-to-end multiplier compounds. A 5-phase RPC with the
+        server advertising the cap can stack 5 × 300 s = 1500 s of
+        read time even when the operator set ``timeout=10``. The
+        cap is per-phase, not cumulative — opting into the widening
+        is opting out of the operator's per-RPC SLO at the
+        cumulative level. Operators whose ``timeout`` is a
+        latency-SLO boundary should NOT opt in (the default is
+        ``False``).
 
         Note: this differs from go-dqlite, which uses an absolute
-        per-call deadline (``conn.SetDeadline(ctx.Deadline())``). The
-        per-phase shape here is a deliberate Python-side choice — the
-        asyncio.wait_for wraps individual sends and reads independently
-        — and is documented at :class:`DqliteConnection` for caller
-        guidance.
+        per-call deadline (``conn.SetDeadline(ctx.Deadline())`` at
+        ``connector.go:312-333`` — applied to BOTH the
+        ``conn.Write`` and any subsequent ``conn.Read`` until
+        cleared). The per-phase shape here is a deliberate
+        Python-side choice — the asyncio.wait_for wraps individual
+        sends and reads independently — and is documented at
+        :class:`DqliteConnection` for caller guidance. The
+        :class:`DqliteConnection` and :class:`ConnectionPool`
+        docstrings echo the worst-case multiplier so operators
+        sizing ``timeout`` for SLO-bound queries see the same shape
+        at every entry point.
         """
         return asyncio.get_running_loop().time() + self._read_timeout
 
 
@@ -0,0 +1,62 @@
+"""Pin: an outer cancel landing BEFORE
+``ClusterClient.connect``'s first attempt runs propagates through
+asyncio cleanly — no per-attempt log breadcrumb fires (because the
+inner ``try_connect`` never ran), the cancel propagates as the
+canonical Python idiom.
+
+This is the structural divergence from go-dqlite's
+``Connector.Connect`` which checks ``ctx.Done()`` only at
+``attempt > 1`` and lets the FIRST attempt always run. Python's
+asyncio cancel propagates through every ``await`` checkpoint —
+the CORRECT shape for the Python ecosystem.
+
+The pin trips if a future change adds a CancelledError catch in
+``try_connect`` to synthesise a breadcrumb (which would violate
+structured-concurrency cancel propagation).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+import pytest
+
+from dqliteclient.cluster import ClusterClient
+from dqliteclient.node_store import MemoryNodeStore
+
+
+@pytest.mark.asyncio
+async def test_outer_cancel_before_first_attempt_does_not_log_breadcrumb(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """``asyncio.timeout(0)`` wrapping ``cluster.connect()`` lands
+    the cancel BEFORE any ``try_connect`` invocation. The
+    per-attempt DEBUG breadcrumb at ``cluster.py`` must NOT fire,
+    confirming Python's structured-concurrency cancel propagation
+    is preserved (no defensive CancelledError catch synthesises
+    a "we tried once" breadcrumb)."""
+    cluster = ClusterClient(MemoryNodeStore(["10.0.0.1:9001"]))
+
+    caplog.set_level(logging.DEBUG, logger="dqliteclient.cluster")
+
+    with pytest.raises((TimeoutError, asyncio.CancelledError)):
+        async with asyncio.timeout(0):
+            await cluster.connect()
+
+    # The per-attempt log emitter at try_connect lives inside the
+    # attempt body; if the cancel landed before the body ran, the
+    # log should NOT contain the per-attempt phrase. The exact
+    # substring "attempt" is too broad (it might appear in other
+    # cluster-side log messages); pin instead on the cluster.connect
+    # attempt-failed breadcrumb specifically.
+    breadcrumb_phrases = ("attempt failed", "Connection attempt")
+    matching = [
+        r for r in caplog.records if any(phrase in r.getMessage() for phrase in breadcrumb_phrases)
+    ]
+    assert not matching, (
+        "Outer cancel-before-first-attempt produced per-attempt log records "
+        f"({len(matching)}); a defensive CancelledError catch in try_connect "
+        "is suppressing the structured-concurrency cancel contract. "
+        "Records: " + " | ".join(r.getMessage() for r in matching)
+    )
@@ -0,0 +1,77 @@
+"""Pins for permanent documentation notes describing structural
+divergences from go-dqlite. Each pin is a substring fence on a
+docstring or in-source comment; a future refactor that drops the
+note trips the pin so the reviewer keeps the rationale in place.
+
+The pins cover four divergences:
+
+1. ``ClusterClient.connect`` — cancel propagation through asyncio
+   vs go's ``ctx.Done()`` check at iteration tops.
+2. ``ClusterClient.connect`` and ``find_leader`` — double-dial
+   structural cost (Python returns an address; Go adopts the
+   probe socket).
+3. ``DqliteProtocol.handshake`` — deliberate randomised
+   ``client_id`` divergence from go-dqlite's default-zero.
+4. ``DqliteProtocol._operation_deadline`` — per-phase timeout
+   vs Go's absolute per-call ``conn.SetDeadline`` deadline.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+from dqliteclient.cluster import ClusterClient
+from dqliteclient.protocol import DqliteProtocol
+
+
+def test_cluster_connect_documents_cancel_propagation_divergence() -> None:
+    doc = ClusterClient.connect.__doc__ or ""
+    assert "Comparison to go-dqlite" in doc
+    assert "Cancel-propagation discipline" in doc
+    # The "first attempt always runs" Go behaviour is the load-bearing
+    # contrast point.
+    assert "first attempt" in doc.lower()
+
+
+def test_cluster_connect_documents_double_dial_cost() -> None:
+    doc = ClusterClient.connect.__doc__ or ""
+    assert "double-dial" in doc.lower() or "extra TCP three-way" in doc
+    # Operators reading this note must understand they pay one extra
+    # RTT per successful connect on the leader.
+    assert "extra" in doc.lower() and "round trip" in doc.lower()
+
+
+def test_find_leader_documents_address_only_return() -> None:
+    """``find_leader``'s docstring documents that it returns an
+    address (not an open protocol), so high-level callers re-dial."""
+    doc = ClusterClient.find_leader.__doc__ or ""
+    assert "address" in doc.lower()
+    assert "re-dial" in doc.lower() or "extra TCP three-way" in doc
+
+
+def test_handshake_documents_client_id_divergence_rationale() -> None:
+    """The source comment at the randomisation site documents the
+    Go-divergence rationale: Go is default-zero, Python randomises
+    for log distinguishability, the cost / fork-safety trade-off
+    against ``random.getrandbits`` lives in the comment."""
+    src = inspect.getsource(DqliteProtocol.handshake)
+    assert "Deliberate divergence from go-dqlite" in src
+    # The operational trade-offs the comment must call out:
+    assert "Mixed-client clusters" in src
+    assert "secrets.randbits" in src
+    # Cross-references to sibling SystemRandom sites for symmetry.
+    assert "_retry_random" in src or "_cluster_random" in src
+
+
+def test_operation_deadline_documents_per_phase_worst_case_quantified() -> None:
+    """The ``_operation_deadline`` docstring documents the per-phase
+    vs Go-absolute-deadline divergence AND the quantitative
+    worst-case multiplier."""
+    src = inspect.getsource(DqliteProtocol._operation_deadline)
+    # Quantitative example (the 10-frame / 120s shape).
+    assert "10-frame" in src or "10 × continuation" in src.replace("times", "×")
+    assert "120" in src
+    # The trust_server_heartbeat amplification call-out.
+    assert "300 s" in src or "300s" in src
+    # The Go contrast remains.
+    assert "differs from go-dqlite" in src