Harden RC7 API response contracts

docs/API_CONTRACTS.md

@@ -9,6 +9,12 @@ This document freezes the first API shape. Codex may add implementation details
 - GeoJSON accepted for geometries where possible.
 - Long processing tasks return a job or analysis run record instead of blocking.
 - Error responses use the shared `ApiError` schema.
+- Every successful JSON endpoint has a concrete Pydantic response model and
+  uses the canonical `{"data": ...}` envelope. Readiness runs an OpenAPI audit
+  that rejects free-form dictionary responses and envelope drift.
+- The only successful non-envelope responses are `/health`, `/health/live`,
+  `/health/ready`, the four documented persisted-raster PNG endpoints and the
+  export artifact download endpoint.
 
 ## Shared schemas
 

docs/CODEX_EXECUTION_LOG.md

@@ -10516,3 +10516,33 @@ Decision:
 
 - RC-6 is complete. RC-7 critical API response typing and OpenAPI validation
   is active.
+
+## 2026-07-18 - Belgium/North Sea RC-7 API contract hardening
+
+Implemented:
+
+- Replaced every remaining free-form successful JSON response model with a
+  concrete Pydantic schema while retaining the canonical `{"data": ...}`
+  payload shape.
+- Added reusable generic envelope, list, pagination and GeoJSON schemas plus
+  concrete project, area, assistant, YOLO preflight and QA evidence models.
+- Corrected Area serialization so persisted PostGIS geometries are converted
+  to GeoJSON before response validation.
+- Added an executable OpenAPI contract audit and focused regression tests that
+  reject missing, free-dictionary or undocumented non-envelope responses.
+- Tracked exactly eight deliberate exceptions: three health probes, four
+  persisted PNG endpoints and the streamed export download.
+
+Validation:
+
+- The API audit passed 124 implemented routes and 228 OpenAPI component
+  schemas.
+- Repository readiness passed backend compilation, 1,008 backend tests,
+  Alembic head `202607160001`, frontend typecheck and production build.
+- Offline `alembic upgrade head --sql` completed and generated 31,548 bytes of
+  migration evidence.
+
+Decision:
+
+- RC-7 is complete. RC-8 automated frontend and browser release journeys are
+  active.

docs/RC_ROADMAP_BELGIUM_NORTH_SEA.md

@@ -150,8 +150,8 @@ editions and licences must still pass source-specific probes before activation.
 | RC-4 | complete | national/maritime scope and provider coverage contracts |
 | RC-5 | complete | deployment, secrets, configuration, fresh install and rollback |
 | RC-6 | complete | complete CI, dependency and supply-chain gates |
-| RC-7 | in progress | critical API envelope typing and contract validation |
-| RC-8 | pending | frontend and browser E2E release journeys |
+| RC-7 | complete | critical API envelope typing and contract validation |
+| RC-8 | in progress | frontend and browser E2E release journeys |
 | RC-9 | pending | loading, accessibility and performance hardening |
 | RC-10 | pending | retention, cleanup and national data operations |
 | RC-11 | pending | final package, upgrade proof, release tag and handoff |
@@ -405,6 +405,13 @@ UID 999.
 
 ## RC-7 - Critical API contract hardening
 
+**State: complete.** All successful JSON routes now publish concrete OpenAPI
+response schemas. The contract audit covers 124 implemented routes and 228
+component schemas; the eight non-envelope operations are the three health
+probes, four persisted PNG responses and the export download. Readiness passed
+with 1,008 backend tests, frontend typecheck/build, one Alembic head and
+offline migration SQL generation.
+
 ### Work
 
 - replace `response_model=dict` first on health, projects, areas, datasets,

docs/TODO.md

@@ -25,7 +25,7 @@ maritieme zones.
 - [x] RC-5: secrets/configuratie/uploadlimieten/immutable deploy en rollback
   bewijzen.
 - [x] RC-6: volledige CI, dependency-audit, containerscan en SBOM toevoegen.
-- [ ] RC-7: kritieke API-routes concrete responsemodellen geven.
+- [x] RC-7: kritieke API-routes concrete responsemodellen geven.
 - [ ] RC-8: echte frontend- en browser-E2E-releaseflows toevoegen.
 - [ ] RC-9: loading, toegankelijkheid, widescreen/mobile en performance afronden.
 - [ ] RC-10: dataretentie, diskdruk en veilige cleanup operationaliseren.