Add backend API contract audit

docs/API_CONTRACTS.md

@@ -161,6 +161,16 @@ Backend responsibilities:
 - Calculate area in square meters using projected CRS.
 - Store bbox.
 
+### GET `/api/v1/projects/{project_id}/areas/{area_id}`
+
+Returns one project area. The payload uses the same `AreaRead` shape as the
+area list endpoint and includes persisted GeoJSON geometry for map display.
+
+### PATCH `/api/v1/projects/{project_id}/areas/{area_id}`
+
+Updates the area name and/or geometry. Geometry updates follow the same
+validation, repair and metric-calculation rules as area creation.
+
 ## Datasets
 
 ### POST `/api/v1/projects/{project_id}/datasets/upload`
@@ -339,7 +349,7 @@ Apply buffer distance to vector features.
 
 Intersect source vector dataset with another vector dataset.
 
-### POST `/api/v1/projects/{project_id}/datasets/{dataset_id}/vector/stats`
+### GET `/api/v1/projects/{project_id}/datasets/{dataset_id}/vector/stats`
 
 Return vector stats (feature counts and geometry summary).
 
@@ -347,6 +357,12 @@ Return vector stats (feature counts and geometry summary).
 
 Return vector bounds and feature count.
 
+### GET `/api/v1/projects/{project_id}/datasets/{dataset_id}/content`
+
+Returns stored vector dataset content through the canonical API envelope.
+Vector content is returned as GeoJSON/JSON payload data. Raster content is not
+served through this endpoint.
+
 ## Jobs
 
 ### POST `/api/v1/projects/{project_id}/jobs`
@@ -670,11 +686,12 @@ Response persists a `quality_check` and `metrics` rows through the existing QA/Q
 
 If the reference dataset has no persisted vector features, the endpoint returns `REFERENCE_FEATURES_NOT_FOUND`. It does not calculate fake QA metrics.
 
-### POST `/api/v1/analysis/building-stats`
+#### Future analysis route: `/api/v1/analysis/building-stats`
 
-Input: area + vector building layer.
+Not implemented in the active API surface. Future input is expected to combine
+an area with a vector building layer.
 
-### POST `/api/v1/analysis/object-detection`
+#### Future analysis route: `/api/v1/analysis/object-detection`
 
 Request:
 
@@ -693,7 +710,7 @@ Request:
 
 Response: `AnalysisRunRead`.
 
-### POST `/api/v1/analysis/segmentation`
+#### Future analysis route: `/api/v1/analysis/segmentation`
 
 Same pattern as object detection, but output includes masks and polygonized geometries.
 
@@ -1027,7 +1044,7 @@ intentionally does not use the JSON envelope because it is a browser/file-downlo
 path; callers that need canonical API JSON should use `/content` for JSON/GeoJSON
 artifacts.
 
-### POST `/api/v1/exports/yolo`
+#### Future export route: `/api/v1/exports/yolo`
 
 Export annotations/detections to YOLO format.
 

docs/CODEX_EXECUTION_LOG.md

@@ -1,3 +1,38 @@
+## Sprint 48 Backend API contract audit (2026-06-17)
+
+Changed:
+- Added `scripts/audit_api_contracts.py` to import the FastAPI app, enumerate the implemented `GET`/`POST`/`PATCH`/`DELETE` route surface and compare it with active `### METHOD route` headings in `docs/API_CONTRACTS.md`.
+- Added the API contract audit to `scripts/run_readiness_check.sh`.
+- Corrected contract drift in `docs/API_CONTRACTS.md`:
+  - documented `GET/PATCH /api/v1/projects/{project_id}/areas/{area_id}`;
+  - corrected vector stats from `POST` to implemented `GET`;
+  - documented `GET /api/v1/projects/{project_id}/datasets/{dataset_id}/content`;
+  - changed non-implemented building-stats, legacy analysis object-detection/segmentation and YOLO export entries from active route headings to future-route notes.
+- Added `backend/tests/test_sprint48_api_contract_audit.py`.
+- Updated `scripts/README.md`, `docs/TODO.md` and `CHANGELOG.md`.
+
+Validation:
+- RED: `cd backend && python -m pytest tests/test_sprint48_api_contract_audit.py -q` failed before implementation because the audit script, readiness integration and route docs were missing.
+- RED: `python scripts/audit_api_contracts.py` reported missing docs for 4 implemented routes and 5 stale documented routes.
+- `python scripts/audit_api_contracts.py` passed: 76 implemented routes matched docs and 2 explicit non-envelope endpoints were tracked.
+- `cd backend && python -m pytest tests/test_sprint48_api_contract_audit.py tests/test_readiness_gate.py -q` passed: 12 tests.
+- `python -m py_compile scripts/audit_api_contracts.py` passed.
+- `python -m compileall backend/app` passed.
+- `cd backend && python -m pytest -W error::DeprecationWarning` passed: 201 tests.
+- `bash scripts/run_readiness_check.sh` passed and included `API contract audit OK`.
+- `cd frontend && npm run typecheck` passed.
+- `cd frontend && npm run build` passed.
+- `cd backend && python -m alembic heads` passed: `202606120900 (head)`.
+- `cd backend && python -m alembic upgrade head --sql` passed.
+- `bash -n scripts/live_migration_smoke.sh` passed.
+
+Limitations:
+- This pass audits route documentation presence, implemented/stale route drift and explicit non-envelope exceptions. It does not yet exercise every error path response body at runtime.
+- No API behavior, migrations, provider fetching, AI behavior or product capabilities changed.
+
+Next recommended pass:
+- Add an error-envelope runtime audit for representative invalid/missing-resource paths across projects, datasets, providers, detection, segmentation, QA and exports.
+
 ## Sprint 47 Workbench interaction smoke (2026-06-17)
 
 Changed:

docs/TODO.md

@@ -43,6 +43,7 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Dry-run-first demo export artifact cleanup tooling.
 - [x] Browser-facing default workbench state smoke for the offline demo project.
 - [x] Browser-facing workbench interaction backing-state smoke and stable UI test anchors.
+- [x] Backend API contract audit comparing implemented FastAPI routes with `docs/API_CONTRACTS.md`.
 - [x] Live Docker/PostGIS validation on Tower/Unraid.
 - [x] Real YOLO compatibility smoke with optional AI extras and local model file.
 - [x] Detection and segmentation workflow hook extraction beyond Sprint 10.
@@ -58,7 +59,7 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Demo workflow orchestration hook decomposition.
 - [x] Final `App.tsx` import/encoding cleanup and size audit.
 - [x] Optional final bootstrap-effect extraction.
-- [ ] Decide next V1 stabilization focus: browser screenshot artifact automation, backend service contract audit, or golden dataset expansion.
+- [ ] Decide next V1 stabilization focus: browser screenshot artifact automation, backend error-envelope audit, or golden dataset expansion.
 
 ## Sprint 8 status