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:
| Line | Says |
|---|---|
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.
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
CONF- — this line satisfies numbered server requirement n
| # | Where | The citation |
|---|---|---|
CONF-01 | src/server/serve.c:123 | the 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-02 | src/server/http_const.c:577 | 200 with a JSON body, answered before any environment exists — which is what makes it a readiness probe rather than a liveness one. |
CONF-03 | src/proto/openapi.c:140 | GET /openapi.json returns a document whose info.version is a string beginning "1." and whose paths lists every HTTP route we publish. |
CONF-04 | src/server/http_const.c:108 | name and description are strings and the other four are nullable, which is exactly what the official validator reads. |
CONF-05 | src/proto/schema.c:880 | GET /schema answers with action, observation and state, each a JSON object — criterion 4 of openenv validate --url. |
CONF-06 | src/proto/jsonrpc.c:522 | POST /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-07 | src/proto/openapi.c:143 | mode 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-08 | src/server/http_stateless.c:150 | an 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-09 | src/server/http_stateless.c:290 | the 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-10 | src/server/http_stateless.c:376 | a 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-11 | src/proto/errors.c:622 | action-validation failures carry an action-relative loc; envelope-validation failures carry one prefixed with "body". |
CONF-12 | src/server/conn.c:701 | the accept names no subprotocol, because /ws negotiates none. |
CONF-13 | src/proto/decode.c:123 | these 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-14 | src/proto/encode.c:526 | these 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-15 | src/server/session.c:46 | this 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-16 | src/proto/errors.c:76 | the seven WSErrorCode strings, with VALIDATION_ERROR carrying errors, CAPACITY_REACHED carrying active_sessions/max_sessions, and FACTORY_ERROR carrying factory_name. |
CONF-17 | src/server/session.c:139 | capacity is reported in a frame, not in the handshake. |
CONF-18 | src/server/conn.c:973 | a 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-18 | src/server/session.c:550 | a close message is answered with silence, not a frame. |
CONF-19 | src/proto/jsonrpc.c:846 | POST /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-19 | src/server/mcp.c:511 | every 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-20 | src/server/http_const.c:440 | the 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-21 | src/server/http_handle.c:29 | every 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-22 | src/server/http_handle.c:254 | the 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-23 | src/server/serve.c:428 | a 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. |