docs(wire): catch the wire protocol spec up to what the code actually does

[rustyconover]

docs/WIRE_PROTOCOL.md was last updated at 2505b28 (~v0.36). Nine releases later it had drifted: three request-metadata keys had never been written down, the HTTP half was a release behind on headers and endpoints, and two of its claims would actively mislead someone writing a port.

Corrected

Spec said	Code does
Capability discovery is OPTIONS {prefix}/__capabilities__	No such route exists in vgi_rpc/. The reference client probes OPTIONS {prefix}/health (http/_client.py:1788), and so does the cross-language conformance suite. The only __capabilities__ responder in the tree is one tests/serve_conformance_http.py adds for itself.
Implementation error → 500	_set_http_status translates every 500 into 200 + X-VGI-RPC-Error: true (http/server/_responses.py:120-136).
"Type error in implementation → 400"	Stale since 58c93a7 — the exception's class no longer picks the status.
(nothing)	413 when the body exceeds VGI-Max-Request-Bytes.

The 200-not-500 correction gets its own subsection rather than a table row, because it has a consequence worth stating outright: a client that classifies by status code alone reads every application failure as a success. The body is where the typed error lives, and intermediaries routinely discard bodies on 5xx — which is the whole reason for the translation.

Newly documented

Each of these is wire-visible and had zero mentions in the spec:

• vgi_rpc.protocol_version — the enforced cross-language version contract. Exact major+minor rule, patch ignored, __describe__ exempt, ProtocolVersionError carrying error_kind. Includes why this is the cross-language contract and protocol_hash is not.
• vgi_rpc.error_kind — open set, four well-known values (method_not_implemented, protocol_version_mismatch, session_lost, server_draining).
• vgi_rpc.cancel — presence-is-the-signal, on both the pipe lockstep exchange and the HTTP /exchange request.
• vgi_rpc.location.sha256 — optional to emit, mandatory to verify, computed pre-compression and checked post-decompression.
• Content-encoding negotiation — VGI-Supported-Encodings, X-VGI-Accept-Encoding, X-VGI-Content-Encoding. Covers why the custom accept header outranks the generic one (general-purpose HTTP clients inject their own, and gzip measured ~an order of magnitude slower than zstd on large Arrow bodies), and why identity is honourable but never advertised.
• Sticky sessions — new §17 giving the wire surface (headers, DELETE {prefix}/__session__, failure kinds) and pointing at docs/sticky-sessions-spec.md for the normative contract, matching how the spec already handles proxy-proof and unauthorized.
• The real endpoint list — split into the Arrow RPC surface, framework endpoints, and the optional human/IdP-facing pages a port may omit.
• The full response-header set — previously four entries, now the complete capability set plus the 401 and session headers, each with when it is emitted.

Verification

• mkdocs build --strict — clean.
• Every in-page anchor checked against id= attributes in the built HTML; all resolve.
• ruff format --check / ruff check — clean.
• uv run pytest — 4062 passed, 163 skipped.

Docs-only; no code changes.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!