JSON-RPC 2.0 envelopes and MCP protocol schema validation — the wire-format floor every answer stands on.

success_response/2 and error_response/3 build the envelope every answer is sent as; Wymcp.Response does the sending. The error map is the one home for wymcp's JSON-RPC error codes: each error_type/0 atom pairs with its {code, message} tuple, so a call site names the condition and never the number. This module owns the envelope's shape; it owns no decision about which condition applies — that is each plug's and each method module's.

The error envelope's contract

One rule, four clauses, over every JSON-RPC error this module builds — the 400s and 404s that are rejections and the 200-status method errors alike:

1. code comes from the error-code table; a site names the condition, never the number.
2. message is the site's one-line cause. The table's string is what a site sends when it has nothing more to say — -32601 Method not found.
3. data is absent, or a map whose keys are drawn from a closed vocabulary of structured detail: errors (a validation failure's locations), header, expected, received (the header-binding check), supported, requested (the protocol version). No key carries a prose sentence, and no key carries the request or any part of it beyond the single value a condition is about.
4. A new structured key joins in one place — the data_keys list this module keeps beside its error-code table, which Wymcp.ErrorEnvelopeInvariantTest reads to hold every envelope to this vocabulary — the same discipline the rejection table keeps, a gate rather than a catalogue. Clause 3 names the keys for a reader; that list is what the gate is checked against.

The sentence belongs in message because that is the slot the MCP schemas define for it — "A short description of the error … a concise single sentence" — and the slot a client renders: a tools/call refused for a wrong-typed argument showed the calling model Invalid params and nothing else, measured 2026-09-10, while the cause sat under data unread.

Message and output-schema validation

The self-contained MCP protocol schema — priv/schema-2026-07-28.json, JSON Schema 2020-12 — is compiled to a JSV.Root at build time through a module attribute, so an inbound request is validated against the official protocol definition with no runtime schema parsing. Its entry point is JSONRPCMessage, which validate_mcp_request/1 validates against. @external_resource on the path makes an edit to the schema file recompile this module.

A validation failure reaches the wire as a distilled error — the envelope's message, a one-line summary, plus data.errors, one entry per instance location, locations sorted, each location's problems deduplicated — never JSV.normalize_error/1's full tree. It is a shape, not one function's return value: the producers below return the two halves as one %{message:, errors:} map, and the site that answers splits them across the envelope's two slots. This module distills it on two paths: validate_mcp_request/1 on the -32600 message path, whose reader is the human debugging a client, and validate_schema/2 on a tool's output-schema failure, which is logged and never reaches the wire. Wymcp.Methods.ToolsCall builds a conforming one by hand for the -32602 arguments path, whose reader is the calling LLM. The full tree is JSON-encodable and was what previously reached the wire; it is simply too verbose for either reader — 2353 bytes against 435 for one garbage message, measured 2026-08-15.