docs: make the single-owner contract explicit (issue 050)

Issues 021 + 026 left the impression that the poison mechanism
would catch concurrent misuse. Fuzz testing (issue 050) reliably
refutes this: threaded readers on a shared ``ReadBuffer`` produce
duplicate messages and corrupt bytes in every trial, with
``is_poisoned`` remaining False, because torn reads frequently
yield valid-looking slices that decode cleanly and never trip the
poison gate.

The right remediation is documentation, not code. Adding a lock
would serialize the hottest method in the package for a caller
contract violation; adding an owner-thread check would break
legitimate hand-off patterns. Instead: spell out on every
class docstring and in the README that (a) the types are not
thread-safe, (b) concurrent misuse produces silent corruption
rather than exceptions, and (c) ``is_poisoned`` does not and
cannot catch lost-update races.

Add a regression test asserting the docstrings carry the warning
so future reformats cannot silently drop it.

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

Author: antoineleclair

README.md

@@ -24,6 +24,25 @@ decoder.feed(data)
 message = decoder.decode()
 ```
 
+## Thread-safety
+
+`ReadBuffer`, `WriteBuffer`, `MessageEncoder`, and `MessageDecoder`
+are **not thread-safe**. Each instance must be owned by a single
+thread or a single asyncio coroutine at a time. This matches Go's
+`driver.Conn` contract from go-dqlite.
+
+Concurrent use of a single instance from multiple threads produces
+**silent data corruption** — not exceptions. The `is_poisoned`
+mechanism catches torn state from signal delivery during
+single-owner execution, but it **cannot** detect lost-update races
+between concurrent threads. Fuzz testing reliably reproduces both
+duplicate message delivery and corrupt (garbage) message bytes with
+no exception surfacing.
+
+If you need concurrent access, wrap every call site in an
+`asyncio.Lock` or `threading.Lock` at the layer that owns the
+socket and decoder.
+
 ## Protocol Reference
 
 Based on the [dqlite wire protocol specification](https://canonical.com/dqlite/docs/reference/wire-protocol).

src/dqlitewire/buffer.py

@@ -5,7 +5,16 @@
 
 
 class WriteBuffer:
-    """Buffer for building wire protocol messages."""
+    """Buffer for building wire protocol messages.
+
+    Thread-safety: NOT thread-safe. A single ``WriteBuffer``
+    instance must be owned by one thread (or one asyncio
+    coroutine) at a time. The single-owner contract matches Go's
+    ``driver.Conn`` layer in go-dqlite; see issue 021 for the full
+    analysis. ``write_padded`` guards against the specific
+    torn-payload/pad interleave described in issue 034, but that is
+    a narrow defense, not a general thread-safety guarantee.
+    """
 
     def __init__(self) -> None:
         self._data = bytearray()
@@ -46,6 +55,33 @@ class ReadBuffer:
     """Buffer for reading wire protocol messages from a stream.
 
     Handles partial reads and message framing.
+
+    Thread-safety: NOT thread-safe. A single ``ReadBuffer`` instance
+    must be owned by one thread (or one asyncio coroutine) at a
+    time. The single-owner contract matches Go's ``driver.Conn``
+    layer in go-dqlite; see issue 021 for the full analysis.
+
+    Concurrent misuse from multiple threads produces **silent data
+    corruption**, not exceptions. Specifically:
+
+    - Two readers can each observe the same ``_pos`` and slice the
+      same message bytes, returning the same message twice while
+      silently skipping the next one (lost update on ``_pos +=``).
+    - Readers can observe torn ``_pos``/``_data`` snapshots across
+      a concurrent ``_maybe_compact()`` call, producing garbage
+      bytes that decode to plausible-looking (but wrong) messages.
+
+    The ``poison()`` mechanism does NOT and CANNOT detect this
+    class of failure. Poison is designed to catch single-owner
+    torn state from interrupted signal delivery (see issues 037,
+    041, 045). It cannot observe lost-update races or torn reads
+    that produce valid-looking output. See issue 050 for
+    reproduction details.
+
+    If you need concurrent access to a single wire stream, wrap
+    every call site in an ``asyncio.Lock`` (for coroutines) or
+    ``threading.Lock`` (for threads) at the layer that owns the
+    socket and decoder.
     """
 
     DEFAULT_MAX_MESSAGE_SIZE = 64 * 1024 * 1024  # 64 MiB

src/dqlitewire/codec.py

@@ -100,7 +100,16 @@
 
 
 class MessageEncoder:
-    """Encodes messages to wire protocol format."""
+    """Encodes messages to wire protocol format.
+
+    Thread-safety: NOT thread-safe. A single ``MessageEncoder``
+    instance must be owned by one thread (or one asyncio coroutine)
+    at a time. The encoder is effectively stateless after
+    construction (it only caches a protocol ``_version``), but the
+    single-owner contract matches the rest of the package — see
+    issue 021 and the class docstring on ``MessageDecoder`` /
+    ``ReadBuffer``.
+    """
 
     def __init__(self, version: int = PROTOCOL_VERSION) -> None:
         """Initialize encoder.
@@ -125,7 +134,30 @@ def encode_handshake(self) -> bytes:
 
 
 class MessageDecoder:
-    """Decodes messages from wire protocol format."""
+    """Decodes messages from wire protocol format.
+
+    Thread-safety: NOT thread-safe. A single ``MessageDecoder``
+    instance must be owned by one thread (or one asyncio coroutine)
+    at a time. The single-owner contract matches Go's
+    ``driver.Conn`` layer in go-dqlite; see issue 021 for the full
+    analysis.
+
+    Concurrent misuse from multiple threads produces **silent data
+    corruption**, not exceptions. The underlying ``ReadBuffer``
+    suffers from lost-update races on ``_pos`` and torn
+    ``_data``/``_pos`` snapshots across ``_maybe_compact()``
+    calls; these produce valid-looking byte slices that decode
+    cleanly to wrong (or duplicated) messages. Fuzz testing
+    (issue 050) confirms this reliably on every trial.
+
+    The ``is_poisoned`` flag does NOT detect concurrent misuse.
+    Poison is designed to catch single-owner torn state from
+    interrupted signal delivery (see issues 037, 041, 045). It
+    cannot observe lost-update races or torn reads that produce
+    valid-looking output. If you need concurrent access, wrap every
+    call site in an ``asyncio.Lock`` or ``threading.Lock`` at the
+    layer that owns the socket.
+    """
 
     def __init__(self, is_request: bool = False, version: int = PROTOCOL_VERSION) -> None:
         """Initialize decoder.

tests/test_thread_safety_contract.py

@@ -0,0 +1,80 @@
+"""Regression tests for issue 050: single-owner contract documentation.
+
+Issue 050 documented that the prior thread-safety analysis (issue 021)
++ poison mechanism (issue 026) created a misleading impression that
+concurrent misuse would always surface as ``ProtocolError``. Empirical
+fuzz testing confirmed it does not — under threaded contention,
+``ReadBuffer`` produces duplicate messages and corrupt (garbage) bytes
+with ``is_poisoned`` remaining ``False``, because torn reads often
+yield valid-looking slices that decode cleanly.
+
+The remediation is documentation, not code: the docstrings on
+``ReadBuffer``, ``WriteBuffer``, ``MessageDecoder``, and
+``MessageEncoder`` must make the single-owner contract explicit AND
+call out that the poison mechanism cannot and does not detect
+concurrent misuse. These tests assert the docstrings carry that
+warning so future refactors that reformat docstrings don't silently
+drop it.
+"""
+
+from __future__ import annotations
+
+from dqlitewire.buffer import ReadBuffer, WriteBuffer
+from dqlitewire.codec import MessageDecoder, MessageEncoder
+
+
+def _docstring(obj: object) -> str:
+    return (obj.__doc__ or "").lower()
+
+
+class TestThreadSafetyContractDocumented:
+    """Assert the thread-safety contract is explicit in class docstrings.
+
+    The contract has three parts, and all three must be mentioned:
+
+    1. The class is NOT thread-safe / requires a single owner.
+    2. Concurrent misuse produces SILENT data corruption, not
+       exceptions.
+    3. The poison mechanism does NOT detect concurrent misuse.
+
+    Any docstring-reformat that drops one of these silently
+    undoes issue 050's documentation fix.
+    """
+
+    def test_readbuffer_docstring_warns_about_thread_safety(self) -> None:
+        doc = _docstring(ReadBuffer)
+        assert "not thread-safe" in doc or "not thread safe" in doc, (
+            "ReadBuffer docstring must explicitly say it is not thread-safe"
+        )
+        assert "silent" in doc and ("corruption" in doc or "corrupt" in doc), (
+            "ReadBuffer docstring must warn that concurrent misuse produces silent corruption"
+        )
+        assert "poison" in doc, (
+            "ReadBuffer docstring must explain the poison mechanism's "
+            "relationship to concurrent misuse"
+        )
+
+    def test_writebuffer_docstring_warns_about_thread_safety(self) -> None:
+        doc = _docstring(WriteBuffer)
+        assert "not thread-safe" in doc or "not thread safe" in doc, (
+            "WriteBuffer docstring must explicitly say it is not thread-safe"
+        )
+
+    def test_message_decoder_docstring_warns_about_thread_safety(self) -> None:
+        doc = _docstring(MessageDecoder)
+        assert "not thread-safe" in doc or "not thread safe" in doc, (
+            "MessageDecoder docstring must explicitly say it is not thread-safe"
+        )
+        assert "silent" in doc and ("corruption" in doc or "corrupt" in doc), (
+            "MessageDecoder docstring must warn that concurrent misuse produces silent corruption"
+        )
+        assert "poison" in doc, (
+            "MessageDecoder docstring must explain the poison mechanism's "
+            "relationship to concurrent misuse"
+        )
+
+    def test_message_encoder_docstring_warns_about_thread_safety(self) -> None:
+        doc = _docstring(MessageEncoder)
+        assert "not thread-safe" in doc or "not thread safe" in doc, (
+            "MessageEncoder docstring must explicitly say it is not thread-safe"
+        )