src/proto/ — the protocol, and no way to reach a socket from here
grep -rnE '#include <(sys/|unistd|poll|signal|netinet|arpa|fcntl|time|stdio|stdlib)' src/proto
make check # rule 14, "src/proto/ makes no syscall"
The first command prints nothing.
Every byte a non-C client will ever see is produced in this directory, and nothing else in this repository touches the wire. That is one claim with two halves, and each half is checked by a different rule:
src/wire/knows no application vocabulary (rule 5), so it cannot decide what any byte means.src/proto/makes no syscall, reads no clock, opens no file, calls no allocator and owns no writable file-scope memory (rule 14), so it cannot decide when any byte moves.
What is left in the middle is a pure function from one JSON frame to one JSON
frame. That is not a metaphor about the design. It is the reason
tests/t_replay.c can push the entire captured reference corpus through this
code in about a millisecond, with no socket, no port, no Python and no
network. Measured, not estimated: a hundred consecutive replays of all
one hundred and three cases take 0.12 s of wall clock. And it is why the
replay runs on every commit for every contributor, instead of ceremonially,
once, before a release.
The purity rule is also what makes the protocol embeddable. A caller who already owns a main loop, an event framework, or a transport we have never heard of gets the protocol without inheriting our I/O.
Marker polarity
Everything in this directory is protocol unless a marker says otherwise.
That is the opposite polarity from src/wire/, and it is what keeps grep an
index rather than a haystack:
| Marker | Means |
|---|---|
WART-##: | the reference does this odd thing and we reproduce it — four lines: claim / reference / observed / honoured-by |
GAP-##: | nobody specified this and we chose — three lines: unspecified / we chose / a different implementer might |
CONF-##: | this line satisfies numbered server MUST N — one line |
SAFETY: | this check exists because the input is hostile — one line |
POLICY: | this is our free choice and yours to change |
An unmarked line in this directory is a line that reproduces the protocol because the protocol says so.
make docs turns those markers into three documents, and make check refuses
to let them go stale. docs/WARTS.md prints every
WART- body verbatim beside the twenty-three CONF- citations;
docs/GAPS.md prints every GAP-; and
docs/BOUNDARY.md prints the tags and then every
SAFETY: line. The index cannot lie about the code, because it is derived from
it.
Boundary tags
Declarations here carry [WIRE], [SDK] or [POLICY] for the same reason the
installed headers do: the whole point of this project is that "built on the
protocol" and "built into the protocol" are distinguishable by looking, and
in this directory in particular almost everything is [WIRE] — so the few
things that are not are worth being able to find. The generated index is
docs/BOUNDARY.md.
The reading order
| File | The question it answers | |
|---|---|---|
| 1 | types.h | What is OpenEnv? Five client messages, four server responses, seven error strings, four envelope keys. |
| 2 | routes.h / routes.c | Which paths exist, in which order, and which of them are published. |
| 3 | encode.h / encode.c | What a server says. Two observation encoders, two state encoders, one frame envelope, and two more encoder pairs for the two observations an MCP-style step answers with — and the divergence table between the two halves of every pair, which is the file's reason for existing. |
| 4 | errors.h / errors.c | What a server says when it cannot. Two mapping tables from our fourteen internal failures onto the two vocabularies a peer understands, the seven WSErrorCode strings with their exact message formats, and the one site that decides whether an error item carries a url. |
| 5 | schema.h / schema.c | What a server's types look like: GET /schema, generated from the one const field table that is this project's whole substitute for Pydantic. Two key-ordering regimes in one object, and the three protocol-owned fields an author never declares. |
| 6 | validate.h / validate.c | What a server refuses, and why the string "42" is an integer. The eighteen pydantic slugs with their exact messages, and the lax coercion the corpus makes mandatory — int_parsing is the report of a conversion that was attempted, so a strict validator can neither emit it nor replay the corpus. |
| 7 | decode.h / decode.c | What a server reads, and in what order it asks. Five client message types, two HTTP request models, four numbered steps whose ORDER is observable — {"type":"bogus","extra":1} is UNKNOWN_TYPE and not VALIDATION_ERROR, because the reference reads type one line above the try block that validates — and one more question, asked of the action itself by both step doors: is this a tool action? |
| 8 | jsonrpc.h / jsonrpc.c | What /mcp is: JSON-RPC 2.0 with four methods, six codes and three framings of one dialect — two of which differ only in the spaces after : and ,. It answers tools/list from the const table, hands tools/call back to whoever owns a live environment, and spells every sentence either one can be refused with. Also the file where a Python exception's str() is reproduced in C, because -32600 carries one and the corpus pins three of them. |
| 9 | openapi.h / openapi.c | What a validator reads: the route table, walked once, into the smallest well-formed OpenAPI 3.1 document that answers the two questions anything has ever been observed to ask of it. Thirteen paths for sixteen routes, and which three are missing is a fact about OpenAPI. |
| — | value.c | Not protocol, and the only file here with no wire byte in it at all. It implements section 3 of <openenv/openenv.h> — the value API an environment author writes — over src/wire/json.h. It is in this directory for a mechanical reason stated in its banner: src/wire/ may not name this project even in an #include line, and these declarations live in the installed header. Every one of them is tagged [SDK]. |
| — | tool.h / tool.c | The same idea for the other const table: section 9 of <openenv/openenv.h>, which is a tool. Five ToolErrorType strings, the seven setters that put one JSON value into a tool's answer over a result the host pre-creates so that an author never names an arena, the table lookup, and the three-key row both doors publish — name, description, and the argument schema under input_schema or inputSchema. The row is here rather than in either door because it is the same shape on both and only the third key's spelling differs; the ENVELOPE around it is jsonrpc.c's result or encode.c's observation, and neither of those is decided here. |
That is the whole directory — eleven header/source pairs, types.h, which has
no source, and value.c, which has no header. docs/TOUR.md is the reader's
path through the repository; docs/PROTOCOL.md is what this directory is an
implementation of.