Story 1453: ErrorResponse.correlation_id → trace_id (R7a)

Why this exists (the catastrophe it prevents). When a domain error reaches a client, the body carries one field whose entire job is “paste this into support and they will find your request.” Until now that field was correlation_id — a per-request UUID minted by PRAMAAN’s own correlation layer. But the system PRAMAAN actually stores traces in is X-Ray/CloudWatch, keyed by the OpenTelemetry trace id, not by that UUID. So an operator handed a correlation_id had to first reverse-map it to a trace before they could see anything — and off the connected graph there was no clean mapping at all. The error body advertised a lookup key that did not open the lock. EPIC-1400 Phase-2 (roster id R7a) renames the published field to trace_id and sources it from the live trace, so the value in the body is the exact trace a human can open in X-Ray. pramaan-docs ADR-124 governs the trace identity this rides on.

The Fix: One Field, Sourced From the Real Trace

The published ErrorResponse field is renamed, and every place that writes that field now reads the active span’s trace id through one helper. Nothing about how the error envelope is shaped (nested error object, codes, messages, details) changed.

any error response (PramaanError envelope, 422, 404, framework 500)
  -> trace_id = get_current_trace_id()          <- NEW single source
       span_context = trace.get_current_span().get_span_context()
       return format_trace_id(span_context.trace_id) if span_context.is_valid else None

ErrorResponse  ==  { "error": { code, message, details }, "trace_id": "0af7651916cd43dd8448eb211c80319c" }

• src/shared/dtos/errors.py — the published ErrorResponse.correlation_id field becomes trace_id. This is the canonical contract; app #1454 and admin #1455 regenerate their clients against it.
• src/shared/observability/trace_context.py (new) — get_current_trace_id() returns the active span’s trace id as 32-char W3C/X-Ray hex, or None off a valid span. It is the single home for the raw trace.get_current_span() read, so the tracer access stays inside the observability package (pramaan-docs ADR-104, pramaan-docs ADR-124); callers in other packages import the helper instead of touching the tracer.
• src/shared/errors/http_handler.py — the PramaanError handler stamps trace_id from get_current_trace_id() instead of the correlation value.
• src/shared/observability/middleware.py — the error-body backfill (FastAPI 422 validation, Starlette 404/405, framework 500) and the catch-all 500 also publish trace_id, so the whole error surface — not just the PramaanError envelope — round-trips the published ErrorResponse.
• openapi/app-api.json, openapi/admin-api.json — regenerated via make openapi; both snapshots reflect trace_id.

Why the Middleware Body Field Had To Move Too

It would have been smaller to touch only the DTO and the PramaanError handler. That fails a repo invariant: the published DTO must round-trip the real wire body. CorrelationIdMiddleware backfills a correlation surface onto every ≥400 JSON body. Leaving that backfill on correlation_id would have shipped { error, trace_id, correlation_id } — an undocumented third field that ErrorResponse cannot round-trip, i.e. first-class contract drift. Repointing only the response body field keeps the envelope honest across the full error surface.

Where the Field Is Written

The backfill skips any body that already self-publishes a correlation surface (its own trace_id, or a DTO field like HealthResponse.correlation_id), so the envelope is stamped exactly once and out-of-scope DTOs are left untouched.

Acceptance Evidence

Full suite green against the isolated Docker test DB (977 passed); ruff clean, mypy clean on changed source, and make openapi regeneration is idempotent.