miniopenenv

docs/WARTS.md → html

The warts, and the conformance citations

GENERATED by tools/gendocs.sh. Do not edit this file; edit the markers in the source and run make docs.

A wart is a place where the reference implementation does something no designer would have chosen, it is visible on the wire, and a compatible server therefore has to do it too. Each one is annotated at the line of ours that reproduces it, in a fixed four-line form:

LineSays
claim:what a reasonable implementer would assume, stated so it can be contradicted
reference:where in the reference the behaviour comes from
observed:the bytes. Not an argument — a recording
honoured-by:the code below the marker, and its twin if it has one

A wart states a fact and never a judgement. The observed: line supplies the justification implicitly: a real client sees these bytes, therefore we emit them. That is how twenty-eight of them avoid reading as twenty-eight apologies.

A conformance citation (CONF-nn) is one line naming the numbered server requirement a piece of code satisfies. The numbering is not ours: CONF-nn is requirement n of the twenty-three in the server conformance checklist reproduced in PROTOCOL.md. tests/t_conform.c re-implements six of them as the official validator does, and prints where the official suite stops.

A HOLE IN THE NUMBERING IS AN ANSWER, NOT A QUESTION. Every number from 1 to the highest in use has a section below; one with no site says whether it was retired and why, or was never placed. A reader who wonders what happened to a number gets told.

Related: GAPS.md is the opposite category — places where the protocol turns out not to exist. NOT-THE-PROTOCOL.md is what we refuse to implement at all.

§ 1 · WART- — the reference does this odd thing and we reproduce it

WART- — the reference does this odd thing and we reproduce it

WART-01

Declared at src/server/http_stateless.c:4 ↗:

WART-01: these three endpoints cannot hold an episode.
claim:       /reset starts an episode and /step advances it, because that is
             what the names mean and what every RL API does.
reference:   each handler runs `env = self._env_factory()` and then
             `finally: env.close()`, so the instance that served the request
             is destroyed before the response is written.
observed:    three identical POST /step calls with {"amount":2} against the
             counter environment return `"total":2` three times, and the
             nested metadata reads `{"steps":1}` every time. Over WS /ws the
             same two steps reach 2 and then 7.
honoured-by: `with_env` below, which constructs and destroys inside one call,
             and by this file having no session type in it at all. WS /ws is
             not the preferred transport for an episode; it is the only one.

WHERE THE INTERESTING PART IS. `with_env` is four lines and is the wart.
Everything else is the HTTP side of a divergence that has its own comment in
src/proto/encode.c: this file calls oe__encode_obs_http and
oe__encode_state_http, and src/server/session.c calls the other two.

Also referred to from: include/openenv/embed.h:212 src/server/handlers.h:57 src/server/handlers.h:91 src/server/http_stateless.c:201 src/server/mcp.c:83

WART-02

Declared at src/proto/encode.c:79 ↗:

WART-02: the metadata object reaches the wire twice in one body.
claim:       a value that a model holds once is encoded once.
reference:   the nested copy is the base Observation's own `metadata` field,
             dumped alongside the subclass's fields; the hoisted copy is
             attached separately by serialization.py:173 under `if
             metadata:`. One Python attribute, two writers, neither aware of
             the other.
observed:    POST /step -> {"observation":{"metadata":{"steps":1},"total":2,
             "last_note":"hi"},"reward":2.0,"done":false,
             "metadata":{"steps":1}} (corpus case 18), and the same
             duplication inside the WebSocket envelope (corpus case 56,
             frame 2).
honoured-by: write_observation_member below, which always writes the nested
             copy, and the two hoisted branches, which both consult this
             predicate. A client may read either; MUST 8.B.14 says so.

Also referred to from: src/proto/client_codec.c:207

WART-03

Declared at include/openenv/openenv.h:257 ↗:

WART-03: one wire field, four JSON types, and the two transports disagree.
claim:       a reward is a number.
reference:   src/openenv/core/env_server/serialization.py:137-175 (WS) vs
             http_server.py's float() coercion (HTTP).
observed:    WS   {"observation":{...},"reward":true,"done":false}
             WS   {"observation":{...},"reward":3,"done":true}
             HTTP {"observation":{...},"reward":1.0,"done":false,"metadata":null}
honoured-by: this tagged union, and the two encoders in src/proto/encode.c
             that read it, which share no body.

A double-only field loses both `true` and `3`; it would also silently turn
every integer reward into `x.0` on a transport that does not do that.

Declared at src/proto/encode.c:196 ↗:

WART-03: the reward is coerced to a float on its way out over HTTP.
claim:       an encoder is a function of the value, so one value has one
             encoding.
reference:   StepResponse.reward is Optional[float] (types.py:162) while
             Observation.reward is bool | int | float | None (types.py:82),
             so the response model re-types the field the environment set.
observed:    an environment returning True yields "reward":1.0 and one
             returning 3 yields "reward":3.0
             (docs/evidence/REFERENCE-NOTES.md section 3.3, [probed]).
honoured-by: this function, which reaches for oe_jw_real in three of four
             arms, against oe__encode_obs_ws, which reaches for a different
             writer in each.

The coercion is float(), not a cast: True becomes 1.0 and not 1. And None is
not coerced at all, because Optional[float] admits it — so `null` survives on
both transports and is the one arm where nothing happens.

Also referred to from: envs/rewards.c:22 examples/oe_probe.c:1004 examples/oe_probe.c:994 examples/oe_probe.c:999 src/proto/client_codec.c:153 src/proto/encode.c:292 src/proto/schema.c:386 src/proto/types.h:131

WART-04

Declared at src/proto/encode.c:246 ↗:

WART-04: the key is always here, and its value is null when the metadata
is empty.
claim:       an empty collection and an absent one encode the same way on
             both transports.
reference:   ResetResponse and StepResponse dump all four of their fields
             unconditionally, so the key exists even when there is
             nothing in it; the WebSocket path attaches it only
             `if metadata:` (serialization.py:173).
observed:    HTTP {"observation":{"metadata":{},...},"reward":null,
                   "done":false,"metadata":null}    (corpus case 12)
             WS   {"observation":{"metadata":{},...},"reward":null,
                   "done":false}                    (corpus case 48/1)
honoured-by: this branch and its absence in oe__encode_obs_ws.

And `null` rather than `{}`, because the same `if metadata:` runs on
this path too: an empty dict is never handed to the response model, so
the model dumps its own declared default, which is None.

Also referred to from: examples/oe_probe.c:215 src/proto/encode.c:307 src/proto/encode.c:711 src/proto/encode.c:739 src/proto/encode.h:185

WART-05

Declared at src/proto/encode.c:458 ↗:

WART-05: GET /state describes the base State and never the environment.
claim:       the state endpoint reports the environment's state.
reference:   http_server.py:1389-1392 registers the route with
             response_model=State, so FastAPI re-serialises the returned
             object through the base model and a subclass field has nowhere
             to go.
observed:    GET /state -> {"episode_id":null,"step_count":0} with no
             `total` (corpus case 3). A freshly constructed counter
             environment has total = 0, not absent, so the key was DROPPED
             rather than merely unset — and the WebSocket `state` frame for
             the same environment carries it:
             {"episode_id":"ep-fixed","step_count":2,"total":6} (case 48,
             frame 4). REFERENCE-NOTES.md section 3.5 [probed] the general
             case with four fields and lost two of them.
honoured-by: this function, which is write_base_state and then a closing
             brace — the loop that oe__encode_state_ws has is exactly what
             is missing here.

Declared at src/server/http_stateless.c:360 ↗:

WART-05: this answer is truncated to the base State and the WebSocket's is
not.
claim:       /state describes the environment's state.
reference:   the route declares `State` as its response_model, and FastAPI
             serialises through the DECLARED model, so every field the base
             class did not declare is dropped — including the ones the
             environment's own State subclass exists to carry.
observed:    {"episode_id":null,"step_count":0} from an environment whose
             state object also holds `total`, against the WebSocket's
             {"episode_id":"ep-fixed","step_count":2,"total":6}.
honoured-by: oe__encode_state_http, called one line below, against
             oe__encode_state_ws in src/server/session.c. Together with the
             hardcoded base-State schema at GET /schema this is why a
             non-Python client can drive an arbitrary environment's actions
             and observations but not read its state.

Declared at src/server/session.c:472 ↗:

WART-05: this transport shows the WHOLE state and GET /state shows two keys.
claim:       one state object, one rendering of it.
reference:   the WebSocket handler calls model_dump() on the environment's
             State subclass, while the HTTP route declares `State` as its
             response model and FastAPI drops every field the base class did
             not declare.
observed:    WS   {"type":"state","data":{"episode_id":"ep-fixed",
                   "step_count":2,"total":6}}
             HTTP {"episode_id":null,"step_count":0}
honoured-by: this call to oe__encode_state_ws against the
             oe__encode_state_http one screen away in http_stateless.c. Six
             lines of difference, and it is why the README can say: can a
             non-Python client drive an arbitrary environment? Yes for
             actions and observations, no for state.

Also referred to from: envs/counter.c:137 envs/echo.c:87 examples/oe_probe.c:1053 include/openenv/openenv.h:734 src/client/client.c:1457 src/proto/client_codec.c:308 src/proto/encode.c:321 src/proto/schema.c:797 tour/02_conformant.c:195 tour/03_client.c:606

WART-06

Declared at src/proto/schema.c:784 ↗:

WART-06: /schema `state` describes the base State and never the environment.
claim:       an endpoint that publishes an environment's schemas publishes
             the schema of that environment's state.
reference:   http_server.py:1451 builds SchemaResponse with
             `state=State.model_json_schema()` — the base class, named
             literally, with no reference to the environment's own State
             subclass anywhere in the expression.
observed:    corpus case 2's `state` is the object below, byte for byte,
             from an environment whose CounterState declares `total: int`.
             The key is absent, not null: it was never described.
honoured-by: this function, which takes no environment argument at all — the
             cheapest possible proof that it cannot depend on one.

Together with WART-05 (GET /state drops subclass fields on the way out) this
is the README's answer to "can a non-C client drive an arbitrary
environment?": yes for actions and observations, no for state. State is
neither discoverable here nor fully readable there; only WS `{"type":"state"}`
returns it, and nothing tells a client what it will contain.

The description is the base class's docstring, which pydantic copies into the
schema — including the blank line between its two paragraphs, which is why
there is a `\n\n` in it.

Also referred to from: src/proto/schema.h:254

WART-07

Declared at src/server/http_const.c:121 ↗:

WART-07: `name` is the environment CLASS's name, not the manifest's.
claim:       an environment has a name, and /metadata reports it.
reference:   the default metadata implementation fills `name` from
             `type(self).__name__` and `description` from
             f"{name} environment", so the manifest name never reaches
             this endpoint.
observed:    a server registered as `counter_env` answers
             {"name":"CounterEnvironment","description":"CounterEnvironment
             environment",...} while GET /list_environments answers
             ["counter_env"].
honoured-by: this key reading oe_env.name while the Task API below reads
             oe_env.task_env_name. Two members, because they are two
             facts.

Also referred to from: envs/counter.c:159 envs/echo.c:96 envs/echo_tools.c:333 src/server/http_const.c:531 tour/02_conformant.c:216

WART-08

Declared at envs/echo.c:67 ↗:

WART-08: a reset over the WebSocket carries no validation at all, so
`params` is whatever the peer sent. This environment reads none of it.

Declared at envs/echo_tools.c:270 ↗:

WART-08: a reset over the WebSocket carries no validation at all, so
`params` is whatever the peer sent. This environment reads none of it —
the reference's `seed` is unused there too.

Declared at src/proto/decode.c:239 ↗:

WART-08: a reset over the WebSocket is not validated at all.
claim:       one protocol, one set of rules for its arguments.
reference:   the WebSocket handler forwards message.data as reset()
             kwargs; only FastAPI's ResetRequest declares `seed` with
             ge=0, and no ResetRequest exists on this path.
observed:    corpus 52 sends {"type":"reset","data":{"seed":-1}} and
             gets a 200-equivalent observation frame; corpus 53 sends
             {"seed":"abc"} and gets the same. The identical values
             over POST /reset are corpus 17's 422.
honoured-by: this arm, which checks the SHAPE of `data` and nothing
             inside it, beside oe__decode_reset_http, which checks
             both.

Declared at src/server/session.c:259 ↗:

WART-08: a reset over the WebSocket is not validated.
claim:       one protocol, one set of rules for the arguments of a call.
reference:   the WebSocket handler forwards `message.data` as reset()
             keyword arguments; the `seed >= 0` bound lives on FastAPI's
             ResetRequest, and no ResetRequest exists on this path.
observed:    corpus 52 sends {"type":"reset","data":{"seed":-1}} and gets an
             observation frame; the same value over POST /reset is corpus
             17's 422 `greater_than_equal`.
honoured-by: this function, which hands `data` to the environment untouched.
             The HTTP twin is oe__decode_reset_http, which checks both.

Also referred to from: envs/counter.c:35 src/proto/client_codec.h:70 src/proto/decode.h:207 tour/02_conformant.c:156

WART-09

Declared at src/proto/schema.c:65 ↗:

WART-09: one document, two key-ordering regimes.
claim:       a generated document has one ordering rule, whatever it is.
reference:   pydantic's JSON-Schema generator sorts the KEYWORDS of a schema
             object and preserves the DECLARATION ORDER of a model's fields,
             because the two come from different places — a fixed keyword set
             it owns, and a member list the author wrote. Neither half is
             wrong; they simply never met.
observed:    GET /schema (corpus case 2) contains
             {"additionalProperties":false,"properties":{...},"title":
             "CounterAction","type":"object"} — a, p, t, t, ASCII order —
             whose `properties` reads
             {"metadata":{...},"amount":{...},"note":{...}}, which is
             declaration order and is not sorted by anything.
honoured-by: this file's two halves. The straight line of keyword writes in
             every function below IS the sort, and the single `properties`
             loop is the regime that does not sort. No proposal in the design
             phase noticed the split; fixture 2 is what settled it.

Also referred to from: envs/echo_tools.c:105

WART-10

Declared at src/proto/errors.c:186 ↗:

WART-10: the upgrade is ACCEPTED and only then refused.
claim:       a server at capacity refuses the connection.
reference:   http_server.py:1494 accepts the WebSocket, :1501 creates
             the session; the capacity test is after the accept.
observed:    HTTP 101, then one frame
             {"type":"error","data":{"message":"Server at capacity: 2/2
             sessions active. Cannot accept new connections.",
             "code":"CAPACITY_REACHED","active_sessions":2,
             "max_sessions":2}}, then close.
honoured-by: this row plus oe_session_open(), which returns a greeting
             frame — the one frame in the protocol with no client frame
             in front of it.
The two numbers appear twice, in the message and as their own keys, so
they are two ints in the frame struct rather than a caller-formatted
string: one fact cannot then be spelled two ways.

Declared at src/server/session.c:124 ↗:

WART-10: the upgrade is ACCEPTED and then refused.
claim:       a server that cannot serve a connection declines the
             handshake, which is what HTTP status codes are for.
reference:   the WebSocket handler calls websocket.accept() before it
             consults the session table, so the capacity test happens
             after the peer is already speaking RFC 6455.
observed:    HTTP/1.1 101 Switching Protocols, then one text frame
             {"type":"error","data":{"message":"Server at capacity: 8/8
             sessions active. Cannot accept new connections.","code":
             "CAPACITY_REACHED","active_sessions":8,"max_sessions":8}},
             then close.
honoured-by: this function existing at all. A design with only
             oe_session_frame could not emit a frame that answers no
             client message.

Also referred to from: src/server/conn.c:7 src/server/conn.c:745 src/server/conn.c:869 src/server/conn.h:87

WART-11

Declared at src/server/session.c:552 ↗:

WART-11: nothing is sent back, and the reference client does not wait
for anything.
claim:       a request gets a response; that is what lock-step means.
reference:   the WebSocket handler breaks out of its receive loop on
             `close` without writing, then closes with code 1000.
observed:    corpus case 48's last exchange sends {"type":"close"}
             and receives only the close frame, payload 0x03E8.
honoured-by: this arm, which appends nothing at all. An
             acknowledgement here would desynchronise a client that
             is no longer reading — and one dependency-free server in
             the reference tree does send one, which is how we know
             clients do not read it.

WART-12

Declared at src/proto/jsonrpc.c:1106 ↗:

WART-12: a notification is answered.
claim:       JSON-RPC 2.0 section 4.1 — "The Server MUST NOT reply to a
             Notification, including those that are within a batch
             request." A request with no `id` is a Notification.
reference:   mcp_types.py:89-105 declares `id` as an ordinary optional
             field defaulting to None, and http_server.py:1460-1474 has
             no branch that suppresses a response; the id simply arrives
             as None and is serialised.
observed:    POST /mcp {"jsonrpc":"2.0","method":"tools/list"}
             -> 200 {"jsonrpc":"2.0","id":null,"error":{"code":-32603,
                "message":"Environment does not support MCP",
                "data":null}}                          (corpus case 37)
honoured-by: this arm, and by the branch that is NOT anywhere in this
             file: nothing here asks whether an id was present, because
             answering does not depend on it. A client should send one
             anyway — it gets a frame either way, and on WS /mcp an
             unexpected frame is a desynchronised session.

WART-13

Declared at src/proto/jsonrpc.c:1042 ↗:

WART-13: WS /mcp frames are SPACED and every other byte this server emits is
compact.
claim:       one server serialises JSON one way.
reference:   mcp_types.py:146-150 defines JsonRpcResponse.model_dump_json as
             `json.dumps(self.model_dump())` — CPython's DEFAULT separators,
             which are ", " and ": ". The /ws frame models are dumped by
             pydantic's own encoder, which is compact, and POST /mcp returns
             a dict that FastAPI re-serialises compactly.
observed:    case 67  {"type":"mcp","data":{"jsonrpc":"2.0","id":1,...}}
             case 68  {"jsonrpc": "2.0", "id": 1, "error": {"code": -32603,
                       "message": "Environment does not support MCP",
                       "data": null}}
             Identical values, captured from the same process, differing in
             exactly those spaces.
honoured-by: oe__rpc_open below, whose three arms are the only place in this
             program that OE_JSON_SPACED is ever selected.

Declared at src/server/mcp.c:525 ↗:

WART-13: this one route is serialised with spaces.
claim:       a server has an output encoding, not several.
reference:   the WS /mcp handler sends json.dumps(...) at its DEFAULT
             separators while every other path uses compact ones.
observed:    corpus 68 {"jsonrpc": "2.0", "id": 1, "error": {"code":
             -32603, ...}} against corpus 67's
             {"type":"mcp","data":{"jsonrpc":"2.0","id":1,...}} — the
             same value, one wire apart.
honoured-by: this framing argument, which is the only consumer of
             OE_JSON_SPACED in the entire program.

Also referred to from: src/proto/client_codec.c:35 src/proto/jsonrpc.c:1012 src/proto/jsonrpc.c:1069 src/server/conn.c:951

WART-14

Declared at src/wire/json_parse.c:86 ↗:

WART-14: a parser's own diagnostics are on somebody else's wire.
claim:       an error message is a courtesy to a human, so its exact text is
             nobody's contract.
reference:   the upstream server puts the text of CPython's
             json.JSONDecodeError straight into the payload it sends a peer
             when a document does not parse, so CPython's wording, its
             1-based line and column, and its 0-based character offset all
             become observable bytes.
observed:    a peer sending `{not json` is answered with the text
             `Expecting property name enclosed in double quotes: line 1
             column 2 (char 1)` (corpus case 62); the same document over the
             request path yields `"ctx":{"error":"Expecting property name
             enclosed in double quotes"}` (corpus case 23), the same wording
             with the suffix stripped.
honoured-by: this table, whose first twelve rows are transcribed verbatim,
             and oe_json_position below, which is JSONDecodeError.__init__
             transcribed. The five rows after them are ours, and are marked
             as ours, because nothing upstream produces them.

Also referred to from: src/proto/errors.c:151

WART-15

Declared at src/server/http_const.c:515 ↗:

WART-15: a server with two different 404 bodies, and a name that
disagrees with the one at GET /metadata.
claim:       one server, one shape for "that is not here".
reference:   the Task API routes are registered as `/{env_name}/…`
             ahead of the fixed paths, and their handler checks the
             captured segment against the REGISTERED name before it
             does anything else — so a two-segment miss is answered
             by application code with its own body while a
             one-segment miss falls through to Starlette's.
observed:    GET /nope           -> {"detail":"Not Found"}
             GET /nope/splits    -> {"detail":"unknown environment
                                     'nope'"}
             GET /CounterEnvironment/splits -> the same second body,
             even though GET /metadata on that very server answers
             {"name":"CounterEnvironment",…} (corpus cases 8, 28, 26
             and 1). The name /metadata publishes is not the name
             this route accepts; see WART-07 above.
honoured-by: this branch and the route table's order in
             src/proto/routes.c, where the six templated rows precede
             every fixed one-segment path for exactly this reason.

WART-16

Declared at src/client/client.c:1404 ↗:

WART-16: `action` goes through untouched and becomes `data` itself. The
wrapper POST /step puts around the same object is an extra key here, and
the marker carrying the evidence is in src/proto/client_codec.c.

Declared at src/proto/client_codec.c:124 ↗:

WART-16: the action is BARE here. `POST /step` wraps the same object
under an "action" key and this transport does not, so a client that
sends {"action":{...}} as its data gets `extra_forbidden` on the key
`action` (corpus case 71).
claim:      one action has one encoding.
reference:  ws_server.py reads `message.data` as the action model;
            http_server.py reads `body.action`.
observed:   WS   {"type":"step","data":{"amount":1}}
            HTTP {"action":{"amount":1}}
honoured-by: this line, which writes `data` and nothing around it,
            and the twin marker in src/proto/decode.c.

Declared at src/proto/decode.c:424 ↗:

WART-16: the action is BARE on this transport.
claim:       one action, one spelling.
reference:   the WebSocket handler passes message.data straight to
             deserialize_action, while http_server.py reads
             request.action out of a StepRequest first.
observed:    WS   {"type":"step","data":{"amount":1}}
             HTTP {"action":{"amount":1}}
             and corpus 63 sends the HTTP shape over the WebSocket:
             `data` becomes an action with an undeclared key `action`,
             answered with extra_forbidden at loc ["action"].
honoured-by: this line, which hands `data` on unwrapped, and the line
             marked WART-16 in oe__decode_step_http, which unwraps.

Declared at src/proto/decode.c:773 ↗:

WART-16: the action is WRAPPED on this transport. See the twin marker in
oe__decode_ws, where the same object arrives bare. This one line is the
whole of the difference, and corpus case 63 is what happens when a client
sends this shape to the other transport.

Also referred to from: envs/rewards.c:86 src/proto/decode.c:435 src/proto/decode.c:841 src/proto/decode.h:234 src/proto/decode.h:40 src/server/http_stateless.c:194 src/server/session.c:408

WART-17

Declared at src/proto/jsonrpc.c:943 ↗:

WART-17: a session created here spends the WebSocket's capacity
budget, and nothing in the answer says so.
claim:       two transports that do not share a message do not share
             a resource either.
reference:   http_server.py:845-871 stores the environment it builds
             in the same `_sessions` table that the `/ws` upgrade
             path consults for its `active >= max` test, and the
             entry is removed only by `openenv/session/close` — no
             timeout, no connection to hang up, no reaper.
observed:    {"jsonrpc": "2.0", "method": "openenv/session/create",
             "id": 1} is answered
             {"jsonrpc":"2.0","id":1,"result":{"session_id":
             "7f919318-7327-42b3-8578-0d0e73c83380"}} (corpus case
             42). The reply carries a uuid and nothing else: no
             lifetime, no active/max pair, no hint that the next
             WebSocket upgrade is one slot poorer.
honoured-by: this arm, which does not decide. It sets `todo` and
             hands the fact to whoever owns a session table — and
             the host this project ships owns none, so
             src/server/mcp.c answers -32000 instead and states why
             at GAP-19. The hazard is named here and reproduced
             nowhere.

Also referred to from: src/server/mcp.c:55

WART-18

Declared at src/proto/decode.c:466 ↗:

WART-18: the Content-Type header decides whether a body was sent.
claim:       a JSON API reads the bytes it was given.
reference:   FastAPI parses the body as JSON only when the media type's main
             type is `application` and its subtype is `json` or ends in
             `+json`; otherwise the raw bytes are handed to the model, which
             is not a mapping, and pydantic says so.
observed:    corpus 12 `application/json` -> 200; corpus 15
             `application/x-www-form-urlencoded` and corpus 16 with the header
             absent -> 422 {"type":"model_attributes_type","loc":["body"],
             "input":"{}"} — and note `input` is the two-character TEXT.
             `application/json; charset=utf-8` and `application/vnd.api+json`
             are both 200 [probed].
honoured-by: this function and the three-line rule at the top of read_body.

Also referred to from: src/proto/decode.c:556 src/proto/decode.h:189 src/proto/decode.h:205 src/server/http_stateless.c:425 src/server/mcp.c:502

WART-19

Declared at src/proto/errors.c:381 ↗:

WART-19: an unhandled failure is not JSON.
claim:       every response from a JSON API is JSON.
reference:   Starlette's ServerErrorMiddleware answers with a
             PlainTextResponse, which never passes through the JSON
             encoder the rest of the application uses.
observed:    500 Internal Server Error,
             `content-type: text/plain; charset=utf-8`, body
             `Internal Server Error`.
honoured-by: this row, and PROTOCOL.md MUST 8.B.19 telling a client not
             to assume a non-2xx body parses.

Also referred to from: src/proto/decode.c:573 src/proto/errors.h:126 src/server/conn.c:653 src/server/handlers.h:125 src/server/handlers.h:139 src/server/handlers.h:21 src/server/http_const.c:182 src/server/http_handle.c:111 src/server/http_handle.c:143 src/server/http_handle.c:35 src/server/http_stateless.c:171 src/server/mcp.c:105 src/server/serve.c:237

WART-20

Declared at src/proto/validate.c:237 ↗:

WART-20: a string is an acceptable integer, and so is a boolean.
claim:       a field declared `int` accepts the JSON integers.
reference:   pydantic's default validation mode is lax; the reference builds
             actions with model_validate and never asks for strict mode —
             `grep -rn strict` over its source returns four hits, none of
             them a validation mode (two are a CLI helper's parameter and two
             are a comment about network egress)
             (docs/evidence/REFERENCE-NOTES.md section 4.5).
observed:    "42" -> 42 and true -> 1 on an int field (corpus case 25 and a
             probe of pydantic 2.13.4); "x" -> int_parsing (corpus case 20);
             5 -> string_type on a str field, which coerces from NOTHING.
honoured-by: the six functions below, one per oe_fkind, each listing its
             accepted inputs in the order the reference tries them.

THE TABLE, probed against pydantic 2.13.4.

  from         -> int              -> real           -> str    -> bool
  ------------    ---------------     -------------     ------    ------------
  int            itself              widened           string_   0/1 only,
                                                       type      else
                                                                 bool_parsing
  real           integral only,      itself            string_   integral: the
                 else                                  type      int rule;
                 int_from_float                                  fractional:
                                                                 bool_type
  bool           1 / 0               1.0 / 0.0         string_   itself
                                                       type
  string         scanned, else       parsed, else      itself    a word list,
                 int_parsing         float_parsing               else
                                                                 bool_parsing
  null/arr/obj   int_type            float_type        string_   bool_type
                                                       type

Two rows are worth stopping on. The `str` column coerces from NOTHING — the
reference really does reject the number 5 for a string field — so an SDK that
helpfully stringifies numbers is wrong on the wire in the direction that
silently succeeds. And the `bool` column disagrees with itself: the integer 2
is `bool_parsing` while the real 2.5 is `bool_type`, because an integral real
is routed through the integer rule and a fractional one never gets that far.

WART-21

Declared at src/proto/routes.c:58 ↗:

WART-21: /openapi.json is the only route we serve that answers HEAD.
claim:       an HTTP server that answers GET answers HEAD.
reference:   docs/evidence/REFERENCE-NOTES.md section 3.0 enumerates the four
             FastAPI-owned routes as GET,HEAD and all fifteen core routes as
             single-method: the framework's own routes went through
             Starlette's add_route, whose methods default to GET and HEAD,
             and the core routes were each registered with one verb.
observed:    HEAD /health -> 405 Method Not Allowed, `allow: GET`,
             `content-length: 31`, and no body (corpus case 10).
honoured-by: M_GET_HEAD on the /openapi.json row and plain M_GET on every
             other GET row, which is what oe__route_allow reports.

Also referred to from: src/proto/openapi.c:66

WART-22

Declared at src/proto/errors.c:596 ↗:

WART-22: whether an error item carries `url` is decided by the CODE PATH
that produced it, not by what the item says.
claim:       an error's shape is a function of the error, so two items with
             the same slug and the same depth of `loc` have the same keys.
reference:   fastapi/_compat/v2.py:187 calls
             `exc.errors(include_url=False)` and prefixes `loc` with
             "body". That one call site is the only place in the stack that
             strips the key, and it is the same place the prefix is added.
             Every other path — including the WebSocket handler's own
             model_validate — uses plain `.errors()` and keeps it.
observed:    http  loc:["amount"]         int_parsing      HAS url
             http  loc:["body","action"]  missing          NO url
             http  loc:["bogus"]          extra_forbidden  HAS url
             ws    loc:["amount"]         int_parsing      HAS url
             ws    loc:["data"]           missing          HAS url   <-- 57
honoured-by: the two `if`s below, both reading `from_request_body`, which
             came from the caller as oe_diag.origin and was not inferred
             from anything.

THE LAST ROW IS THE WHOLE POINT. `loc:["data"]` is an envelope-level error
and it CARRIES a url, so the plausible rule — "field errors have a url,
envelope errors do not" — is false, and a validator that infers the answer
from the shape of `loc` emits the wrong bytes for corpus case 57 while
passing every other case. It was believed by four separate analyses of this
protocol, including one that had probed the running server.

WART-23

Declared at src/proto/jsonrpc.c:567 ↗:

WART-23: a batch array is a PARSE ERROR.
claim:       JSON-RPC 2.0 section 6 defines batches, so a server that does
             not support them answers -32600 Invalid Request.
reference:   http_server.py:1460 constructs the model as
             `JsonRpcRequest(**payload)`. The `**` splat of a list is a
             TypeError, not a ValidationError, so it falls past the model's
             own handler into the blanket `except Exception` at :1476, which
             answers PARSE_ERROR.
observed:    POST /mcp [{"jsonrpc":"2.0","method":"tools/list","id":1}]
             -> {"jsonrpc":"2.0","id":null,"error":{"code":-32700,
                 "message":"Parse error","data":null}}   (corpus case 36),
             and the same answer for `5`, `""` and `"hi"`.
honoured-by: this function, which is reached for every JSON value that is
             not an object and never consults the request model.

`detail` is CPython's own diagnostic and is empty on two of the three
framings: the reference's HTTP handler builds this message with no detail at
all, and a well-formed non-object has no syntax error to describe.

Also referred to from: src/proto/jsonrpc.c:775 src/proto/jsonrpc.h:283

WART-24

Declared at src/proto/jsonrpc.c:460 ↗:

WART-24: a `params` that is not an object is INVALID REQUEST, not
INVALID PARAMS.
claim:       -32602 exists for a request whose params are wrong.
reference:   http_server.py:751-756 has an `isinstance(params, dict)`
             guard that answers -32602 and is DEAD CODE: the model is
             validated at :1460 before the guard is reached, and
             pydantic rejects a non-dict first.
observed:    POST /mcp {"jsonrpc":"2.0","method":"tools/list",
             "params":[1],"id":1} -> -32600, "params  Input should be a
             valid dictionary [type=dict_type, input_value=[1],
             input_type=list]" (corpus case 38).
honoured-by: this branch, which raises the code the model raises rather
             than the code the method dispatcher would have.

WART-25

Declared at src/proto/jsonrpc.c:788 ↗:

WART-25: a request that fails validation is answered with `"id":null`,
even when it carried a perfectly good id.
claim:       a JSON-RPC server echoes the id it was given, so a client
             can match answers to questions.
reference:   http_server.py:1460-1474 validates the model first and only
             reads `request.id` from the VALIDATED object, so a request
             that did not validate has no id to read.
observed:    POST /mcp {"jsonrpc":"1.0","method":"tools/list","id":1}
             -> {"jsonrpc":"2.0","id":null,...}      (corpus case 35)
honoured-by: this assignment, which is BELOW the validation branch above
             and not above it.

Also referred to from: src/proto/jsonrpc.c:782 src/proto/jsonrpc.h:227

WART-26

Declared at src/proto/jsonrpc.c:819 ↗:

WART-26: an unrecognised method that carries a bad session id is
answered about the session, not about the method.
claim:       a server that does not have a method says so first.
reference:   http_server.py:845-871 resolves `params["session_id"]`
             against the session table BEFORE the method dispatch at
             :873, so an id that names nothing returns from the
             resolution step and the method is never looked at.
observed:    POST /mcp {"jsonrpc":"2.0","method":"foo/bar",
             "params":{"session_id":"zzz"},"id":7}
             -> -32602 "Unknown session_id: zzz", NOT -32601
             (docs/evidence/REFERENCE-NOTES.md section 3.9, [probed]).
honoured-by: this block, which fills `session_id` whatever the method
             is, and the contract in jsonrpc.h that says a caller
             resolves it before it acts on `todo`. The ORDER cannot live
             here, because the table it consults cannot.

Also referred to from: src/proto/jsonrpc.c:907 src/proto/jsonrpc.h:235 src/proto/jsonrpc.h:405 src/proto/jsonrpc.h:76 src/proto/jsonrpc.h:92 src/server/mcp.c:360 src/server/mcp.c:379

WART-27

Declared at src/proto/jsonrpc.c:869 ↗:

WART-27: `tools/call` answers about its PARAMS before it answers
about the environment, so an environment with no tools at all still
complains about a missing name.
claim:       an environment that supports no tools can answer every
             tools/call the same way, because there is nothing a
             name could have selected.
reference:   http_server.py:967 reads `params.get("name")` and
             returns INVALID_PARAMS "Missing 'name' in params" at
             :970-975 — ABOVE the `mcp_client is None and
             mcp_server is None` test at :977 that produces
             "Environment does not support MCP". The tool-surface
             question is never reached by a request with no name.
observed:    reference interop/probe_env.py (no tool surface) on
             8901, POST /mcp:
               {"jsonrpc":"2.0","method":"tools/call","id":2,
                "params":{}}
               -> {"jsonrpc":"2.0","id":2,"error":{"code":-32602,
                   "message":"Missing 'name' in params",
                   "data":null}}
               {"jsonrpc":"2.0","method":"tools/call","id":3,
                "params":{"name":"x"}}
               -> {"jsonrpc":"2.0","id":3,"error":{"code":-32603,
                   "message":"Environment does not support MCP",
                   "data":null}}
             Ours, build/rel/bin/counter on 8994, answered the FIRST
             request with the SECOND answer until this branch
             existed: one input, one wrong code, one wrong message.
             Both `-32602` rows re-measured on all three framings
             (POST /mcp, WS /mcp, `{"type":"mcp"}` on /ws) against
             8901 and 8902 before this line was written.
honoured-by: this arm, whose ORDER is the whole of it. The name test
             is first and the tool-surface answer is second, which is
             the reference's source order and is the reason
             `tools/list` above cannot share the branch.

The session id is resolved before EITHER of these, by the caller and
not here — `{"params":{"session_id":"zzz"}}` with no name answers
"Unknown session_id: zzz" and not "Missing 'name' in params", which
is WART-26 measured on this very method. Three orderings, one
request; this file owns the second and third.

WHAT COMES AFTER THE NAME TEST IS NOT A DECISION THIS FILE CAN MAKE.
The four rows below all begin here and end somewhere else, because
three of them need something a pure function of the request does not
have — a const table, or an environment instance to run a handler
against. Captured live from the `mcp_server`-only branch on 8908,
which is the branch whose tool SHAPE we emit:

  params                              answer
  ----------------------------------  --------------------------------
  {}                                  -32602 Missing 'name' in params
  {"name":"nope"}, no table           -32603 Environment does not …
  {"name":"nope"}, table without it   -32602 Tool not found: nope
  {"name":"bump","arguments":{…}} and
    the handler raised                -32603 _bump() got an unexpected
                                             keyword argument 'nope'
  {"name":"bump","arguments":{…}}     result, BARE: {"…","result":2}

Row 1 is here. Rows 2-4 are oe__rpc_fail_no_mcp,
oe__rpc_fail_tool_not_found and oe__rpc_fail_tool_error, called by
whoever holds the table.

Also referred to from: src/proto/jsonrpc.c:58 src/proto/jsonrpc.h:189 src/proto/jsonrpc.h:44 src/proto/types.h:387 src/server/mcp.c:139

WART-28

Declared at src/proto/tool.h:174 ↗:

WART-28: an empty description is a key with an empty string, and a tool with
no arguments publishes `{}` rather than omitting its schema.
claim:       a serialiser omits a key it has nothing to put under.
reference:   http_server.py:951-952 writes `tool.description or ""` and
             `tool.parameters or {}` — two `or`s that turn None into a value
             rather than into an absence.
observed:    the `mcp_server`-only branch on 8908, whose second tool declares
             neither a docstring nor a parameter:
               {"name":"cat","description":"","inputSchema":{}}
honoured-by: the description line in oe__tool_write_table, which writes the
             empty slice `oe_str_cstr(NULL)` produces rather than skipping
             the key, and oe__schema_write_tool_args, which writes `{}` for a
             tool with no argument table.

Also referred to from: src/proto/tool.c:426

§ 2 · CONF- — this line satisfies numbered server requirement n

CONF- — this line satisfies numbered server requirement n

#WhereThe citation
CONF-01src/server/serve.c:123the container contract is TCP 8000 on 0.0.0.0, and both halves of it are defaults rather than arguments because every provider maps the container side to 8000 and several refuse any other value. A server that binds the loopback answers nothing from outside its container.
CONF-02src/server/http_const.c:577200 with a JSON body, answered before any environment exists — which is what makes it a readiness probe rather than a liveness one.
CONF-03src/proto/openapi.c:140GET /openapi.json returns a document whose info.version is a string beginning "1." and whose paths lists every HTTP route we publish.
CONF-04src/server/http_const.c:108name and description are strings and the other four are nullable, which is exactly what the official validator reads.
CONF-05src/proto/schema.c:880GET /schema answers with action, observation and state, each a JSON object — criterion 4 of openenv validate --url.
CONF-06src/proto/jsonrpc.c:522POST /mcp with the body {} answers HTTP 200 with a JSON-RPC payload — never 4xx. This function composes that payload, and the status is the caller's: an error in this dialect is a 200 carrying an error member, which is the criterion the official validator checks and the one place OpenEnv's HTTP surface refuses to use HTTP's own error channel.
CONF-07src/proto/openapi.c:143mode consistency — /reset, /step and /state appear together or not at all. All three are simulation_only rows in the table, so the production bit decides the whole trio in one place: false publishes all three (the simulation arm), true skips all three (the production arm), and the criterion is satisfied by the column rather than by a runtime agreement between two files.
CONF-08src/server/http_stateless.c:150an absent body, {} and {"seed":n,"episode_id":s,…} are all accepted; the answer is the four-key envelope in that key order with metadata always present; seed < 0 and a non-JSON content type are 422.
CONF-09src/server/http_stateless.c:290the action arrives WRAPPED under "action" here (WART-16), the optional timeout_s and request_id are accepted beside it, and the answer is the same four-key envelope with reward coerced to a number or null.
CONF-10src/server/http_stateless.c:376a flat object carrying at least episode_id (string or null) and step_count (a non-negative integer). Here it carries exactly those two, which is the wart above and is also the whole of the requirement.
CONF-11src/proto/errors.c:622action-validation failures carry an action-relative loc; envelope-validation failures carry one prefixed with "body".
CONF-12src/server/conn.c:701the accept names no subprotocol, because /ws negotiates none.
CONF-13src/proto/decode.c:123these five names are every client message WS /ws accepts. The extras pass further down is the other half of the same MUST — an envelope key that is not type or a declared data is VALIDATION_ERROR, never ignored.
CONF-14src/proto/encode.c:526these four names, type before data, are the whole of what a server may emit on WS /ws — with reward uncoerced and metadata omitted when empty, which is what oe__encode_obs_ws above does.
CONF-15src/server/session.c:46this pointer, held across frames, is the whole of "maintain per-connection session state". Two steps on one connection see accumulated state because they see the same self, and no reset is required first.
CONF-16src/proto/errors.c:76the seven WSErrorCode strings, with VALIDATION_ERROR carrying errors, CAPACITY_REACHED carrying active_sessions/max_sessions, and FACTORY_ERROR carrying factory_name.
CONF-17src/server/session.c:139capacity is reported in a frame, not in the handshake.
CONF-18src/server/conn.c:973a close message is answered with silence and then a Close frame carrying 1000 with an empty reason. The three terminal error codes arrive here too, having already appended their frame.
CONF-18src/server/session.c:550a close message is answered with silence, not a frame.
CONF-19src/proto/jsonrpc.c:846POST /mcp and WS /mcp implement tools/list, tools/call, openenv/session/create and openenv/session/close; anything else is -32601 "Method not found: <m>".
CONF-19src/server/mcp.c:511every JSON-RPC error, including a parse error, is HTTP 200. The status line describes the HTTP exchange and the error member describes the RPC — conflating them is how a client ends up retrying a malformed request forever.
CONF-20src/server/http_const.c:440the six Task API routes are registered, env_name is matched case-insensitively, a mismatch is the second 404 and a match is a 501 naming the method — which is a conforming answer for an environment with no task set, and every environment this project ships has none.
CONF-21src/server/http_handle.c:29every JSON answer this file can produce carries content-type: application/json and nothing else — no CORS header, no auth header, no header of ours. That is structural rather than disciplined: oe_http_res in src/wire/http.h has three header-shaped members (allow, content_type, location) and no extension point, so there is no way to attach a fourth header without editing the type. The one non-JSON answer is WART-19's 500, which is text/plain on purpose.
CONF-22src/server/http_handle.c:254the three Starlette-compatible defaults, and all three are here rather than in a handler because none of them is an environment's business — a trailing slash is a 307 carrying location, a path that matches no row is a 404 with {"detail":"Not Found"}, and step 4 below is the 405 with allow.
CONF-23src/server/serve.c:428a termination signal must produce a clean exit, and the only thing a handler does is write one byte to the pipe the loop is already watching. docker stop sends SIGTERM and then SIGKILLs ten seconds later; a server that ignores it makes every teardown take those ten seconds. SIGPIPE is deliberately NOT touched: it is suppressed per-send inside wire/net.c, because a process-wide disposition is the embedder's and we do not get to change it behind them.