Rewrite the README as a lean intro and move detail into docs/

The README had grown into a dense reference (caps, stricter validations,
asymmetric encode/decode), which is unwelcoming to a first-time visitor
trying to decide whether the package is relevant. Replace it with a short
overview: what the package is, who should use it (and who should reach for
a higher layer instead), a minimal example, and the place of this package
in the four-package dqlite stack with links.

Move the still-useful detail into docs/: thread-safety (single-owner
codec objects) and the deliberate divergences from the C server and
go-dqlite.

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

Author: antoineleclair

README.md

@@ -1,101 +1,62 @@
 # dqlite-wire
 
-Pure Python wire protocol implementation for [dqlite](https://dqlite.io/), Canonical's distributed SQLite.
+Pure-Python codec for the [dqlite](https://dqlite.io/) wire protocol —
+encode and decode the messages a dqlite server speaks.
+
+[dqlite](https://dqlite.io/) is Canonical's distributed SQLite, built on
+Raft. This package implements the bytes-on-the-wire layer: it turns
+request/response objects into frames and back, following the
+[official wire-protocol specification](https://canonical.com/dqlite/docs/reference/wire-protocol).
+It does no networking, pooling, or SQL — just framing.
+
+## Is this the package you want?
+
+Probably not, unless you are building a driver or doing wire-level work
+(a proxy, traffic capture/replay, a custom client). If you just want to
+run SQL against dqlite from Python, use one of the higher layers — see
+[The dqlite Python stack](#the-dqlite-python-stack) below.
 
 ## Installation
 
 ```bash
 pip install dqlite-wire
 ```
 
+Requires Python 3.13+.
+
 ## Usage
 
 ```python
 from dqlitewire import encode_message, decode_message
 from dqlitewire.messages import LeaderRequest
 
-# Encode a message
+# Encode a request to bytes
 data = encode_message(LeaderRequest())
 
-# Decode a message
+# Decode bytes back into a message object
 message = decode_message(data, is_request=True)
 ```
 
-## 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).
-
-## Deliberate divergences from upstream
-
-This library implements the dqlite wire protocol faithfully but adds a
-handful of defensive guards that the upstream C server and the
-canonical [go-dqlite](https://github.com/canonical/go-dqlite) client do
-not. They protect a Python client running in potentially adversarial
-network contexts and are all opt-out-able.
-
-**Python-specific caps** (not present in C or Go; `None` disables):
-
-- `DEFAULT_MAX_TOTAL_ROWS` (`MessageDecoder(max_total_rows=...)`, default
-  10,000,000) — cap on rows accumulated across continuation frames for
-  one query. Importable from `dqlitewire`.
-- `DEFAULT_MAX_CONTINUATION_FRAMES` (`MessageDecoder(max_continuation_frames=...)`,
-  default 100,000) — cap on continuation frames for one query.
-  Importable from `dqlitewire`.
-- `RowsResponse.DEFAULT_MAX_ROWS` (`MessageDecoder(max_rows=...)`,
-  default 1,000,000) — per-frame row cap. Class-scoped, not exported
-  at module level.
-- `ReadBuffer.DEFAULT_MAX_MESSAGE_SIZE` (`ReadBuffer(max_message_size=...)`,
-  default 64 MiB) — envelope cap on a single frame. Class-scoped, not
-  exported at module level.
-- `_MAX_PARAM_COUNT` (32,766 — matches SQLite's
-  `SQLITE_MAX_VARIABLE_NUMBER`), `_MAX_COLUMN_COUNT` (2000 — SQLite's
-  documented `SQLITE_MAX_COLUMN` compile-time default), `_MAX_FILE_COUNT` (100),
-  `_MAX_NODE_COUNT` (10,000) — internal sanity bounds on decoded
-  tuple / response sizes.
-
-**Stricter-than-Go validations** (match the C server's intent):
-
-- `decode_row_header` requires the full 8-byte marker (C defines
-  `DQLITE_RESPONSE_ROWS_DONE = 0xff..ff` / `_PART = 0xee..ee`;
-  go-dqlite checks only the first byte).
-- `encode_value(value, ValueType.BOOLEAN)` rejects arbitrary ints
-  (accepts only `bool` or exactly `0`/`1`).
-- `FilesResponse.encode_body` rejects non-8-aligned file content (C's
-  `dumpFile` asserts `len % 8 == 0`).
-- `encode_params_tuple` rejects `ValueType.UNIXTIME` outbound (C's
-  `tuple_decoder__next` cannot decode it on the server side).
-- `StmtResponse` rejects a 16-byte body when `schema=1` (C's V1
-  response is 24 bytes).
-
-**Asymmetric encode/decode** (decoded for proxy / recorded-traffic
-round-trip; fresh construction rejected):
-
-- `ClusterRequest` `format=0` — V0 response shape (id + address only).
-  Decoded by `ClusterRequest.decode_body` for proxy / replay use. A
-  *decoded* V0 frame carries the `_decoded` sentinel and re-encodes
-  byte-identically, so capture-replay tooling can round-trip it through
-  the dataclass. *Fresh* construction with `format=0` is rejected with
-  `EncodeError`, because production senders always emit V1 (id + address
-  + role) and this client only decodes the V1 `ServersResponse`.
+## The dqlite Python stack
+
+This is the lowest of four layered packages. Each builds on the one below:
+
+| Package | Role |
+| --- | --- |
+| [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite) | SQLAlchemy 2.0 dialect |
+| [dqlite-dbapi](https://github.com/letsdiscodev/python-dqlite-dbapi) | PEP 249 (DB-API 2.0) driver — sync & async |
+| [dqlite-client](https://github.com/letsdiscodev/python-dqlite-client) | Async wire client — pooling, leader discovery |
+| **dqlite-wire** — this package | Wire-protocol codec |
+
+**Most applications should use [dqlite-dbapi](https://github.com/letsdiscodev/python-dqlite-dbapi)
+or [sqlalchemy-dqlite](https://github.com/letsdiscodev/sqlalchemy-dqlite).**
+
+## Documentation
+
+- [Thread-safety](docs/thread-safety.md) — codec objects are single-owner; read this before sharing one.
+- [Divergences from upstream](docs/divergences-from-upstream.md) — the
+  defensive caps and stricter validations this codec adds on top of the C
+  server and [go-dqlite](https://github.com/canonical/go-dqlite).
 
 ## Development
 

docs/divergences-from-upstream.md

@@ -0,0 +1,58 @@
+# Divergences from upstream
+
+This library implements the dqlite wire protocol faithfully, but adds a
+handful of defensive guards that the upstream C server and the
+[go-dqlite](https://github.com/canonical/go-dqlite) client do not. They
+protect a Python client running in potentially adversarial network
+contexts. The caps are configurable (pass `None` to disable); the stricter
+validations match the C server's intent.
+
+## Python-specific caps
+
+Bounds on how much a single decode will allocate, so a hostile or buggy
+peer cannot exhaust memory. All are optional (`None` disables):
+
+- `DEFAULT_MAX_TOTAL_ROWS` (`MessageDecoder(max_total_rows=...)`, default
+  10,000,000) — rows accumulated across continuation frames for one query.
+- `DEFAULT_MAX_CONTINUATION_FRAMES`
+  (`MessageDecoder(max_continuation_frames=...)`, default 100,000) —
+  continuation frames for one query.
+- `RowsResponse.DEFAULT_MAX_ROWS` (`MessageDecoder(max_rows=...)`, default
+  1,000,000) — per-frame row cap.
+- `ReadBuffer.DEFAULT_MAX_MESSAGE_SIZE` (`ReadBuffer(max_message_size=...)`,
+  default 64 MiB) — envelope cap on a single frame.
+- Internal sanity bounds on decoded tuple/response sizes:
+  `_MAX_PARAM_COUNT` (32,766 — SQLite's `SQLITE_MAX_VARIABLE_NUMBER`),
+  `_MAX_COLUMN_COUNT` (2000 — SQLite's default `SQLITE_MAX_COLUMN`),
+  `_MAX_FILE_COUNT` (100), `_MAX_NODE_COUNT` (10,000).
+
+`DEFAULT_MAX_TOTAL_ROWS` and `DEFAULT_MAX_CONTINUATION_FRAMES` are
+importable from `dqlitewire`; the others are class-scoped.
+
+## Stricter-than-Go validations
+
+These match the C server's intent more closely than go-dqlite does:
+
+- `decode_row_header` requires the full 8-byte end-of-rows marker (C defines
+  `DQLITE_RESPONSE_ROWS_DONE = 0xff…ff` / `_PART = 0xee…ee`; go-dqlite checks
+  only the first byte).
+- `encode_value(value, ValueType.BOOLEAN)` rejects arbitrary ints (accepts
+  only `bool` or exactly `0`/`1`).
+- `FilesResponse.encode_body` rejects non-8-aligned file content (C's
+  `dumpFile` asserts `len % 8 == 0`).
+- `encode_params_tuple` rejects `ValueType.UNIXTIME` outbound (the C server's
+  tuple decoder cannot decode it).
+- `StmtResponse` rejects a 16-byte body when `schema=1` (C's V1 response is
+  24 bytes).
+
+## Asymmetric encode/decode
+
+Some frames are decodable for proxy / recorded-traffic round-trips even
+though fresh construction of them is rejected:
+
+- `ClusterRequest` with `format=0` (the V0 response shape: id + address
+  only). `ClusterRequest.decode_body` decodes it for proxy/replay use, and a
+  *decoded* V0 frame re-encodes byte-identically. *Fresh* construction with
+  `format=0` is rejected with `EncodeError`, because production senders
+  always emit V1 (id + address + role) and this client only decodes the V1
+  `ServersResponse`.

docs/thread-safety.md

@@ -0,0 +1,20 @@
+# 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 the single-owner
+`driver.Conn` contract from [go-dqlite](https://github.com/canonical/go-dqlite).
+
+Concurrent use of one instance from multiple threads produces **silent
+data corruption — not exceptions.** Fuzz testing reliably reproduces both
+duplicate message delivery and corrupt (garbage) message bytes with no
+error raised. The internal `is_poisoned` guard catches torn state from a
+signal delivered during single-owner execution, but it **cannot** detect
+lost-update races between concurrent threads.
+
+If you need concurrent access, serialize it with an `asyncio.Lock` or
+`threading.Lock` at the layer that owns the socket and decoder. In
+practice the higher-level packages
+([dqlite-client](https://github.com/letsdiscodev/python-dqlite-client) and
+above) already do this for you — this constraint matters only if you drive
+the codec directly.