Narrow is_wire_coherent docstring to codec-layer poison only

The accessor reflects only MessageDecoder.is_poisoned, but the
previous docstring's gloss ("wire desync from a prior parse failure")
implied a broader contract that covers any wire-protocol violation.
Client-layer ProtocolError raises (prepare db_id mismatch,
_read_response extra-frame-after-FAILURE, _read_continuation
unexpected EmptyResponse, interrupt drain caps,
_drain_continuations caps) all leave the flag True at the moment of
raise even though the wire IS desynchronised at the next-request
boundary — the codec decoded correctly but the connection has
unread frames buffered or a continuation expected.

The in-tree path is masked: every ProtocolError routes through
_run_protocol → _invalidate, which closes the writer and clears
_protocol so the pool short-circuits on `protocol is None` before
this accessor is ever read. Third-party harnesses on DqliteProtocol
directly are NOT masked.

Rewrite the docstring to scope the contract to codec-layer poison,
enumerate the major client-layer raise sites that do NOT flip the
flag, and direct third-party direct-DqliteProtocol harnesses to
invalidate on any ProtocolError rather than reading this flag.

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

Author: antoineleclair

src/dqliteclient/protocol.py

@@ -178,29 +178,52 @@ def __reduce__(self) -> NoReturn:
 
     @property
     def is_wire_coherent(self) -> bool:
-        """True if the decoder buffer has not been poisoned.
+        """True if the codec-layer decoder buffer has not been poisoned.
 
-        A poisoned buffer (mid-stream desync, malformed frame, etc.)
-        cannot recover without ``reset()`` + reconnect. Pool reset
-        consults this before sending ROLLBACK so a wasted round-trip
+        Reflects ONLY the wire-codec layer (``MessageDecoder.is_poisoned``).
+        A poisoned buffer (mid-stream wire desync, malformed frame, etc.)
+        cannot recover without ``reset()`` + reconnect; the pool-reset
+        path consults this before sending ROLLBACK so a wasted round-trip
         on an already-doomed connection is short-circuited.
 
-        INTENTIONALLY consulted only by the pool reset path
-        (``pool.py::_socket_looks_dead``). The dbapi, the SA dialect,
-        and direct ``DqliteConnection`` callers route a wire desync
-        through the exception-based classifier chain instead:
-        wire-layer ``ProtocolError`` is wrapped to
-        ``OperationalError(code=None)`` by
+        Does NOT reflect client-layer ``ProtocolError`` raises that
+        detect higher-level invariant violations on top of coherent
+        bytes: ``prepare`` db_id mismatch, ``_read_response``
+        extra-frame-after-FAILURE, ``_read_continuation`` unexpected
+        EmptyResponse, ``interrupt`` drain wrong-type / no-progress /
+        frame-cap, ``_drain_continuations`` max_total_rows /
+        max_continuation_frames / no-progress. In those cases the codec
+        decoded correctly but the connection still has unread frames
+        buffered or a continuation expected; the wire IS desynchronised
+        at the next-request boundary, but ``is_wire_coherent`` returns
+        ``True``.
+
+        This narrowness is intentional. ``is_wire_coherent`` is the
+        codec-poison hint only; client-layer protocol violations route
+        through ``DqliteConnection._run_protocol``'s
+        ``ProtocolError → _invalidate`` chain, which closes the writer
+        and clears ``self._protocol`` — the pool short-circuits on
+        ``protocol is None`` before consulting this accessor at all
+        (see ``pool.py::_socket_looks_dead``).
+
+        INTENTIONALLY consulted only by the pool reset path. The
+        dbapi, the SA dialect, and direct ``DqliteConnection``
+        callers route a wire desync through the exception-based
+        classifier chain instead: wire-layer ``ProtocolError`` is
+        wrapped to ``OperationalError(code=None)`` by
         ``dqlitedbapi.cursor._call_client``, and the SA dialect's
         ``is_disconnect`` substring branch matches the
-        ``"wire decode failed"`` prefix the client emits. That
-        layering is deliberate — wire coherence is a hint, not a
-        liveness contract: a ``CancelledError`` mid-flight could
-        poison the buffer between this read and the next operation,
-        so a ``True`` return MUST NOT be treated as "the connection
-        is healthy". Use as a short-circuit optimisation only; do
-        not propagate this check to ``do_ping`` / pre-checkout
-        paths or to other operational classifiers.
+        ``"wire decode failed"`` prefix the client emits.
+
+        Wire coherence is a hint, not a liveness contract: a
+        ``CancelledError`` mid-flight could poison the buffer between
+        this read and the next operation, so a ``True`` return MUST
+        NOT be treated as "the connection is healthy". Use as a
+        short-circuit optimisation only; do not propagate this check
+        to ``do_ping`` / pre-checkout paths or to other operational
+        classifiers. Third-party harnesses that consume
+        ``DqliteProtocol`` directly should always invalidate on any
+        ``ProtocolError`` rather than reading this flag.
         """
         return not self._decoder.is_poisoned
 

tests/test_is_wire_coherent_docstring_narrowness.py

@@ -0,0 +1,43 @@
+"""Pin: ``DqliteProtocol.is_wire_coherent`` docstring scopes the
+flag to codec-layer poison only and explicitly disclaims client-
+layer ProtocolError raises.
+
+The accessor reflects only ``MessageDecoder.is_poisoned``; client-
+layer ProtocolError raises (db_id mismatch, extra-frame-after-FAILURE,
+unexpected EmptyResponse mid-ROWS, interrupt drain caps,
+_drain_continuations caps) leave it True at the moment of raise even
+though the wire IS desynchronised at the next-request boundary. The
+in-tree path is masked by _run_protocol's ProtocolError → _invalidate
+chain; third-party harnesses on DqliteProtocol directly are not
+masked.
+"""
+
+from __future__ import annotations
+
+from dqliteclient.protocol import DqliteProtocol
+
+
+def test_is_wire_coherent_docstring_calls_out_codec_layer_only() -> None:
+    doc = DqliteProtocol.is_wire_coherent.__doc__ or ""
+    assert "codec-layer" in doc.lower() or "codec layer" in doc.lower()
+    assert "is_poisoned" in doc, "Docstring should name the underlying MessageDecoder.is_poisoned"
+
+
+def test_is_wire_coherent_docstring_disclaims_client_layer_protocolerror() -> None:
+    """The docstring must explicitly call out that the flag does NOT
+    reflect client-layer ProtocolError raises."""
+    doc = DqliteProtocol.is_wire_coherent.__doc__ or ""
+    assert "Does NOT reflect" in doc or "does not reflect" in doc.lower(), (
+        "Docstring must disclaim coverage of client-layer ProtocolError raises"
+    )
+    # The major sites the audit identified should be referenced so a
+    # reader knows where to look for the contract drift.
+    assert "_drain_continuations" in doc or "drain_continuations" in doc
+
+
+def test_is_wire_coherent_docstring_directs_third_party_harnesses_to_invalidate() -> None:
+    """Third-party direct DqliteProtocol harnesses must be told to
+    invalidate on any ProtocolError rather than reading this flag."""
+    doc = DqliteProtocol.is_wire_coherent.__doc__ or ""
+    assert "third-party" in doc.lower() or "third party" in doc.lower()
+    assert "invalidate" in doc.lower()