miniopenenv

docs/evidence/OBSERVED-WIRE.md → html

Observed wire traffic

This file holds the exchanges that are probed rather than captured: questions put to a running reference server that the corpus does not answer. The corpus is the machine-readable capture the tests actually assert against — ../../tests/fixtures/reference-corpus.json ↗, 103 byte-exact cases from the reference server. Test files cite it by case number (corpus case 30), and tests/t_http.c, tests/t_ws.c and tests/t_json_write.c each name the cases they pin. ../PROVENANCE.md is how it was made and how it is used.

../PROVENANCE.md explains why the probed/captured distinction matters. A wart (../WARTS.md) backed by captured bytes is a fact about the protocol. A wart backed by a probe is a fact about one implementation of it. And a third implementer deserves to know which they are reading.

Provenance for everything below: openenv at 60ecc7b7d6ecf830448aa9fbf330e3c7cecbc542, with fastapi 0.140.0, pydantic 2.13.4, starlette 1.3.1, uvicorn 0.51.0, on CPython 3.13.7. The server probed was interop/probe_env.py — the Python environment envs/counter.c is a literal port of.


§ 1 · There is no episode state machine

There is no episode state machine

The probes behind GAP-01 and GAP-02, on one WebSocket connection, in this order: a step before any reset, two more steps to reach done, two more steps after done, then two resets in a row.

The genuine reference server, uvicorn probe_env:app:

>> {"type":"step","data":{"amount":1,"note":"before-any-reset"}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":1},"total":1,"last_note":"before-any-reset"},"reward":1.0,"done":false,"metadata":{"steps":1}}}
>> {"type":"step","data":{"amount":1,"note":"b"}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":2},"total":2,"last_note":"b"},"reward":2.0,"done":false,"metadata":{"steps":2}}}
>> {"type":"step","data":{"amount":1,"note":"c"}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":3},"total":3,"last_note":"c"},"reward":3.0,"done":true,"metadata":{"steps":3}}}
>> {"type":"step","data":{"amount":1,"note":"after-done-1"}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":4},"total":4,"last_note":"after-done-1"},"reward":4.0,"done":true,"metadata":{"steps":4}}}
>> {"type":"step","data":{"amount":1,"note":"after-done-2"}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":5},"total":5,"last_note":"after-done-2"},"reward":5.0,"done":true,"metadata":{"steps":5}}}
>> {"type":"reset","data":{}}
<< {"type":"observation","data":{"observation":{"metadata":{},"total":0,"last_note":"reset"},"reward":null,"done":false}}
>> {"type":"reset","data":{}}
<< {"type":"observation","data":{"observation":{"metadata":{},"total":0,"last_note":"reset"},"reward":null,"done":false}}

./build/rel/bin/counter, the same seven messages:

<< {"type":"observation","data":{"observation":{"metadata":{"steps":1},"total":1,"last_note":"before-any-reset"},"reward":1.0,"done":false,"metadata":{"steps":1}}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":2},"total":2,"last_note":"b"},"reward":2.0,"done":false,"metadata":{"steps":2}}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":3},"total":3,"last_note":"c"},"reward":3.0,"done":true,"metadata":{"steps":3}}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":4},"total":4,"last_note":"after-done-1"},"reward":4.0,"done":true,"metadata":{"steps":4}}}
<< {"type":"observation","data":{"observation":{"metadata":{"steps":5},"total":5,"last_note":"after-done-2"},"reward":5.0,"done":true,"metadata":{"steps":5}}}
<< {"type":"observation","data":{"observation":{"metadata":{},"total":0,"last_note":"reset"},"reward":null,"done":false}}
<< {"type":"observation","data":{"observation":{"metadata":{},"total":0,"last_note":"reset"},"reward":null,"done":false}}

Byte for byte identical. Four facts fall out of it:

ProbeResult
step before any resetaccepted. An ordinary observation, total 1
step after done:trueaccepted, repeatedly. done stays true and the environment keeps mutating
a second resetaccepted; state re-initialised
doneis a field on an observation, and nothing in the protocol reads it

There is no episode state machine on the wire. Any sequencing discipline lives in the client, by convention. That is a protocol gap and not a subtlety, and it is why struct oe_session in src/server/session.c has no phase field: inventing one would reject traffic a conforming server accepts, including traffic in the corpus.

The corpus pins the first of the four on its own — case 59, ws: step before reset (LEGAL - no episode state machine). The other three are why this section exists.


§ 2 · The other probed facts, and where each is argued

The other probed facts, and where each is argued

Each of these is a [probed] citation in the source rather than a corpus case, and each is argued at the line it decides:

FactWhere
the two transports disagree about reward's JSON typeWART-03; envs/rewards.c is that probe as a program
a non-minimal RFC 6455 length is accepted by the referencesrc/wire/ws.c rule 4, with the exact header bytes
the reference's close-frame reason strings, all tenthe table above validate_frame in src/wire/ws.c
a WebSocket version mismatch is 400 text/plain, not 426src/wire/ws.h, at oe_ws_server_write_refusal
integers wider than int64_t, in three bandssrc/proto/validate.c, at the conversion
the reference pings at 20 s and drops at 40 ssrc/client/README.md, and OE_WS_IDLE_MS in src/wire/limits.h
where our frame cap bites a real client — 100 KB accepted, 300 KB closestools/interop.sh oracle 2c, which re-measures it on every run
§ 3 · See also

See also