feat(ADM-018): completed feature

legacy/specs-old/F-003-http-foundation/SPEC.md

@@ -0,0 +1,37 @@
+# SPEC — F-003 HTTP foundation and request context
+
+## Problem
+Every request needs identity, structured logs and predictable errors. Today the app
+answers with ad-hoc console logging potential, no request correlation id, and an
+error envelope without request context.
+
+## Goal
+request_id everywhere, JSON logs, one error envelope, no magic.
+
+## Scope IN
+- request_id generated or propagated on every request
+- Structured JSON logging with request_id
+- Single error response envelope (v2: adds stable `code` + `requestId`)
+- Input validation hook on API layer (foundation helper, explicit usage)
+
+## Scope OUT
+- No tracing backend
+- No metrics backend
+- No production endpoints that consume validation yet (first consumer: F-005 identity)
+
+## Acceptance criteria
+1. Every response carries `request_id` (via `x-request-id` response header; error bodies also embed it).
+2. Every log line for a request carries the same request_id.
+3. Given an invalid request When handled Then the error envelope shape is stable.
+4. Internal stack traces never leak to API responses (5xx message is generic; stack stays server-side in logs).
+5. `./scripts/verify.sh` green.
+
+## Non-functional
+- JSON-only logs (no pretty printers in runtime).
+- Incoming `x-request-id` must be sanitized before reuse (length/charset limits).
+- No new framework magic: logging hooks and error handler are explicit code in the composition root.
+
+## Dependencies added
+- pino (JSON structured logging; Fastify ecosystem standard)
+- zod (explicit input validation; no decorators/annotations magic)
+Justification goes to `spec/tech.md`.