Add governed DHMV terrain analysis

docs/API_CONTRACTS.md

@@ -219,6 +219,49 @@ dimensions, EPSG:4326/EPSG:31370 bounds, sampling resolution, attribution,
 cache reuse and limitation text. Historical products also persist their
 observation/validity period and a spatially scoped temporal-series key.
 
+### GET `/api/v1/projects/{project_id}/datasets/dhmv/products`
+
+Returns the fixed official DHMV II product registry in the canonical envelope.
+The registry contains only `dtm_1m` (`DHMVII_DTM_1m`) and `dsm_1m`
+(`DHMVII_DSM_1m`). Each item records native 1 m resolution, EPSG:31370, TAW,
+the 2013-2015 acquisition period, attribution, catalogue and limitations.
+
+### POST `/api/v1/projects/{project_id}/datasets/dhmv/acquire`
+
+Runs a bounded WCS 2.0.1 `GetCoverage` request behind the existing synchronous
+Job abstraction. Arbitrary coverage identifiers are rejected.
+
+```json
+{
+  "bbox": {"min_x": 5.0, "min_y": 51.1, "max_x": 5.2, "max_y": 51.3, "crs": "EPSG:4326"},
+  "area_id": "optional-project-area-uuid",
+  "product_key": "dtm_1m",
+  "resolution_m": 5.0,
+  "force_refresh": false
+}
+```
+
+The service extracts the GeoTIFF from the official multipart response, clips
+to the exact persisted Area when supplied, validates EPSG:31370, one band,
+resolution, nodata and valid cells, then persists through `DatasetService`.
+The default 5 m file is an analysis copy of the retained 1 m source product;
+both resolutions and all request/response/output checksums remain provenance.
+
+### POST `/api/v1/projects/{project_id}/datasets/{dataset_id}/raster/terrain/select`
+
+Accepts an EPSG:4326 rectangle and optional Area id. It reads only a governed,
+ready DHMV Dataset and returns a canonical envelope with valid-cell coverage,
+mean/min/max/P10/P90 height in `m TAW`, relief in metres and mean/P90/max slope
+in degrees. Area geometry is an exact mask, not only a bounding box.
+
+The response always lists `water_depth_m` and `water_volume_m3` under
+`unsupported_metrics`. Drainage is not calculated by this endpoint.
+
+### GET `/api/v1/projects/{project_id}/datasets/{dataset_id}/raster/terrain/image`
+
+Returns a browser-safe PNG colour relief for the persisted governed DHMV
+Dataset. This binary MapLibre source never accepts an arbitrary file path.
+
 Safety contract:
 
 - every side must measure between 128 m and 1,024 m in EPSG:31370;