feat(ir)!: make ErrorCase a response: name, headers, media types

[fuad-daoud]

Closes #422. Breaking, and the largest change in the stack.

Closes #433.

ir.ErrorCase and ir.Response were not siblings. Responses split by status — 2xx/3xx to Response, 4xx/5xx/default to ErrorCase — and the two nodes were shaped differently:

	Response	ErrorCase before
status spelling	Name.Hint = "200"	nothing — only a provenance pointer
headers	Headers []Property	absent, dumped to Unmodeled
content	all media types	one bare TypeRef, the rest dumped

So anything a consumer did with responses behaved differently by status class, silently. Retry-After and rate-limit headers live on 429 and 503 — precisely the side with no typed home. A 4xx declaring two media types kept one and lost the media-type key entirely.

703 occurrences of "error response media type has no ErrorCase home" across GitHub and Stripe.

ErrorCase now lowers through the same helpers as the success path — responseName, lowerHeaders, lowerPayload. Four functions that existed only because of the gap are deleted, and with them two info diagnostics and the openapi:headers / openapi:content writes.

pass/validate.go grows the fourth Payload carrier, reached at both positions an ErrorCase hangs from — Operation.Errors and Service.CommonErrors. The completeness guard TestEncodingCarriers_NameEveryPayloadFieldInTheIR fired on its own and named it.

The conformance fixture gained a 429 declaring two media types and two rate-limit headers, so the new fields are witnessed, not merely present — deleting either reddens the case.

BREAKING CHANGE: ErrorCase.type is removed; name, payload and headers take its place. A 0.3.0 consumer finds no type on an error case and cannot reach its models at all.

---

Stack 4 of 8. Base stack/3-ir-fields — review and merge bottom-up. Every commit here passed make gate when it landed, and the full gate was re-run on the top of the stack. Run it as GOTOOLCHAIN=go1.26.3 make gate; this machine's Go 1.27 fails it for reasons unrelated to any change (#431).

🤖 Generated with Claude Code

https://claude.ai/code/session_01SYeBgDsskwnyitLgPGCPn1

---

Review round 2 (commit 2)

Addresses the review on this PR. Every finding was reproduced by execution first.

A shared response across the status boundary produced order-dependent IR — this is #433, filed on 2026-09-07 and left standing; closed here. A components/responses entry mounted at both a success and an error status lowers through lowerResponse and lowerErrorCase, which passed payload hints "response" and "error"; both intern the body at the same declaration pointer, so the two mints raced and the loser's hint was discarded — reversing the two keys renamed the type. Both hints now come from ids.DeclarationHint on the declaration pointer, which is one pointer whichever side reaches it first. Confirmed on the base branch too, so the behaviour predates this PR; what was new is the prose claiming symmetry, corrected here and in the ir-design.md matrix row.

Nothing in the corpus asked the question — component-reuse.yaml mounts Listed only at 200s and Failure only at default — so the order oracle never fired on it. shared-response-across-status.yaml is added to close that, and it reproduced the exact Hint: "response" ↔ "error" diff before the fix.

Two responses-map keys can name one range. "4XX" beside "4xx" compiled with exit 0 to two error cases identical in name and conditions. Now reported as openapi/duplicate-status-key, a warning, with both kept — neither key is wrong on its own, and dropping one picks a winner on declaration order.

Naming.Source was the other candidate and is not available. A responses-map key is not a name the document declared — TestResponses_NamedByStatusKey pins Source empty for both sides — and setting it without a derived Canonical breaks the pairing NamingFor holds, which irverify reports as ir/naming-not-derived. So the four sites claiming the key reaches the IR "as written" are corrected instead: it is neutralized, 5XX arrives as 5_xx, and only default round-trips.

Nothing pinned that the walk reaches ErrorCase.Name or ErrorCase.Headers. Planting a skip for either left the whole suite green, exactly as reported, where the Response twins and ErrorCase.Payload each redden a test. Both are guarded now — an "error case" row in TestVerify_NamelessServerAndResponseAreViolations and a ghost header on the error case in TestValidate_OperationHeadersAndItemWalked (count 3 → 4) — and each was re-confirmed to redden under its planted skip.

Also: the ErrorCase GoDoc no longer claims the two nodes differ only in fault classification, and records why StatusCodeProp stays success-only (the formats that populate a member from the status line classify errors by @httpError instead); checkEncodingKeys addresses a service by ID as checkServerIndices does rather than positionally, so one node stops having three spellings from one package; and the corpus justification in verify_corpus_test.go names the real reason, since both things it claimed the corpus does not reach are reached by it.

Known gap, deferred

• PlannedError has no Headers and no media-type election now that ErrorCase is a response #447 — PlannedError has no Headers field, so Retry-After has no home in the plan, and its single Type names no election where ErrorCase.Payload.Contents is plural. The worked example's plan line contradicts the IR line above it. Stated in emitter-design.md beside that example. It is emitter-design work — a new plan field plus an election rule — rather than a correction to what this PR changed.

[Wahbeh-Mohammad]

Two-pass review (design/coherence, then adversarial), every item re-verified by execution against the branch head. Suite and 100% coverage gate green under GOTOOLCHAIN=go1.26.3; goldens consistently regenerated (no type left on any error case, no openapi:headers/openapi:content residue); the 429 fixture witnesses headers and two media types; both checkEncodingKeys carriers are independently guarded.

Seven inline comments, roughly in severity order: walk reachability of the new fields is unguarded; the "key as written" claim is false and hides a silent 4XX/4xx collision; shared response components across the status boundary are order-dependent while the new prose claims symmetry; PlannedError in emitter-design.md was not updated; one imprecise universal in the ErrorCase GoDoc; a positional pointer in pass/validate.go; a stale justification in verify_corpus_test.go.

[Wahbeh-Mohammad]

Review done by me + fable