fix(api): declare the real v1 error envelope and the SSE content type (#116)

[pparage]

Closes #116. Both findings originally from Codex review on #115.

The committed spec bootstraps the Kong gateway and is what clients would be generated from, so a wrong declaration is not cosmetic — it produces clients that mis-parse real responses.

422 shape

app/core/errors installs a RequestValidationError handler returning the Range42 envelope:

{"error": "...", "message": "...", "code": "...", "details": [...], "trace_id": "...", "timestamp": "..."}

…while all 48 v1 operations advertised FastAPI's default {"detail": [...]}.

Added ErrorEnvelope (mirroring _envelope()) and declared it once on the aggregate v1 router via responses=, so every operation inherits it rather than 48 routes each repeating the same block — and a new v1 route gets it automatically.

SSE content type

/v1/deployments/{deployment_id}/events returns EventSourceResponse, so its body is text/event-stream. The spec said application/json, which would have a generated consumer awaiting a body that never completes instead of opening a stream. Now declared with response_class plus an explicit text/event-stream response.

Tests

Three, all failing against dev:

FAILED test_a_real_422_matches_the_declared_schema
FAILED test_no_v1_operation_still_declares_the_fastapi_default
FAILED test_events_stream_is_declared_as_sse

The first is the important one: it POSTs an invalid body, reads the real 422, and asserts its keys match the declared schema's properties. Asserting on the spec alone would let the declaration and the handler drift together — which is exactly how this bug existed in the first place.

Deliberately not changed

The 48 v0 operations still advertise the default 422. They do not go through the v1 handlers, and they are on the decom track (#113 removed a large chunk already), so aligning them would be churn on surface we intend to delete. Verified the remaining HTTPValidationError references are v0-only.

491 passed, ruff clean, spec regenerated — and #134's drift guard now enforces that.