miniopenenv

src/README.md → html

src/ — the layers, and the line the whole repository is about

Reading order is the reverse of build order. The compiler needs the bottom first; you do not. Start at tour/01_minimal.c, then read src/proto/, and come down to src/wire/ only when you want to know what the RFCs cost.

                      wire/          bytes. Knows no application vocabulary.
                        ^
                        |
                     proto/          THE PROTOCOL. Makes no system call.
                      ^     ^
                      |     |
                 server/   client/   I/O. The only layers that touch a socket.
§ 1 · Three claims, each with the command that decides it

Three claims, each with the command that decides it

Every one of these is checked by make check (tools/check.sh). They are claims and not aspirations precisely because a machine, not a reviewer, decides them.

ClaimCheck it yourself
wire/ has never heard of OpenEnvgrep -riE 'openenv|observation|reward|episode' src/wire --include='*.[ch]' returns nothing — rule 5
proto/ makes no system call, and only wire/arena.c allocatesgrep -rnE '(^|[^A-Za-z0-9_])(malloc|calloc|realloc|free)\(' src shows one file — rule 3. The leading boundary is load-bearing: without it the pattern also matches oe_arena_free( and oe_session_free( and prints seven
the error enum cannot drift between the internal and installed headersrule 9 compares them value for value
§ 2 · What lives where

What lives where

§ 3 · Two conventions worth knowing before you open a file

Two conventions worth knowing before you open a file

OE_TRY(expr) is a wire/ dialect. In the codecs the error checks outnumber the logic and explicit ifs bury the grammar. Above the wire layer every branch is protocol semantics, and hiding a branch in a macro hides the lesson — so the macro is banned there, and rule 4 enforces it.

Every public declaration carries a [WIRE] / [SDK] / [POLICY] tag. That tag is the direct answer to the question this project was commissioned to answer: which of this is the protocol, and which of it is somebody's decision about the protocol. make docs turns the tags and the four sparse markers into docs/BOUNDARY.md, docs/WARTS.md and docs/GAPS.md, and make check fails the build when any of the three goes stale. So the index cannot lie about the code, because it is derived from it.

§ 4 · Where to go from here

Where to go from here

wire/README.mdthe plumbing, and the order to read twenty-seven files in
proto/README.mdthe protocol, and the order to read eleven pairs in
server/README.mdhosting it: the seam that makes no syscall, and the loop that does
client/README.mddriving it, and three rules a plausible client gets wrong
../docs/PROTOCOL.mdwhat proto/ is an implementation of
../docs/TOUR.mdthe reader's order through all of it