miniopenenv

src/proto/README.md → html

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:

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.

§ 1 · Marker polarity

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:

MarkerMeans
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.

§ 2 · Boundary tags

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.

§ 3 · The reading order

The reading order

FileThe question it answers
1types.hWhat is OpenEnv? Five client messages, four server responses, seven error strings, four envelope keys.
2routes.h / routes.cWhich paths exist, in which order, and which of them are published.
3encode.h / encode.cWhat 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.
4errors.h / errors.cWhat 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.
5schema.h / schema.cWhat 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.
6validate.h / validate.cWhat 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.
7decode.h / decode.cWhat 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?
8jsonrpc.h / jsonrpc.cWhat /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.
9openapi.h / openapi.cWhat 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.cNot 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.cThe 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.