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.
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.
| Claim | Check it yourself |
|---|---|
wire/ has never heard of OpenEnv | grep -riE 'openenv|observation|reward|episode' src/wire --include='*.[ch]' returns nothing — rule 5 |
proto/ makes no system call, and only wire/arena.c allocates | grep -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 headers | rule 9 compares them value for value |
What lives where
wire/— arena, buffers, slices, UTF-8, JSON, SHA-1, base64, sockets, HTTP/1.1, RFC 6455. Generic plumbing. A project that has never heard of this protocol could vendor this directory. Seesrc/wire/README.md.proto/— the message vocabulary, the two encoders, the routing table. This is the layer the project exists to make visible, and it contains no syscall: it is a pure function from one JSON frame to one JSON frame.server/,client/— loops, descriptors, timeouts. Policy. Everything here is a choice about when to callproto/, never about what it means.
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.
Where to go from here
wire/README.md | the plumbing, and the order to read twenty-seven files in |
proto/README.md | the protocol, and the order to read eleven pairs in |
server/README.md | hosting it: the seam that makes no syscall, and the loop that does |
client/README.md | driving it, and three rules a plausible client gets wrong |
../docs/PROTOCOL.md | what proto/ is an implementation of |
../docs/TOUR.md | the reader's order through all of it |