miniopenenv

src/wire/README.md → html

src/wire/ — the plumbing does not know what it is carrying

grep -riE 'openenv|observations?|rewards?|episodes?|jsonrpc' src/wire --include='*.[ch]'
make check     # rule 5, "wire/ knows no application vocabulary"

The first command prints nothing. (--include is not a technicality. This README has to spell the banned words in order to explain the ban, and tools/check.sh scans .c and .h files for exactly that reason.)

This is the load-bearing claim of the whole repository. Everybody says their code is layered. The claim here is that the layering is decided by a program, not by a reviewer's memory. It is checked in two tiers, because some words are genuinely generic:

Getting that distinction right is the difference between a check that is an index and a check people learn to work around.

The circumlocutions in these files are a consequence of the rule, not coyness. wire/json.h describes a field whose type is null | bool | int | float without naming it, because naming it would be a violation. When you meet a sentence that seems to be talking around something, that is what is happening, and the thing being talked around is one layer up in src/proto/.

§ 1 · The order to read the twenty-seven files in

The order to read the twenty-seven files in

Not alphabetical, not the compiler's. This one:

FileWhy here
1limits.hEvery hard cap with its reason. Read it before anything that uses one
2err.hFourteen values, one screen, and the only control-flow macro in the project
3arena.hThe memory model, and the three antidotes to the bug it creates
4str.h, buf.hThe only string type below the application layer, and the only output buffer
5bytes.hOverflow-checked arithmetic on numbers a peer chose
6json.h3 is not 3.0, the grammar, and the three encoders the reference has
7json_parse.cRFC 8259 by recursive descent. The grammar is six functions, in order
8json.c, json_write.h, json_write.cReading a tree; writing one, including the shortest-round-trip double
9utf8.hWhy validation is incremental — a character can span two frames
10http.hTHE SMUGGLING RULES, which are the whole reason this parser is small
11sha1.h, base64.hTwo RFC primitives the handshake needs and nothing else uses
12ws.h, ws.cRFC 6455. validate_frame is the file; everything else is bookkeeping
13net.hThe operating system, wrapped. The only file below with a #ifdef in it
§ 2 · What is not here

What is not here

No event loop, no connection object, no session, no route table, no configuration, and no logging. Those are policy, and policy lives one layer up. Nothing in this directory reads or writes a descriptor except net.c.