fix(api): v1 OpenAPI misdeclares 422 shape and the SSE events response

[pparage]

The committed openapi.json bootstraps the Kong gateway and is what clients would be generated from, but two v1 response contracts in it do not match what the app actually returns. Both are route-declaration gaps, not spec-generation bugs — the spec faithfully reports what FastAPI is told.

Surfaced by Codex review on #115.

1. 422 body shape

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

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

…but every v1 operation still advertises FastAPI's default HTTPValidationError ({"detail": [...]}). Generated clients will deserialize validation failures with the wrong shape. Affects all v1 routes, not just POST /v1/projects/.

Fix: a shared responses={422: {"model": <envelope model>}} default, ideally set once at router level rather than per route.

2. SSE stream documented as JSON

GET /v1/deployments/{deployment_id}/events returns EventSourceResponse (app/routes/v1/deployments/events.py), so successful responses are text/event-stream. The spec advertises application/json, so a consumer generated from it will await a JSON body instead of opening a stream.

Fix: response_class=EventSourceResponse and/or an explicit text/event-stream response declaration.

Notes

Both were invisible until #115 regenerated the spec, because the committed file had rotted back to the pre-v1 API (84 paths, zero /v1). Regenerating after this lands is required for the fix to reach Kong — see the drift-guard issue.

[pparage]

Closed by #136.

Both halves fixed and pinned by tests. ErrorEnvelope is declared once on the aggregate v1 router, so all 48 operations inherit it and a new v1 route gets it automatically. The SSE stream is declared with response_class=EventSourceResponse plus an explicit text/event-stream response.

The load-bearing test asserts a real 422 body and the declared schema have the same keys — asserting on the spec alone would let the declaration and the handler drift together, which is how this existed in the first place.

v0 still advertises FastAPI's default 422 deliberately: those routes do not go through the v1 handlers and are on the decom track, so aligning them would be churn on surface we intend to delete.