miniopenenv

docs/ → index

The documentation

Every document in the repository, rendered from the file of the same name. Three of them are generated from the source by make docs, and make check fails the build when they go stale — so those three cannot drift from the code they index.

18 documents · 11 directory notes · 3 generated by make docs

docs/TOUR.md — sixteen steps, about an hour

Sixteen numbered steps — twenty-two stops, counting 6b, 7b, 7c, 8b, 8c and 13b — about an hour. Steps 1–7 are the complete answer to "what is OpenEnv"; everything after them is how a server that has to survive strangers is built underneath it.

Step one of the tour is this repository's README, and the whole of it is here.

§ 1 · THE PROTOCOL

The protocol

docs/PROTOCOL.mdour statement of the protocol. The sixteen routes, the five and four message types, the envelope, the seven error strings
docs/NOT-THE-PROTOCOL.mdwhat a conforming OpenEnv implementation does not have to do, with the reference's own captured bytes beside each claim
docs/WARTS.md generatedevery WART-nn with its four lines verbatim, plus the CONF-nn citations — twenty-five of them, covering the twenty-three numbered server requirements
docs/GAPS.md generatedevery GAP-nn with its three lines verbatim — the places where the protocol turns out not to exist
docs/BOUNDARY.md generatedevery [WIRE]/[SDK]/[POLICY] tag with its symbol and site, then every SAFETY: line. Two boundaries, one index

Those five are one subject from five sides, and every one of them carries a rail to the other four: what it is, what it is not, where the reference is an accident, where the protocol is silent, and which names are protocol and which are ours.

§ 2 · THE MODELS, ONCE EACH

The models, once each

docs/MEMORY.mdthe arena model, the one rule an author carries, and the three antidotes to the hazard it creates
docs/ERRORS.mdone flat enum, why none of its names ever reaches a peer, and the collapse onto what one does
docs/SECURITY.mdthe threat model, every cap and why that number, and two limits that were wrong
docs/PORTING.mdthe one file with platform conditionals in it, and what a port has to keep true
§ 3 · SHIPPING IT, AND BREAKING IT

Shipping it, and breaking it

docs/PACKAGING.mdinstall, pkg-config, vendoring, embedding, and the container
docs/FUZZING.mdthe six fuzz targets, their invariant oracles, and Autobahn case by case
docs/TRAINING.mdhow to train a small language model on the arcade's environments jointly, with rewards the environments themselves compute
arcade/MATH.mdEight small environments turn mathematics into ordinary text, then grade the answer with ordinary code.
§ 4 · THE EVIDENCE

The evidence

docs/PROVENANCE.mdNo upstream code is vendored in this repository. Not a line. That is the first thing to establish, because it is the thing that makes everything else here worth reading
docs/evidence/OBSERVED-WIRE.mdcaptured traffic, byte for byte
docs/evidence/REFERENCE-NOTES.mdwhere each measured constant came from
docs/CONFORMANCE.mdthe machine-readable verdict for every exchange in the captured reference corpus
§ 5 · THE DIRECTORIES

The directories

Each of these is a directory's own README, and each opens with a claim you can check with one command.

src/README.mdthe layers, and the line the whole repository is about
src/wire/README.mdthe plumbing does not know what it is carrying
src/proto/README.mdthe protocol, and no way to reach a socket from here
src/server/README.mdhosting the protocol
src/client/README.mddriving the protocol from the other end
envs/README.mdwhat an environment author actually writes
arcade/README.mdgames, synthesis tasks, and text-first mathematics
examples/README.mdthe other end of the socket
tests/README.mdread them; they are the specification
tests/embed/README.mdcan a stranger consume this?
tour/README.mdthe protocol, hand-written, from both chairs