miniopenenv

docs/PROTOCOL.md → html

The OpenEnv protocol, as this implementation understands it

This page is our statement of the OpenEnv protocol: what a conforming server puts on a wire, written from captured traffic rather than from anybody's documentation. It is short because the protocol is short. Everything long about OpenEnv is a Python library that speaks it.

It is normative for this repository and nothing else. Where it differs from the reference — huggingface/OpenEnv, the Python implementation this repository was captured from — the reference wins. WARTS.md records each such difference at the line that reproduces it. Where nothing decides, GAPS.md says so. A WART-nn, GAP-nn or CONF-nn below is a numbered entry in those ledgers: a reference accident we reproduce, a question the protocol does not answer, or a conformance requirement. How all of it was derived is PROVENANCE.md.

There is no protocol version anywhere in OpenEnv. Not in a header, not in a payload, not in the handshake. GET /openapi.json's info.version is the closest thing that exists, and it describes the document, not the wire. This is worth knowing before you read the rest: nothing below can be negotiated.


§ 1 · The shape, in one paragraph

1. The shape, in one paragraph

A conforming server is an HTTP/1.1 server on TCP port 8000, bound 0.0.0.0, that answers GET /health and accepts a WebSocket upgrade at /ws. Over that socket it speaks text frames, one JSON object each, strictly lock-step: one client message, exactly one server response. No pipelining, no correlation ids, no server-initiated frames. An episode — one run of the loop: a reset, then steps, until done — happens on that socket and nowhere else. Everything else the server exposes — the fourteen other routes, the schema, the /mcp tool surface — is discoverable and optional in practice.


§ 2 · The sixteen routes

2. The sixteen routes

The table in ../src/proto/routes.c ↗ is the executable form of this, and tests/t_routes.c asserts the count.

MethodPathAnswersIn /openapi.json?
GET, HEAD/openapi.jsonthe document. info.version selects the conformance profileno — it cannot describe itself
GET/list_environments["<task name>"]. One row: a server is one environmentyes
GET/{env_name}/splitsTask APIyes
POST/{env_name}/tasksTask APIyes
POST/{env_name}/num_tasksTask APIyes
POST/{env_name}/taskTask APIyes
POST/{env_name}/task_rangeTask APIyes
—WS /mcpbare JSON-RPC, spaced separatorsno — OpenAPI cannot describe a WebSocket
POST/resetthe four-key envelope. Statelessyes (simulation mode only)
POST/stepthe four-key envelope. Statelessyes (simulation mode only)
GET/stateepisode_id and step_count, and nothing elseyes (simulation mode only)
GET/metadatasix keys, fixed orderyes
GET/health{"status":"healthy"}yes
GET/schemaaction, observation, stateyes
POST/mcpJSON-RPC 2.0, four methods, always HTTP 200yes
—WS /wsthe episodeno

Registration order is observable. The five templated Task API rows are registered before the fixed one-segment paths. That is why GET /nope/splits reaches a handler that knows the word "environment" and answers {"detail":"unknown environment 'nope'"}, while GET /nope falls through to {"detail":"Not Found"}. Two different 404 bodies on one server; WART-15.

Three rows are simulation-only. Production mode removes /reset, /step and /state and answers 404 for them. Never 405: the row ceases to exist, and the 404 is decided before the method is looked at. WS /ws is left untouched, so the stateful transport survives and the stateless mirror does not. This project serves both modes: oe_serve_opts.production (and the production parameter of oe_http_handle) selects the reference's ServerMode.PRODUCTION, with simulation the default. Nothing in the reference tree reaches production from a shipped entry point. So the corpus — the captured reference traffic in tests/fixtures/reference-corpus.json — records it against a purpose-built server on port 8903 (cases 43-45), and those cases replay byte for byte with the flag set.

The four defaults that come from the framework, not the application

They are on the wire, so they are part of what a compatible server produces (CONF-22):

RequestAnswer
a trailing slash on a real path (GET /health/)307 with location
a real path, wrong method (GET /reset)405 with allow: POST
HEAD or OPTIONS on any core route405 — they are ordinary wrong methods, not separate mechanisms (WART-21)
any unmatched path404 {"detail":"Not Found"}

The Task API — six routes, five of them provider-backed

Six of the sixteen routes are a discovery surface for dataset-backed environments. They are the one part of the protocol this implementation documents but declines to implement (GAP-24). Every environment this project ships answers the five provider-backed routes with 501. That is a conforming answer — the route is registered, the provider is absent (CONF-20, requirement 8.A.20) — and GET /list_environments needs no provider at all. The shapes below are what a reference environment WITH a provider does return. All were captured byte for byte from the live reference (interop/task_env.py):

RouteSuccess shapeCorpus
GET /list_environments["<task name>"] — one row; a server is one environment5, 96
GET /{env}/splits[{"name":…,"type":…}, …] — a bare array of split objects97
POST /{env}/tasks{"tasks":[…],"env_name":"<name>"} — the only route that echoes env_name98
POST /{env}/num_tasks{"num_tasks":<int>}99
POST /{env}/task{"task":{…}}100
POST /{env}/task_range{"tasks":[…]} — Python slice bounds, and no env_name101

The four POST bodies are {"split":<str>} (tasks, num_tasks), plus "index":<int> (task) or optional "start"/"stop" (task_range). A missing split is a 422 the framework raises before the handler runs (case 30).

_normalize_split types an unknown split "validation". list_splits may return bare strings; the SERVER wraps each as {"name","type"}. A name that is not one of train/validation/test is silently given type:"validation" (READ from http_server.py:1070-1080). So an environment whose splits are train, test and holdout publishes the last as {"name":"holdout","type":"validation"} — corpus case 97, the wart as bytes.

Two 404s, a 501, and an undocumented 400 — decided by order. env_name is matched case-insensitively against the REGISTERED name, not the class name GET /metadata reports (WART-15). A mismatch is the second 404: {"detail":"unknown environment '<name>'"}, cases 26-28. A match on a provider-less environment is a 501 naming the Python method: {"detail":"list_splits is not supported for this environment"}, cases 91-95. An out-of-range index on a provider env is an undocumented 400, {"detail":"Invalid task index"} (case 102, READ from http_server.py:1094-1098). That is a new row in ERRORS.md, and the only Task API status the reference's own OpenAPI document never mentions.

Provenance: captured, and the divergence is REFUSED not out-of-scope. Every shape above is in the corpus, from the live reference. The provider-less 501s and list_environments were captured against counter_env on 8901; the real dataset rows and the 400 against interop/task_env.py on 8907. Where this implementation and a provider env part — the five success shapes and the 400 — t_replay buckets it REFUSED (cases 97-102; the replay verdicts are defined in CONFORMANCE.md). The bytes are OpenEnv's own and we could emit them. But no upstream client consumes these routes, so we decline until one does. That re-open condition is named, and it lives in the GAP ledger at GAP-24.


§ 3 · The episode — WS /ws

3. The episode — WS /ws

Five client message types, four server response types. type first, data second, compact JSON, no spaces.

// client -> server                        // server -> client
{"type":"reset","data":{}}                 {"type":"observation","data":{…}}
{"type":"step","data":{<action fields>}}   {"type":"state","data":{…}}
{"type":"state"}                           {"type":"error","data":{…}}
{"type":"close"}                           {"type":"mcp","data":{…}}
{"type":"mcp","data":{<jsonrpc>}}

Three rules a plausible client gets wrong, each with a case in tests/t_client.c named after it:

  1. The action is BARE. data is the action object. The {"action":{…}} wrapping is HTTP-only. WART-16.
  2. state and close declare no data. Sending one is VALIDATION_ERROR extra_forbidden — and a rejected close does not close.
  3. {"type":"close"} gets no reply frame at all, then a Close with code 1000 and an empty reason. WART-11, CONF-18.

The envelope

Every observation is these four keys, in this order:

{"observation": {…}, "reward": 3, "done": false, "metadata": {…}}

There is no episode state machine

step before reset is legal. step after done: true is legal, repeatedly. Two resets in a row are legal. Sequencing is a client-side convention with nothing on the wire behind it. GAP-01, GAP-02.

The seven error strings

A closed set. A client branches on code, never on message.

codeExtra keys in dataSocket after
INVALID_JSON—stays open
UNKNOWN_TYPE—stays open
VALIDATION_ERRORerrors — an array of pydantic itemsstays open
EXECUTION_ERROR—stays open
CAPACITY_REACHEDactive_sessions, max_sessionscloses
FACTORY_ERRORfactory_namecloses
SESSION_ERROR—closes

Two of those have no client message to be a reply to. The reference accepts the WebSocket upgrade and only then refuses, so CAPACITY_REACHED and FACTORY_ERROR arrive as an unsolicited first frame. WART-10, CONF-17.

The message strings are fixed formats and are pinned verbatim in ../src/proto/errors.c ↗ — including "Server at capacity: %d/%d sessions active. Cannot accept new connections." and "Unknown message type: %s", whose substitution is the peer's own bytes.


§ 4 · Validation errors

4. Validation errors

A VALIDATION_ERROR's errors array, and a 422's detail array, hold pydantic items:

{"type":"missing","loc":["body","action"],"msg":"Field required","input":{}}

Eighteen type slugs occur, with exact msg strings; the table is in ../src/proto/validate.c ↗.

Validation is lax, not strict. The string "42" is a valid integer, and "x" yields the slug int_parsing. That slug is the report of a conversion that was attempted, so a strict validator cannot produce it at all. This is not an optional nicety: see PROVENANCE.md.

Whether an item carries url is decided by the CODE PATH, not by the shape of loc. This is the single most common thing to get wrong, and getting it from loc produces plausible, wrong bytes:

Originlocurl
HTTP request-body validation — missing action, no body, malformed JSON, wrong Content-Type, seed:-1prefixed "body"absent
everything else: HTTP action validation, all WebSocket validationnot prefixedpresent

FastAPI's request-body path is the only place in the stack that strips the URL. It is also the place that adds the "body" prefix. That is why the two travel together, and why exactly one call site in this implementation passes the first value. WART-22, CONF-11.


§ 5 · The stateless HTTP mirror

5. The stateless HTTP mirror

POST /reset, POST /step and GET /state cannot hold an episode. Each one constructs an environment, runs one call, and destroys it in a finally. Two identical POST /step calls return the same observation. WART-01.

$ build/rel/bin/counter --port 8931 &
$ curl -s -H 'content-type: application/json' -d '{"action":{"amount":2}}' localhost:8931/step
{"observation":{"metadata":{"steps":1},"total":2,"last_note":""},"reward":2.0,"done":false,"metadata":{"steps":1}}
$ curl -s -H 'content-type: application/json' -d '{"action":{"amount":2}}' localhost:8931/step
{"observation":{"metadata":{"steps":1},"total":2,"last_note":""},"reward":2.0,"done":false,"metadata":{"steps":1}}

The same two steps over /ws, against the same binary:

$ ./build/rel/bin/oe_probe http://127.0.0.1:8934 --episode --steps 2 --action '{"amount":2}'
<< {"type":"observation","data":{"observation":{"metadata":{},"total":0,"last_note":"reset"},"reward":null,"done":false}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":1},"total":2,"last_note":""},"reward":2.0,"done":false,"metadata":{"steps":1}}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":2},"total":4,"last_note":""},"reward":4.0,"done":true,"metadata":{"steps":2}}}
<< {"type":"state","data":{"episode_id":"ep-fixed","step_count":2,"total":4}}

2, then 4. That is the ten-second proof that HTTP cannot hold an episode, and it is why the file that serves those three routes is called http_stateless.c. Note the last line too: total is there over the WebSocket and is not in GET /state's answer. That is WART-05 on one screen.

Three more things this mirror does that the WebSocket does not:

The last one matters to users rather than implementers. It is the honest answer to can a non-Python client drive an arbitrary environment? — yes for actions and observations, no for state. GET /schema's state member is likewise hardcoded to the base model (WART-06).

Content-Type is load-bearing

Absent or non-JSON with a body → 422 model_attributes_type. No body at all → 200. The header decides whether a body was sent. WART-18.

An unhandled environment error is not JSON

500 Internal Server Error, content-type: text/plain, body Internal Server Error. A client that assumes every non-2xx is JSON breaks here. WART-19.


§ 6 · /schema — how a non-Python client learns the shape

6. /schema — how a non-Python client learns the shape

{"action": <schema>, "observation": <schema>, "state": <schema>}, each a JSON Schema object. Two things about it are worth knowing before you generate one:

The protocol owns three fields an environment author never declares: metadata on every action, and done/reward/metadata on every observation. They are injected by the framework and appear first.


§ 7 · /mcp — JSON-RPC 2.0, three framings

7. /mcp — JSON-RPC 2.0, three framings

One dialect, three wires, and two of them differ only in whitespace:

WhereFramingSeparators
POST /mcpbare JSON-RPCcompact
WS /mcpbare JSON-RPCspaced — {"jsonrpc": "2.0", …
{"type":"mcp"} on /wswrapped in the envelopecompact

WART-13. Same server, two encodings, and nothing announces which you will get.

Four methods: tools/list, tools/call, openenv/session/create, openenv/session/close. Anything else is -32601 "Method not found: <m>".

Every JSON-RPC error is HTTP 200. The status line describes the HTTP exchange; the error member describes the RPC. POST /mcp with the body {} must answer 200 with a JSON-RPC payload. That is one of the six criteria the official validator checks (CONF-06).

Four behaviours a reasonable implementer gets wrong:

The tool vocabulary, and the door rule

An environment either has a tool table or it does not, and both answers are protocol. With none, tools/list and tools/call are -32603 "Environment does not support MCP". That is the reference's own answer, and the whole answer for three of the four environments this project ships.

With one, a tool is three keys: a name, a description and an argument schema. No title, no outputSchema, no annotations, no icons, no cursor, no initialize, no session. And the schema's key is spelled differently on each door, which is the one rule here that reads as arbitrary and is not:

DoorMessagesSchema key
trainer — POST /step, {"type":"step"} on /ws{"type":"list_tools"} and {"type":"call_tool","tool_name":…,"arguments":{…}} as ordinary actions; the answer is an ordinary observationinput_schema
agent — POST /mcp, WS /mcp, {"type":"mcp"} on /wstools/list and tools/call; the answer is a JSON-RPC result, and a call's result is the tool's bare return valueinputSchema

Both spellings are the reference's own. The trainer door serialises mcp_types.Tool, which is extra="forbid" over exactly name/description/input_schema. The agent door's hand-written branch (http_server.py:945-958) writes inputSchema. It matters because OpenEnv's own LLM-facing converter reads inputSchema with no snake fallback (llm_client.py:463). Fed the trainer door's payload, it tells the model the tool takes no arguments. A client, unlike a server, must accept both — that is requirement 8.B.18.

Two more facts a tool table does not change. A tools/call that carries no name is -32602 "Missing 'name' in params" whether or not the environment has tools, because the dispatcher answers about params first (WART-27). And a name that is not in the table is -32602 "Tool not found: <name>".

What we refuse here — one library's nine-key Tool dump, its CallToolResult envelope, and the MCP specification's own lifecycle — is NOT-THE-PROTOCOL.md, with the bytes for each.


§ 8 · Bytes, exactly

8. Bytes, exactly

encodingUTF-8, raw. No \uXXXX escaping on output
readinga reader must decode \uXXXX including surrogate pairs
separatorscompact everywhere except WS /mcp
numbersreward is tagged: 0 and 7 have no .0; 7.0 and -1.5 do
floats2.0, not 2, on both transports — but the exponent is spelled differently by each. HTTP bodies are json.dumps of a dict, so CPython's repr: 1e-5 → 1e-05, 1e-6 → 1e-06. WebSocket frames are pydantic's model_dump_json, which stays in fixed notation a decade further: 1e-5 → 0.00001, 1e-6 → 1e-6. Nothing in the corpus pins this row — every captured reward is in the range where the two agree — so it rests on the two libraries' own rules, and tests/t_encoders.c asserts it. Row 4 of the divergence table in src/proto/encode.c
key orderinsertion order, everywhere. GAP-03 records that nothing says it is contractual
duplicate keysthe last member wins for a lookup. GAP-16

The RFC 6455 handshake

Standard: base64(SHA1(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11")). The server negotiates no subprotocol and sends no Sec-WebSocket-Protocol (CONF-12). Client frames are masked, server frames are not. Text frames only — a binary frame kills the session.

The container contract, in two sentences

Listen on port 8000, bound 0.0.0.0. Answer GET /health.

CONF-01, CONF-02. Exit cleanly on SIGTERM within ten seconds (CONF-23); docker stop's grace period is where that number comes from.


§ 9 · The twenty-three server requirements

The twenty-three server requirements

These are the numbered requirements CONF-nn cites. Requirement n is cited in the source at the line that satisfies it. WARTS.md is the generated index of where each one landed. Six of them — 1 through 6 — are what openenv validate --url actually checks; the rest are observable and unchecked by any official tool.

One requirement, two spellings, and both are in the source. CONF-nn marks the LINE that satisfies requirement n. MUST 8.A.n is how a comment refers to the requirement itself when it is arguing about what a peer may rely on. They are the same number: 8.A is this table, 8.B is the next one. tools/check.sh fails on a citation whose number has no row here.

#A minimal conforming OpenEnv server MUST
8.A.1Listen for HTTP/1.1 on TCP port 8000, bound to 0.0.0.0
8.A.2GET /health → 200, content-type: application/json, body exactly {"status":"healthy"}, working before and independently of environment construction
8.A.3GET /openapi.json → 200, info.version a string starting "1.", paths listing every HTTP route published
8.A.4GET /metadata → 200 with string name and description, plus nullable readme_content, version, author, documentation_url
8.A.5GET /schema → 200 with action, observation, state, each a JSON Schema object. state may be the fixed base-State schema
8.A.6POST /mcp with body {} → HTTP 200 carrying "jsonrpc":"2.0". Never 4xx for a protocol error
8.A.7Mode consistency: if /reset appears in paths, /step and /state must too; if it does not, neither may
8.A.8POST /reset accepts an absent body, {}, or {"seed":int≥0,"episode_id":str≤255,…}; returns the four-key envelope in order with metadata always present; seed < 0 → 422; non-JSON Content-Type → 422
8.A.9POST /step accepts {"action":object,"timeout_s"?:number>0,"request_id"?:string≤255,…} with the action wrapped; returns the same envelope with reward a number or null
8.A.10GET /state returns a flat object with at least episode_id (string|null) and step_count (int ≥ 0)
8.A.11Action-validation failure on /step → 422 with action-relative loc; envelope-validation failure → 422 with loc prefixed "body"
8.A.12WS /ws accepts an upgrade at exactly that path, negotiating no subprotocol, speaking text frames only
8.A.13On /ws, accept the five client types, and reject extra envelope keys with VALIDATION_ERROR
8.A.14On /ws, emit the four server types, with reward uncoerced and metadata omitted when empty
8.A.15Maintain per-connection session state: two steps in one connection observe accumulated state, and reset is not required first
8.A.16Emit only the seven WSErrorCode strings, with their declared extra keys
8.A.17Reject over capacity by accepting the upgrade first, then one CAPACITY_REACHED frame, then closing. Never fail the handshake
8.A.18On {"type":"close"}, send no reply frame and close with 1000, empty reason
8.A.19POST /mcp and WS /mcp implement the four methods; anything else → -32601. Emit {"jsonrpc","id"} then exactly one of error/result
8.A.20Register the six Task API routes. 501 is a conforming answer; env_name mismatch (case-insensitive) → the second 404
8.A.21Emit content-type: application/json on every JSON response. No CORS headers, no auth headers, no custom headers
8.A.22Starlette-compatible defaults: trailing slash → 307 with location; wrong method → 405 with allow; unknown path → 404 {"detail":"Not Found"}
8.A.23Exit cleanly on SIGTERM within 10 s

§ 10 · The twenty client requirements

The twenty client requirements

Published here because they were not published anywhere. Sixty comments in the .c and .h files of this tree cite MUST 8.B.n — in src/client/, in src/proto/client_codec.c, in tests/t_client.c, and in the INSTALLED header a stranger reads after make install. Until this section existed, a reader who followed one arrived nowhere. This is the client half of the protocol: the half a person writing an agent needs, and the half no conformance tool checks.

Nothing below is checked by openenv validate --url, which only ever talks to a server. What checks them here is tests/t_client.c, which has a case named after each of the ones this implementation can be wrong about. The code they describe is tour step 8b, src/proto/client_codec.c — a pure function with no socket in it.

And a counted artifact now stands behind these rows, the way tour/01_minimal.c ↗ stands behind the 8.A ones. tour/03_client.c ↗ (tour step 8c) is the client half hand-written with src/wire/ and nothing from src/proto/. It is 73 statements of client protocol, fenced so make lines-tour measures them. It drives the genuine Python reference to done, and it sends byte-for-byte the same client frames the library client does (interop.sh oracles 3c and 3d). So these twenty MUSTs are measured and checked, not just asserted.

#A minimal conforming OpenEnv client MUST
8.B.1Derive the WebSocket URL as rstrip("/") → scheme map (http→ws, https→wss, a bare host gets ws://) → append /ws. No query parameters, and a base URL with a path keeps it
8.B.2Poll GET {base}/health for status 200 before connecting. Do not inspect the body
8.B.3Open exactly one WebSocket to {ws_base}/ws, sending no Sec-WebSocket-Protocol, no Authorization, no cookie. OpenEnv has no authentication of any kind
8.B.4Send only masked TEXT frames (opcode 0x1, RFC 6455 §5.1) containing JSON objects. Never binary; never a non-object JSON payload, which kills the session
8.B.5Auto-reply to a server Ping with a masked Pong carrying the same payload
8.B.6Keep client→server frames under 16 MiB (uvicorn's ws_max_size)
8.B.7Operate strictly lock-step: one request frame, then block for exactly one response frame. No pipelining, and no correlation ids exist to pipeline with
8.B.8Send {"type":"step","data":{…action fields…}} — the action is the direct value of data, not wrapped under "action". That wrapping is HTTP-only
8.B.9Send {"type":"state"} and {"type":"close"} with no data key. Adding one is a VALIDATION_ERROR
8.B.10Never add extra keys to the envelope — no id, no seq, no version. All five server-side models are extra="forbid"
8.B.11Branch on data.code, not on data.message. Treat CAPACITY_REACHED, FACTORY_ERROR and SESSION_ERROR as terminal and the other four as recoverable
8.B.12Read reward and done from the top level of data, never from inside observation — the nested dump excludes both keys, so they are absent in there and a lookup hands back your own default rather than anything the server sent
8.B.13Accept reward as null, true, false, an integer or a float. A double-only field silently invents a number nobody sent
8.B.14Treat top-level metadata as optional on the WebSocket and nullable on HTTP; fall back to observation.metadata
8.B.15Tolerate unknown keys inside observation. Servers add environment-specific fields freely — that is what an observation is
8.B.16Treat any socket close as terminal and reconnect for a fresh session. There is no resume, no session id and no replay
8.B.17Send {"type":"close"} best-effort before closing, and await nothing
8.B.18If speaking /mcp: send exactly {jsonrpc, method, params?, id?} and nothing else; always give an id; never send a batch array; accept both inputSchema and input_schema in a tools/list result; expect HTTP 200 for every JSON-RPC error
8.B.19Do not assume a non-2xx HTTP response is JSON — a 500 is text/plain Internal Server Error
8.B.20Set content-type: application/json on every POST body, including {}

Three of these are where a plausible client is wrong rather than incomplete: 8.B.12, 8.B.13 and 8.B.15. ../src/client/README.md argues each one at the length it deserves.

tests/t_conform.c re-implements criteria 1–6 exactly as openenv validate --url does, and then prints the line the official suite has no equivalent of:

$ V=1 ./build/rel/tests/t_conform
  - conf_01_openapi_version_available
  - conf_02_health_endpoint
  - conf_03_metadata_endpoint
  - conf_04_schema_endpoint
  - conf_05_mcp_endpoint
  - conf_06_mode_endpoint_consistency
     validate --url: 6/6 required criteria passed, profile openenv-http/1.x
     --- beyond the official suite: the WebSocket no criterion
         opens, and the episode that exists only there ---
  - the_handshake_the_official_suite_never_performs
  - an_episode_round_trip_and_the_mirror_that_cannot_do_it
  - the_error_frame_vocabulary_a_client_switches_on
  - a_full_server_answers_101_and_then_refuses_in_a_frame
  - a_close_message_is_answered_with_silence_then_a_close_frame
  - the_two_encoders_disagree_about_one_observation
ok   t_conform: 151 checks, 0 failed

The official conformance suite never opens a WebSocket. Every criterion it checks is HTTP. The episode — the thing OpenEnv exists for — is unverified by it. That is the sharpest single fact about the state of this specification, and it is why the six checks above are followed by six more.


§ 11 · What is deliberately absent

What is deliberately absent

Half the lesson, and it has its own document: NOT-THE-PROTOCOL.md.


§ 12 · Reading on

Reading on

WARTS.mdevery reference oddity a compatible server must reproduce, with its observed bytes — generated from the source
GAPS.mdevery question this document could not answer — generated from the source
NOT-THE-PROTOCOL.mdevery refusal, with the reference's bytes for each
PROVENANCE.mdhow all of the above was derived, and the fifteen oracles that grade it
TOUR.mdthe reading path through the implementation
../src/proto/types.h ↗this document as a header, and the place it is enforced