miniopenenv

docs/BOUNDARY.md → html

The boundary

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

Two boundaries, one index.

The first is the one this project was commissioned to draw. Every declaration in the public headers and in src/proto/ carries exactly one tag, and it answers the question the reference implementation makes hard to answer: which of these names is the protocol, and which is us?

TagMeansThe test
[WIRE]bytes a non-C client sees, or a name that appears in themchange it and a Python client notices
[SDK]our ergonomics, zero wire footprintchange it and only C callers notice
[POLICY]our free choice, and yours to changea different implementer could legitimately differ

tools/check.sh rule 16 fails the build if an aggregate is tagged at the type level and at some of its members but not all of them, because a half-tagged struct is where a wrong tag hides. oe_field is the reason that rule exists: it was once tagged [SDK] under the sentence "None of it is on the wire" while three of its four members were copied onto the wire verbatim.

The extraction rule, stated so that a row which looks odd is explained by the rule rather than by a bug:

Files under src/wire/ carry no tags, and that is not an oversight: the tags classify the protocol surface, and by construction nothing in that directory is on it (tools/check.sh rule 5). The exception is oe_err, which is [SDK] because it is also declared in an installed header.

§ 1 · [WIRE]

[WIRE]

SymbolWhereNote
oe_session_openinclude/openenv/embed.h:113Open a session, and produce the frame that says you could not.
oe_session_frameinclude/openenv/embed.h:151THE PROTOCOL, LITERALLY.
oe_ws_mcp_frameinclude/openenv/embed.h:186One frame on WS /mcp: bare JSON-RPC 2.0, spaced, always exactly one response frame.
oe_http_handleinclude/openenv/embed.h:196One complete HTTP/1.1 request in, one complete HTTP/1.1 response out: status line, headers and body, ready to write to a socket.
oe_wserrinclude/openenv/openenv.h:102The seven WSErrorCode strings.
oe_wserrinclude/openenv/openenv.h:107
oe_wserr_nameinclude/openenv/openenv.h:118"VALIDATION_ERROR", "CAPACITY_REACHED", ... — the bytes themselves.
oe_wserr_terminalinclude/openenv/openenv.h:121True when the reference sends this frame and then closes.
oe_kindinclude/openenv/openenv.h:171
oe_rewardinclude/openenv/openenv.h:269
oe_obsinclude/openenv/openenv.h:306
nameinclude/openenv/openenv.h:366The JSON-Schema property key, and the key the validator matches a request's members against, both verbatim.
json_defaultinclude/openenv/openenv.h:376JSON TEXT, e.g.
descriptioninclude/openenv/openenv.h:389The schema's description string, verbatim.
nameinclude/openenv/openenv.h:429GET /metadata .name — the reference reports the Python CLASS name here, not the manifest name, so "CounterEnvironment" is the right answer and "counter_env" is not.
descriptioninclude/openenv/openenv.h:433GET /metadata .description
task_env_nameinclude/openenv/openenv.h:435The name the TASK API answers to: the single element of GET /list_environments, and the name /{env_name}/splits is matched against, case-insensitively.
versioninclude/openenv/openenv.h:449NULL => "1.0.0"
readme_contentinclude/openenv/openenv.h:450NULL => JSON null
authorinclude/openenv/openenv.h:451NULL => JSON null
documentation_urlinclude/openenv/openenv.h:452NULL => JSON null
toolsinclude/openenv/openenv.h:462The tool table, OE_TOOLS_END-terminated — section 9.
resetinclude/openenv/openenv.h:475
stepinclude/openenv/openenv.h:476
stateinclude/openenv/openenv.h:478YOU write episode_id and step_count here; they are base State fields the reference's environments construct too.
last_errorinclude/openenv/openenv.h:487Set this before returning non-OK from a callback.
max_sessionsinclude/openenv/openenv.h:5410 => 8.
oe_resultinclude/openenv/openenv.h:661
oe_client_wait_healthyinclude/openenv/openenv.h:697Poll GET {base}/health until it answers 200.
oe_client_openinclude/openenv/openenv.h:707base -> ws: strip trailing '/', http->ws, https->wss, a bare host becomes ws://, then append the literal "/ws".
oe_client_resetinclude/openenv/openenv.h:728
oe_client_stepinclude/openenv/openenv.h:729
oe_client_stateinclude/openenv/openenv.h:733{"type":"state"} — no data key, and the WebSocket answers the FULL state dump where GET /state whitelists two fields (WART-05).
oe_client_pumpinclude/openenv/openenv.h:744Answer the peer's heartbeat without making a call.
oe_client_closeinclude/openenv/openenv.h:760Sends {"type":"close"} and awaits nothing: it is the single message the reference answers with silence.
oe_toolerrinclude/openenv/openenv.h:842ToolErrorType — five strings, a CLOSED set, from OpenEnv's own mcp_types.py:198-205 and not from any library it imports.
oe_toolerrinclude/openenv/openenv.h:845
oe_toolerr_nameinclude/openenv/openenv.h:867The five spellings, verbatim, as the error_type member of a ToolError object.
oe_tool_outinclude/openenv/openenv.h:883
nameinclude/openenv/openenv.h:986as published, exact bytes.
descriptioninclude/openenv/openenv.h:1000NULL => "", never an omitted key — http_server.py:951 or ""
callinclude/openenv/openenv.h:1011
authoritysrc/client/client.h:41The authority exactly as it was written, brackets and port included, which is the Host header's value.
pathsrc/client/client.h:49The request target for the upgrade — always ending in the literal /ws, because oe__client_ws_url appended it.
basesrc/client/client.h:53The same path without that trailing /ws: the prefix every HTTP route hangs off, so that a server behind a path-prefixing proxy is reachable at {base}/health as well as at {base}/ws.
oe__client_encodesrc/proto/client_codec.h:83Append one complete client frame's JSON to out, compact.
kindsrc/proto/client_codec.h:109which of the four response types this frame was.
datasrc/proto/client_codec.h:112the whole data value: the four-key envelope for an observation, the full state dump for a state, the JSON-RPC response for an mcp, the message/code object for an error.
resultsrc/proto/client_codec.h:117the envelope, read the way MUST 8.B.12-15 say to read it.
oe__client_decodesrc/proto/client_codec.h:122Decode one text frame from WS /ws.
oe__reward_ofsrc/proto/client_codec.h:140The four JSON shapes reward arrives in, as the tagged union that keeps all four (MUST 8.B.13).
oe__wserr_of_namesrc/proto/client_codec.h:146The seven WSErrorCode strings, read rather than written.
oe__client_ws_urlsrc/proto/client_codec.h:175base URL -> the WebSocket URL to dial, allocated in a.
oe_msg_kind_namesrc/proto/decode.c:102The five wire spellings.
oe_msg_kind_ofsrc/proto/decode.c:119The reverse.
oe__decode_wssrc/proto/decode.h:118Decode one text frame from WS /ws.
oe__decode_bodysrc/proto/decode.h:181The body-reading rule ALONE, with no request model behind it: is there a body at all, does its Content-Type make it one, is it JSON, and is that JSON an object.
oe__decode_reset_httpsrc/proto/decode.h:198POST /reset — request model ResetRequest, extra="allow".
oe__decode_step_httpsrc/proto/decode.h:213POST /step — request model StepRequest, extra="allow".
oe_tool_action_kindsrc/proto/decode.h:268
oe_tool_actionsrc/proto/decode.h:276What a call_tool action carried.
oe_tool_actionsrc/proto/decode.h:289
oe__decode_tool_actionsrc/proto/decode.h:295Sniff one action object.
oe_res_kind_namesrc/proto/encode.c:521Declared in proto/types.h; defined here because this is the only file that puts one of these four words on a wire.
oe__encode_begin_httpsrc/proto/encode.h:85Compact separators, CPython's float repr.
oe__encode_begin_wssrc/proto/encode.h:89Compact separators, pydantic's float rule.
oe__encode_obs_httpsrc/proto/encode.h:105reward is coerced to a JSON float and metadata is ALWAYS present, as null when it is empty.
oe__encode_obs_wssrc/proto/encode.h:109reward reaches the peer exactly as the environment wrote it — null, true, 3 and 1.5 are all legal — and metadata is OMITTED when empty.
oe__encode_state_httpsrc/proto/encode.h:123Exactly episode_id then step_count, and nothing else, whatever the environment wrote.
oe__encode_state_wssrc/proto/encode.h:127The two base fields first, then every other member the environment wrote, in the order it wrote them.
oe__encode_frame_opensrc/proto/encode.h:140Writes {"type":"...","data": and leaves the writer expecting exactly one value: the payload.
oe__encode_frame_closesrc/proto/encode.h:144Closes the object the frame opened.
oe__encode_frame_jsonsrc/proto/encode.h:147The one-call form, for the two frame types whose payload is a tree somebody else already built — an error's data from errors.c, a JSON-RPC response from jsonrpc.c.
oe__encode_tools_httpsrc/proto/encode.h:196ListToolsObservation.
oe__encode_call_tool_httpsrc/proto/encode.h:210CallToolObservation.
oe_wserr_namesrc/proto/errors.h:80"VALIDATION_ERROR", "CAPACITY_REACHED", ... — the bytes themselves.
oe_wserr_terminalsrc/proto/errors.h:85True when the reference sends this frame and then closes.
oe__wserr_ofsrc/proto/errors.h:89Our failure, in the peer's vocabulary.
oe_http_errorsrc/proto/errors.h:129One row.
oe_http_errorsrc/proto/errors.h:133
oe__http_errorsrc/proto/errors.h:140The row for a failure.
oe_loc_kindsrc/proto/errors.h:170
oe_locsrc/proto/errors.h:175One element of a loc path.
oe_locsrc/proto/errors.h:184
oe_ctx_kindsrc/proto/errors.h:190The ctx object, which is present on some slugs and absent on most.
oe_ctx_kindsrc/proto/errors.h:198
oe_diag_ctxsrc/proto/errors.h:205
oe_input_kindsrc/proto/errors.h:213The input member: the value that was actually validated, echoed back.
oe_input_kindsrc/proto/errors.h:229
oe_diag_inputsrc/proto/errors.h:235
oe_diag_itemsrc/proto/errors.h:241One error item.
oe_diag_itemsrc/proto/errors.h:244
oe__diag_write_itemssrc/proto/errors.h:336The bare array, [{...},{...}].
oe__diag_write_detailsrc/proto/errors.h:340The whole 422 body, {"detail":[...]}.
oe_wserr_framesrc/proto/errors.h:369
oe__error_write_datasrc/proto/errors.h:391The data object alone: {"message":...,"code":...[,extras]}.
oe__error_write_framesrc/proto/errors.h:394The whole frame: {"type":"error","data":{...}}.
oe_rpc_method_namesrc/proto/jsonrpc.c:100Declared in proto/types.h; defined here because this is the only file that compares one of these four strings.
oe_rpc_method_ofsrc/proto/jsonrpc.c:116Exact byte match, and nothing else.
oe_rpc_framingsrc/proto/jsonrpc.h:161
oe__rpc_dispatchsrc/proto/jsonrpc.h:282Dispatch one already-parsed request.
oe__rpc_dispatch_bytessrc/proto/jsonrpc.h:293Parse doc and dispatch it.
oe__rpc_fail_unknown_sessionsrc/proto/jsonrpc.h:305Turn a dispatched session-close into the -32602 the reference emits for an id its table does not hold: "Unknown session_id: <id>".
oe__rpc_fail_no_mcpsrc/proto/jsonrpc.h:324-32603 "Environment does not support MCP" — the answer for an environment whose tools member is NULL, reached by a tools/call that carried a name.
oe__rpc_fail_tool_not_foundsrc/proto/jsonrpc.h:330-32602 "Tool not found: <name>", with name rendered as Python's str() renders it inside an f-string — bare for a string, 5 for an int, True for a bool.
oe__rpc_fail_tool_errorsrc/proto/jsonrpc.h:351-32603 "<message>" — a tool that ran and failed.
oe__rpc_fail_args_not_objectsrc/proto/jsonrpc.h:381-32603 for a tools/call whose arguments the tool's KEY SET refuses: a non-mapping arguments (oe__rpc_fail_args_not_object), or a mapping carrying a key the tool does not declare (oe__rpc_fail_arg_undeclared).
oe__rpc_wants_tool_tablesrc/proto/jsonrpc.h:401True when call is a tools/list still carrying the dispatcher's own "no tool surface" answer, and therefore the one request a caller WITH a table should answer differently.
oe__rpc_opensrc/proto/jsonrpc.h:434Open a writer in this framing's style, and for the enveloped framing write {"type":"mcp","data": as well.
oe__rpc_closesrc/proto/jsonrpc.h:438Close whatever oe__rpc_open opened.
oe__rpc_write_errorsrc/proto/jsonrpc.h:443{"jsonrpc":"2.0","id":<id>,"error":{"code":<c>,"message":<m>, "data":<d>}}.
oe__rpc_write_callsrc/proto/jsonrpc.h:448The same, for a call the dispatcher already decided.
oe__rpc_write_resultsrc/proto/jsonrpc.h:451{"jsonrpc":"2.0","id":<id>,"result":<result>}.
oe__rpc_write_session_createdsrc/proto/jsonrpc.h:455The two session results, spelled here so that a server never writes a JSON-RPC key of its own: create -> {"session_id":"<id>"} close -> {"session_id":"<id>","closed":true} closed is always true, because a close that failed is one of the errors above rather than a result with a false in it.
oe__rpc_write_tools_listsrc/proto/jsonrpc.h:464The whole of a successful tools/list:
oe__openapi_writesrc/proto/openapi.h:95Append the whole document as one JSON value to a writer the caller opened.
oe__openapi_buildsrc/proto/openapi.h:105The whole GET /openapi.json body, appended to out.
oe__pyrepr_inputsrc/proto/pyrepr.h:54pydantic's input_value=<repr>, truncated exactly as pydantic truncates it: at most OE_PYREPR_LIMIT bytes pass through whole, and anything longer comes back as the first OE_PYREPR_HEAD bytes, ..., and the last OE_PYREPR_TAIL — each end moved to a UTF-8 character boundary, so the result is always a legal string in a text frame.
oe__pyrepr_strsrc/proto/pyrepr.h:66Python's str(value), as it appears interpolated into an f-string.
oe__pyrepr_of_strsrc/proto/pyrepr.h:76repr() of a STRING, which is the one thing the two above cannot spell: oe__pyrepr_input reprs it and then applies pydantic's fifty-byte cut, and oe__pyrepr_str is the arm that deliberately drops the quotes.
oe_route_idsrc/proto/routes.h:33One identifier per row, in registration order.
oe_route_idsrc/proto/routes.h:37
oe_routesrc/proto/routes.h:62One row.
oe_routesrc/proto/routes.h:64
oe__route_matchsrc/proto/routes.h:124Match a request path against the table, FIRST MATCH WINS, in table order.
oe__route_allowsrc/proto/routes.h:155The union of the method bits of every HTTP row whose path matches, or 0 when no row does.
oe__schema_buildsrc/proto/schema.h:196The whole GET /schema body, appended to out.
oe__schema_write_actionsrc/proto/schema.h:242The action model: the injected metadata field, then the author's action fields in declaration order.
oe__schema_write_observationsrc/proto/schema.h:247The observation model: the injected done, reward and metadata fields, then the author's observation fields in declaration order.
oe__schema_write_statesrc/proto/schema.h:252The state model — a CONSTANT.
oe__schema_write_tool_argssrc/proto/schema.h:288One tool's argument schema, appended to out.
oe__schema_titlesrc/proto/schema.h:306Title Case, pydantic's rule: name.title().replace('_', ' ').
oe_tool_spellingsrc/proto/tool.h:141
oe__tool_write_tablesrc/proto/tool.h:146The whole table as a JSON ARRAY of three-key rows, appended to w:
oe__tool_findsrc/proto/tool.h:191The row whose name is exactly name, or NULL.
oe__tool_arg_undeclaredsrc/proto/tool.h:200Does args carry a key this tool does not declare? The GAP-21 gate on the AGENT door, KEY SET ONLY: true when any member of args is outside the tool's declared argument names.
oe__tool_unknown_messagesrc/proto/tool.h:264Unknown tool: 'nope', NUL-terminated, pointing into *out.
oe_transportsrc/proto/types.h:162
oe_msg_kindsrc/proto/types.h:193
oe_msg_kind_namesrc/proto/types.h:202The five wire spellings.
oe_msg_kind_ofsrc/proto/types.h:207The reverse: a type string to its kind, OE_MSG_UNKNOWN for anything else.
oe_msgsrc/proto/types.h:212One decoded client frame.
oe_msgsrc/proto/types.h:220
oe_res_kindsrc/proto/types.h:244
oe_res_kind_namesrc/proto/types.h:251the four spellings
oe_errs_originsrc/proto/types.h:322
oe_rpc_methodsrc/proto/types.h:360
oe_rpc_method_namesrc/proto/types.h:368the four spellings
oe_rpc_method_ofsrc/proto/types.h:369UNKNOWN otherwise
OE_RPC_PARSE_ERRORsrc/proto/types.h:371The six codes.
oe_verr_slugsrc/proto/validate.h:80
oe__verr_typesrc/proto/validate.h:105The slug as it appears in type, and as the tail of url.
oe__verr_msgsrc/proto/validate.h:108Its msg, verbatim.
oe__validate_coercesrc/proto/validate.h:167ONE value against ONE declared kind, by the lax rules of PART 3.
§ 2 · [SDK]

[SDK]

SymbolWhereNote
oe_buf_newinclude/openenv/embed.h:81A buffer growing out of a.
oe_buf_bytesinclude/openenv/embed.h:96
oe_buf_leninclude/openenv/embed.h:97
oe_buf_okinclude/openenv/embed.h:99False when the arena refused, or when a builder decided the message must not exist.
oe_sessioninclude/openenv/embed.h:108One session: one environment instance and the state block it was given.
oe_session_freeinclude/openenv/embed.h:139End the session: run the environment's fini callback, if it declared one, and mark the handle spent.
oe_versioninclude/openenv/openenv.h:50Our version, "0.1.0".
oe_errinclude/openenv/openenv.h:78
oe_err_nameinclude/openenv/openenv.h:97The identifier as text, for logs and test output — never for a peer.
oe_arenainclude/openenv/openenv.h:140
oe_bufinclude/openenv/openenv.h:145append-only, arena-backed byte buffer
oe_arena_newinclude/openenv/openenv.h:148NULL on OOM
oe_arena_resetinclude/openenv/openenv.h:149
oe_arena_freeinclude/openenv/openenv.h:150
oe_arena_okinclude/openenv/openenv.h:151
oe_arena_usedinclude/openenv/openenv.h:152
oe_jsoninclude/openenv/openenv.h:184
oe_kind_ofinclude/openenv/openenv.h:193
oe_obj_getinclude/openenv/openenv.h:194NULL when the key is absent, when obj is not an object, or when it is NULL.
oe_leninclude/openenv/openenv.h:198
oe_atinclude/openenv/openenv.h:199
oe_key_atinclude/openenv/openenv.h:200
oe_val_atinclude/openenv/openenv.h:201
oe_as_strinclude/openenv/openenv.h:203oe_as_str returns fallback when the string contains an interior NUL, because a const char * cannot represent one and a TRUNCATED string is worse than none: the validator would have seen safe ; rm -rf / and you would act on safe.
oe_as_strinclude/openenv/openenv.h:207
oe_as_sliceinclude/openenv/openenv.h:208
oe_as_intinclude/openenv/openenv.h:209
oe_as_realinclude/openenv/openenv.h:210
oe_as_boolinclude/openenv/openenv.h:211
oe_obj_get_strinclude/openenv/openenv.h:213
oe_obj_get_intinclude/openenv/openenv.h:214
oe_obj_get_realinclude/openenv/openenv.h:215
oe_obj_get_boolinclude/openenv/openenv.h:216
oe_obj_set_nullinclude/openenv/openenv.h:223
oe_obj_set_boolinclude/openenv/openenv.h:224
oe_obj_set_intinclude/openenv/openenv.h:225
oe_obj_set_realinclude/openenv/openenv.h:226
oe_obj_set_strinclude/openenv/openenv.h:227copies
oe_obj_set_strninclude/openenv/openenv.h:228Like oe_obj_set_str, for bytes that may contain an interior NUL.
oe_obj_set_jsoninclude/openenv/openenv.h:231Deep-copies v, bytes and all, into the arena obj was born in — so the source may die immediately afterwards.
oe_obj_set_objinclude/openenv/openenv.h:234nested
oe_obj_set_arrinclude/openenv/openenv.h:235
oe_arr_add_boolinclude/openenv/openenv.h:236
oe_arr_add_intinclude/openenv/openenv.h:237
oe_arr_add_realinclude/openenv/openenv.h:238
oe_arr_add_strinclude/openenv/openenv.h:239
oe_arr_add_objinclude/openenv/openenv.h:240
oe_arr_add_arrinclude/openenv/openenv.h:241
oe_json_objinclude/openenv/openenv.h:246
oe_json_arrinclude/openenv/openenv.h:247
oe_json_parseinclude/openenv/openenv.h:248
oe_json_dupinclude/openenv/openenv.h:249THE ONE ESCAPE FROM THE MEMORY RULE.
oe_json_writeinclude/openenv/openenv.h:254compact bytes
OE_REWARD_NULLinclude/openenv/openenv.h:281
OE_REWARD_BOOLinclude/openenv/openenv.h:282
OE_REWARD_INTinclude/openenv/openenv.h:283
OE_REWARD_REALinclude/openenv/openenv.h:284
oe_fkindinclude/openenv/openenv.h:356
kindinclude/openenv/openenv.h:371Which of the six type keywords the field publishes and which coercion the validator applies.
oe_toolinclude/openenv/openenv.h:398One tool, declared here and DEFINED in section 9.
oe_envinclude/openenv/openenv.h:428
action_fieldsinclude/openenv/openenv.h:454OE_FIELDS_END-terminated
observation_fieldsinclude/openenv/openenv.h:455schema only; the bytes we emit come from oe_obs, not here
action_schema_jsoninclude/openenv/openenv.h:457the one escape hatch:
observation_schema_jsoninclude/openenv/openenv.h:458a literal schema, sent verbatim.
state_sizeinclude/openenv/openenv.h:472zeroed per session; may be 0
initinclude/openenv/openenv.h:474optional
finiinclude/openenv/openenv.h:485optional
oe_serverinclude/openenv/openenv.h:581
oe_serveinclude/openenv/openenv.h:583blocks
oe_serve_stopinclude/openenv/openenv.h:585Async-signal-safe.
oe_server_newinclude/openenv/openenv.h:594Build a server without running it.
oe_server_fdsinclude/openenv/openenv.h:596
oe_server_tickinclude/openenv/openenv.h:597Advance the server by whatever the descriptors above just reported.
oe_server_pollinclude/openenv/openenv.h:599polls internally
oe_server_freeinclude/openenv/openenv.h:600
oe_maininclude/openenv/openenv.h:602main() for an environment binary: four flags plus a healthcheck subcommand, so a FROM-scratch container with no shell can still HEALTHCHECK itself by re-executing its own binary.
oe_clientinclude/openenv/openenv.h:653
oe_url_verdictinclude/openenv/openenv.h:674WHY A URL WILL NOT BE DIALLED, WHICH IS NOT THE SAME QUESTION AS WHETHER THE SERVER IS UP.
oe_url_verdictinclude/openenv/openenv.h:683
oe_client_url_verdictinclude/openenv/openenv.h:693Never OE_URL_OK for a URL oe_client_open would answer OE_EUSAGE for, and never anything else for one it would dial.
oe_client_reset_rawinclude/openenv/openenv.h:730
oe_client_step_rawinclude/openenv/openenv.h:731
oe_client_getinclude/openenv/openenv.h:738One of the thirteen HTTP routes, on a connection of its own — the WebSocket is upgraded and is no longer an HTTP connection.
oe_client_arenainclude/openenv/openenv.h:764Results are borrowed and die at your next call on this handle.
oe_tool_nullinclude/openenv/openenv.h:931
oe_tool_boolinclude/openenv/openenv.h:932
oe_tool_intinclude/openenv/openenv.h:933
oe_tool_realinclude/openenv/openenv.h:934
oe_tool_strinclude/openenv/openenv.h:935copies
oe_tool_objinclude/openenv/openenv.h:936empty object, fill and forget
oe_tool_arrinclude/openenv/openenv.h:938
oe_tool_failinclude/openenv/openenv.h:940The failure channel.
argsinclude/openenv/openenv.h:1002the SAME table an action uses; it generates the argument schema.
args_schema_jsoninclude/openenv/openenv.h:1007the per-tool escape hatch, and the only way to publish a schema this generator cannot produce.
hostsrc/client/client.h:35The name or numeric address to resolve: no brackets, no port, and NUL-terminated because the resolver is a C library function and takes a C string.
portsrc/client/client.h:59The TCP port: the one in the URL, or the scheme's default (80 for ws, 443 for wss).
tlssrc/client/client.h:63The URL said wss://.
oe__client_dial_parsesrc/client/client.h:71A ws:// or wss:// URL — the output of oe__client_ws_url — into the four things a socket needs.
oe_res_msgsrc/proto/client_codec.h:108
oe_ws_decodedsrc/proto/decode.h:90
oe_http_decodedsrc/proto/decode.h:162
oe_diagsrc/proto/errors.h:253The report.
oe_diagsrc/proto/errors.h:261
oe__diag_initsrc/proto/errors.h:268Zero the report and fix its origin.
oe__diag_addsrc/proto/errors.h:274Append one zeroed item and return it, or NULL when the report is full (which also latches overflowed).
oe__diag_loc_keysrc/proto/errors.h:279Append one element to an item's loc path.
oe_rpc_todosrc/proto/jsonrpc.h:181
oe_rpc_callsrc/proto/jsonrpc.h:212One dispatched request.
oe_rpc_callsrc/proto/jsonrpc.h:219
oe__rpc_messagesrc/proto/jsonrpc.h:272The composed message as a slice.
oe_pyreprsrc/proto/pyrepr.h:46The result, and the storage behind it.
oe_pyreprsrc/proto/pyrepr.h:49
oe__routessrc/proto/routes.h:112The table itself, in registration order, and its length.
oe__route_by_idsrc/proto/routes.h:118A row by id, or NULL for OE_ROUTE_NONE and for anything out of range.
oe__route_id_namesrc/proto/routes.h:121The identifier as text, for logs and test output.
OE_SCHEMA_NAME_MAXsrc/proto/schema.h:112The longest field name, and the longest environment name, this generator will render a title for.
oe_schema_fault_kindsrc/proto/schema.h:130
oe_schema_faultsrc/proto/schema.h:168Everything the server needs to name the mistake in one log line:
oe_schema_faultsrc/proto/schema.h:176
oe__schema_fault_initsrc/proto/schema.h:189
oe__schema_fault_namesrc/proto/schema.h:190
oe__tool_out_initsrc/proto/tool.h:59Zero out, record which door this call arrived on, and pre-create the result as JSON null in a.
oe_tool_msgsrc/proto/tool.h:257The storage, on the caller's stack, exactly like oe_pyrepr: the result is a C string inside it and dies with it.
oe_tool_msgsrc/proto/tool.h:260
oe__verr_addsrc/proto/validate.h:119Append one item to a report and stamp its type and msg from the slug, which is the only pair of fields that must always agree.
oe__validate_check_defaultssrc/proto/validate.h:181Parse every json_default in a table and coerce it to its declared kind.
oe_versionsrc/proto/value.c:56OUR version, and not the protocol's — there is no protocol version anywhere in OpenEnv.
oe_framingsrc/server/conn.h:131Three answers, and the third one is the interesting one: REFUSED does not mean "malformed", it means THIS WILL NEVER BECOME A WHOLE MESSAGE — stop reading and answer with what you have.
oe_framingsrc/server/conn.h:136
oe_req_scansrc/server/conn.h:142The cursor the HTTP predicate carries between calls.
oe_req_scansrc/server/conn.h:151
oe__request_completesrc/server/conn.h:157Is one whole HTTP request resident in p[0..n)?
oe__ws_frame_completesrc/server/conn.h:160Is one whole WebSocket frame resident in p[0..n)? On COMPLETE, *out_len is the frame's total size, header included.
oe_conn_statesrc/server/conn.h:177
oe_conn_cfgsrc/server/conn.h:191Everything a connection needs to know about the server it belongs to, as one const block every connection points at rather than eight copies.
oe_conn_cfgsrc/server/conn.h:198
oe_connsrc/server/conn.h:209One connection.
oe_connsrc/server/conn.h:222
oe__conn_opensrc/server/conn.h:296Take an accepted descriptor.
oe__conn_closesrc/server/conn.h:302Release the session (running the environment's fini), close the descriptor and reset the arenas so the slot is ready for the next peer.
oe__conn_releasesrc/server/conn.h:307Free the two arenas.
oe__conn_eventssrc/server/conn.h:311Which readiness this connection is waiting for, as OE_POLL_* flags.
oe__conn_finishedsrc/server/conn.h:315True once the connection has said everything it had to say.
oe__conn_expiredsrc/server/conn.h:318True when the pre-upgrade deadline has passed.
oe__conn_recvsrc/server/conn.h:321The socket half: read what is available into the input buffer, write what is pending out of the output buffer.
oe__conn_advancesrc/server/conn.h:327The state machine half: consume every complete message the input buffer holds and append every answer they are owed.
oe__conn_feedsrc/server/conn.h:333Push bytes into the input buffer as though they had arrived on the socket, and report how many fitted.
oe__conn_pendingsrc/server/conn.h:339The outbound half of the same pair: what the connection still owes the peer, and how much of it has left.
oe__conn_going_awaysrc/server/conn.h:349Begin a graceful shutdown of this connection: an open WebSocket is told 1001 "going away", anything else is closed once its answer has drained.
oe__logsrc/server/conn.h:356One diagnostic line.
oe__srv_const_routesrc/server/handlers.h:36The constant surface: /health, /metadata, /schema, /openapi.json, and the six Task API rows.
oe__srv_stateless_routesrc/server/handlers.h:56The stateless mirror: POST /reset, POST /step, GET /state.
oe__srv_mcp_routesrc/server/handlers.h:63POST /mcp.
oe__srv_mcp_bytessrc/server/handlers.h:70The JSON-RPC exchange itself, in whichever framing the caller arrived in.
oe__srv_detail_bodysrc/server/handlers.h:99{"detail":"<text>"} — Starlette's shape for a plain HTTP error, inferred from the two the corpus pins ({"detail":"Not Found"} and {"detail":"Method Not Allowed"}) and applied to the three bodies this program composes: the reason phrase of a status the corpus does not contain, the Task API's second 404, and its 501.
oe__srv_our_faultsrc/server/handlers.h:109WHOSE FAULT WAS IT — the one thing an error code cannot say on its own.
oe__srv_http_refusalsrc/server/handlers.h:128THE ONE ANSWER THAT CAN STILL BE COMPOSED WHEN NOTHING ELSE CAN.
§ 3 · [POLICY]

[POLICY]

SymbolWhereNote
oe_log_fninclude/openenv/openenv.h:510Where our diagnostics go.
portinclude/openenv/openenv.h:5190 => 8000.
hostinclude/openenv/openenv.h:524NULL => "0.0.0.0" (the observed value)
productioninclude/openenv/openenv.h:526false => simulation mode, the default and what every corpus server but one was captured in.
max_connectionsinclude/openenv/openenv.h:5470 => 64.
traceinclude/openenv/openenv.h:552dump every frame, both directions
loginclude/openenv/openenv.h:553NULL means silence
log_ctxinclude/openenv/openenv.h:554handed back to log untouched
install_signalsinclude/openenv/openenv.h:556default true for the shipped binaries; false leaves SIGTERM/SIGINT/SIGPIPE untouched, which an embedder needs.
stopinclude/openenv/openenv.h:567NULL => we use our own self-pipe.
oe_client_optsinclude/openenv/openenv.h:655
OE_RPC_MSG_MAXsrc/proto/jsonrpc.h:120The longest message this file will compose, in bytes.
oe__serve_log_stderrsrc/server/serve.h:21The log sink the shipped binaries install: one line per record on stderr, prefixed with its level, and nothing at all when tracing is off.
oe__serve_probe_healthsrc/server/serve.h:27One HTTP request against a running server, for the healthcheck subcommand: connect, GET /health, read the status line, hang up.
§ 4 · The other boundary — SAFETY:

The other boundary — SAFETY:

The threat model is one sentence: every byte from the socket is hostile. There is no authentication, no CORS and no TLS anywhere in OpenEnv, so anyone who can reach the port can reach the parser. Isolation is the container's job; refusing to crash is ours.

A SAFETY: marker is one line at a check that exists because the input is hostile, as opposed to because the format requires it. Below is every one of them. SECURITY.md is the argument these are the conclusion of.

WhereThe check
src/client/client.c:276the two spans below are written into the request line and the Host header by src/wire/ws.c, which does not inspect them. A CR or LF here would let a caller's URL write a header of its own choosing into our request, so the alphabet is checked once, here, at the parse.
src/client/client.c:700the declared length is a claim. It is checked against the ceiling by SUBTRACTION, so the comparison cannot itself overflow, and the buffer is only grown to a length that has already passed.
src/client/client.c:1476this is spliced into a request line. It is our own caller's string rather than a peer's, and it is checked all the same — the alphabet is the one the dial parser applies to a URL, for the same reason: a space would end the target early and a CR would end the line.
src/proto/decode.c:303the dedup test below is a backwards scan of this same object, so the loop is O(n^2) in the number of keys the peer sent — 128,000 of them measured at eighteen seconds of single-threaded CPU, from one unauthenticated 1.8 MB frame, on a program that runs one process by design (see OE_MAX_SESSIONS in wire/limits.h) — so that is the whole server wedged. Once the report has overflowed no later key can change a byte of the answer, so stopping here is byte-identical and bounds the total work at 33 scans.
src/proto/decode.c:332loc is the peer's own key and input is the peer's own value. Neither is formatted into anything — both reach the wire only as JSON nodes handed to the writer, which escapes them.
src/proto/decode.c:562the peer's bytes, reflected. They reach the wire only as a JSON string node handed to the writer, which escapes them and refuses to emit them if they are not UTF-8 — in which case the caller's one error check turns the 422 into the 400 of H_BAD_BODY (src/proto/errors.c, the OE_EUTF8 row), because on this path OE_EUTF8 means exactly what it says: the REQUEST BODY was not UTF-8. Observed: POST /step with content-type: text/plain and a body of \xff\xfe\xff answers 400 {"detail":"There was an error parsing the body"}. This is the one place that mapping is right; server-composed strings take the other route, through oe__srv_our_fault in src/server/handlers.h, and land on WART-19's 500.
src/proto/decode.c:905the peer's own key and value, reaching the wire only as JSON nodes handed to the writer, exactly as check_envelope_extras reflects the envelope's own extras one level up.
src/proto/errors.c:650an extra_forbidden loc is the attacker's own key. It reaches the wire only here, as a JSON string node handed to the writer, which escapes it and refuses it if it is not UTF-8.
src/proto/errors.c:765the cap and the marker, argued in errors.h section 4a and applied at all FOUR of the program's reflection sites from here — errors.c:799 (the UNKNOWN_TYPE detail), src/server/http_const.c (the Task API's environment name), src/proto/jsonrpc.c's put_reflected (which serves three sentences: an unknown session id, an unknown method, and the agent door's Tool not found: <name>), and src/proto/tool.c (the trainer door's Unknown tool: '<name>'). The last is the newest and the one an attacker reaches most cheaply, since a tool name is a string a peer picks outright.
src/proto/errors.h:372for UNKNOWN_TYPE this is the peer's own type value, rendered by src/proto/pyrepr.c and echoed back. It reaches the output only as a JSON string node handed to the writer, and errors.c puts it through oe__reflect — cap plus marker — before it goes anywhere. Every other code's detail is ours or the embedder's.
src/proto/jsonrpc.c:218the two places this file echoes a peer's bytes back INSIDE a sentence rather than as a value of its own — an unknown method name, and an unknown session id. Capped at OE_REFLECT_MAX, the same cap the Task API's reflected environment name gets, with the cut moved back to a character boundary. Everything else in a message is ours.
src/proto/jsonrpc.h:127the composer fills this buffer and stops, then moves the cut back to a UTF-8 character boundary, so an over-long message reaches the peer as a PREFIX of the right message rather than as an invalid string that would cost the whole frame (RFC 6455 section 8.1). The longest message the corpus pins is 352 bytes, so a kibibyte is threefold slack and still a fixed member of a struct a caller declares on its stack.
src/proto/jsonrpc.h:309the id is the peer's own bytes coming back, capped at OE_REFLECT_MAX on a character boundary, and it reaches the wire only as a JSON string node handed to the writer.
src/proto/jsonrpc.h:345the name is the peer's own bytes coming back inside a sentence, capped at OE_REFLECT_MAX on a character boundary, exactly like the two reflections above it.
src/proto/routes.h:149env_name is attacker-controlled and reaches an output buffer only as a JSON string node handed to the writer. *env_name is left untouched when the match is not a templated one, so a caller that forgets to check templated gets whatever it initialised, never a stale slice.
src/proto/tool.c:341THE PEER'S OWN TOOL NAME, REFLECTED — the newest of the four sites errors.h section 4a governs, and the one an attacker reaches most cheaply, since a tool name is a string a peer picks outright. oe__reflect caps it at OE_REFLECT_MAX on a UTF-8 character boundary and OE_REFLECT_MARK says that it did, so a truncation cannot be read as a short name. The buffer bound is not argued but PROVED, by the oe__tool_msg_fits array below: prefix + cap + marker + terminator must fit OE_TOOL_MSG_MAX or the file stops compiling. Measured against build/san/bin/echo_tools: a 300-byte name comes back as 64 bytes and ..., where the reference echoes all 300.
src/proto/validate.c:354the ceiling is fixed before the loop so the overflow test can be a division, which cannot itself overflow, rather than a multiplication that has already wrapped by the time it is examined.
src/proto/validate.c:483THE RANGE IS DECIDED ON THE DOUBLE SIDE, BEFORE A CAST EXISTS TO BE UNDEFINED. C99 6.3.1.4 says a floating-to-integer conversion whose integral part is outside the target type's range is UNDEFINED — not lossy, not implementation-defined — and the idiom this replaces, d != (double)(int64_t) d, is that undefined conversion written twice. It is reachable from one unauthenticated request: the JSON grammar has no bound on a number's length, so {"action":{"amount":1e400}} arrives as OE_REAL holding +inf, and a ninety-five-digit integer arrives as OE_REAL holding 6.7e94, because a number too large for int64_t is kept as a real (which is what CPython's arbitrary- precision ints degrade to here). On a sanitized build the conversion aborts, which makes one POST a remote kill.
src/proto/validate.c:832the duplicate-key test below is a backwards scan of this same object, so without this the loop is O(n^2) in the number of keys the peer sent — measured at 4.7 seconds of CPU for one 900 KB action. Once the report has overflowed no later key can change a byte, so stopping is byte-identical and bounds the work at 33 scans. The same three lines guard the other two extra="forbid" loops, in src/proto/decode.c and src/server/http_const.c.
src/server/conn.c:62detail is routinely the peer's own bytes — a request target, a frame payload — and a log line is a place an attacker would like to write a newline followed by a plausible entry of their own. Every byte outside printable ASCII becomes a dot, so nothing they send can be more than one character wide and none of it can end the line.
src/server/conn.c:785a full buffer that still holds no whole request cannot ever hold one. It is not reachable today — the head cap is enforced by the scan and the body cap by the parser, and the buffer is grown to fit whatever survives both — and it is here so that a future cap which does not add up ends as a closed socket rather than a spin.
src/server/http_const.c:72text may contain a path segment the peer chose. It reaches the output only here, as a JSON string node handed to the writer, which escapes it and refuses to emit it if it is not UTF-8. There is no format string anywhere on this path.
src/server/http_const.c:306the duplicate-key test below is a backwards scan of this same object, so without this the loop is O(n^2) in the number of keys the peer sent — 40,000 of them in a 560 KB body measured at 1.9 seconds of CPU. Once the report has overflowed no later key can change a byte, so stopping is byte-identical and bounds the work at 33 scans. The same three lines guard the other two extra="forbid" loops, in src/proto/decode.c and src/proto/validate.c.
src/server/http_const.c:496the reflected segment is the peer's own bytes, put through oe__reflect — capped at OE_REFLECT_MAX on a character boundary so an over-long path cannot inflate a response, and MARKED when the cap fired so the peer can tell sixty-four bytes from a truncation of six hundred. The reference caps nothing here; errors.h section 4a is the argument. It is written as a JSON string node either way, so it cannot forge a key.
src/wire/arena.c:129rounding up is the classic place a size wraps — align_up(SIZE_MAX) is a very small number, and a small buffer returned for a gigantic request is a heap overflow with attacker-controlled length. The addition is checked rather than masked, so an unroundable size is refused instead of shrunk.
src/wire/arena.c:146the budget test is a subtraction on the LIMIT, never reserved + n > limit, because that addition is the one an attacker-supplied n makes wrap — and a wrapped comparison passes.
src/wire/base64.c:51the arithmetic happens before the first byte is written, so a failure here leaves the destination untouched.
src/wire/buf.c:118the required capacity is the sum of two sizes, one of which came off the wire. It is added with a check, not with a +, because a wrapped total is a small allocation followed by a large memcpy.
src/wire/http.c:72the target is the one attacker-controlled span this file ever writes back out, in the location of a 307. The alphabet is enforced in TWO places — here, on the way in, and again in res_is_writable() on the way out — and that is not belt-and-braces, it is the only way the property holds for every caller. Enforcing it at parse time alone makes header injection impossible only for slices that came out of THIS file's parser; oe_http_res_write is public, the router above will hand it values routing chose, and a percent-decoded path (see the note at the top of http.h) can contain CR, LF and NUL by construction.
src/wire/http.c:347this value is reflected into the location of a 307, so it is held to the target's alphabet and not the looser one every other field value gets.
src/wire/http.c:522the gate for every span this writer reflects. Four of the six fields of an oe_http_res are spans a CALLER chose, and three of them come from the peer by way of the router. A CR or an LF in any of them ends the header block early and everything after it is a second response of the attacker's design — verified: a target carrying CRLF produces location: http://h/health\r\n x-injected: yes\r\n\r\nHTTP/1.1 200 OK....
src/wire/json_parse.c:231divide the ceiling rather than multiply the accumulator, so the overflow test cannot itself overflow.
src/wire/json_parse.c:564tested BEFORE the recursion, so a megabyte of {"a": — the largest document a server will read — costs OE_JSON_MAX_DEPTH stack frames and not one more. A depth cap applied after the call is a cap on the error message, not on the stack. (A megabyte of bare '{' is not the interesting attack: it is a missing property name, refused at byte 1, before any recursion.)
src/wire/json_parse.c:633the same cap, tested the same way, for the same reason as in oe_json_object above — and this is the shape an attacker actually sends, because '[' needs no key to nest.
src/wire/json_write.c:445a text frame carrying malformed UTF-8 obliges the peer to drop the connection (RFC 6455 section 8.1), so one bad byte from a caller costs the whole session. Refusing here turns that into an error the caller can answer with a well-formed frame. Strings that came from json_parse.c are already known good; this catches the ones that did not.
src/wire/json_write.c:502the cap json_parse.c applies on the way in, PLUS the echo headroom argued at OE_JW_MAX_DEPTH, applied again on the way out. A tree assembled in memory is not bounded by anything a parser checked, and oe_jw_json below recurses once per level. The headroom is what lets a value read at the parser's limit be written back inside an envelope.
src/wire/net.c:79read() and write() take a size_t but return a signed ssize_t, and a transfer larger than SSIZE_MAX is undefined behaviour rather than an error. Our own caps make this unreachable; it is here because "unreachable" is a property of today's callers and this is a property of the function.
src/wire/net.c:859DISARM BEFORE CLOSING. A closed descriptor number is immediately reusable, and the signal handler holds the number, not the pipe. Left armed, the next open() or accept() takes the same number and the next SIGTERM writes 0x01 into it — reproduced: wake write-end fd = 4 / newly opened fd = 4 (SAME NUMBER) / bytes injected by the handler: 1. In a server that number is overwhelmingly likely to be a live client socket, so a shutdown signal would put a stray byte into a WebSocket stream (the peer reads it as a continuation-frame header and hangs up with 1002), or into the listening socket, or into a log file. It is the one write in the program to a descriptor nobody named.
src/wire/net.c:931ONE ARMED PIPE PER PROCESS, AND THE SECOND CALLER IS REFUSED RATHER THAN QUIETLY SERVED. A signal handler takes no argument, so there is exactly one oe_wake_fd and whichever server armed last would own every SIGTERM — the first server would then never learn it had been asked to stop, and worse, freeing either one restores every disposition and disarms the other. Refusing here is what makes that visible: oe_server_new treats a failed install as non-fatal, so a second server in the same process simply runs without handlers and its embedder can still call oe_serve_stop(), which needs no signal at all. The alternative — taking over silently — is a program that appears to work and ignores a signal.
src/wire/net.c:969the global is restored if sigaction fails. Assigning it first and leaving it assigned on the failure path is the same misdirected-write bug oe_net_wake_close guards against, reached the other way round: the first pipe's handler would still be installed and would now be writing into the second pipe.
src/wire/net.c:1017zeroed first, so that a caller who ignores the return value gets a conspicuously wrong value instead of an interesting one assembled from whatever the stack happened to be holding.
src/wire/sha1.c:108memcpy with a null source is undefined even for zero bytes, and "hash nothing" is a perfectly ordinary call. Leave before touching p.
src/wire/str.c:131the overflow test divides the ceiling instead of multiplying the accumulator, so the check itself never wraps. v * 10 + d evaluated first and compared afterwards is the classic form that lets a nineteen-digit length become a small one.
src/wire/str.h:190these two are security-critical, and they are the reason this file bans atoi and sscanf rather than merely disliking them. Every length a peer declares arrives as text and passes through here: an HTTP Content-Length, a WebSocket 126/127 payload length once it has been read as digits, a chunk size. A parser that saturates, wraps, or reports 0 for both "0" and "not a number" hands an attacker the difference between the length we believe and the length we read.
src/wire/utf8.c:87classified through unsigned char, never plain char. On a signed- char target b[i] >= v->lo on a byte of 0x80 compares -128 against 128 and every multi-byte character in the stream would be rejected — or, with the comparison written the other way round, accepted.
src/wire/ws.c:36a repeated field is refused rather than resolved. HTTP permits a repeat only where the value is a comma-list, and none of these four is one, so two Sec-WebSocket-Key fields mean two parties disagree about what we are about to answer. Picking one is how a request-splitting bug starts; counting them and saying no is one line.
src/wire/ws.c:235no fallback. §4.1 wants a nonce "selected randomly"; its job is to stop a cache from replaying somebody else's completed handshake at us, and a value derived from the clock does not do that job. If the kernel will not give us entropy we do not connect.
src/wire/ws.c:656residency is decided by SUBTRACTION on what we hold, never by header_len + payload_len > n, which is the addition that wraps and lets a 2^64-3 byte claim look like a frame that has already arrived.
src/wire/ws.c:701the WHOLE frame is reserved before one byte of it is written. Writing the header first and discovering afterwards that the payload does not fit leaves a bare header announcing bytes that are not there — and oe_ws_send_close is called on the out-of-memory path, by a caller that is already failing and deliberately ignores the return, so that truncated header is what would actually go on the wire. oe_buf_reserve latches on refusal, so past this line the two appends below cannot fail independently and "half a frame is never mistaken for a frame" is a fact rather than an intention.
src/wire/ws.c:774oe_utf8_truncate finds a code-point boundary; it is NOT a validator, and it hands back the length unchanged when the byte it walked to is not a lead byte at all (see wire/utf8.h). So the bytes are checked here, before they are copied. §5.5.1 says the reason is UTF-8, and a Close whose reason is not obliges the peer to answer 1007 — turning our goodbye into its error. Every reason inside this library is an ASCII literal, so this is unreachable today; it stops being unreachable the first time the layer above wants an application message in a Close, which is a natural thing to want. Dropping the reason keeps the code, which is the half that carries the meaning.
src/wire/ws.c:956the cap is on the ACCUMULATED message, checked before every append. A per-frame cap alone lets a thousand maximal continuation frames assemble sixteen gigabytes one legal frame at a time.
src/wire/ws.c:1072rule 3 has already bounded a control payload at 125, and this says so a second time in the language the compiler checks — because the destination is a fixed array and a bound that is only true elsewhere is a bound that a future edit can delete without noticing.