feat: add governed hydrology and historical imagery

docs/API_CONTRACTS.md

@@ -191,15 +191,24 @@ Response: `DatasetRead` with extracted metadata if supported.
 
 Vector uploads remain stored as original files and are also persisted into `vector_features` as queryable PostGIS state.
 
+### GET `/api/v1/projects/{project_id}/datasets/orthophoto/products`
+
+Return the governed Digitaal Vlaanderen orthophoto product allowlist in the
+canonical envelope. Every product reports its key, display/observation label,
+temporal granularity, native resolution, colour mode, catalogue URL,
+limitations and whether current configured-YOLO detection is allowed.
+
 ### POST `/api/v1/projects/{project_id}/datasets/orthophoto/acquire`
 
-Explicitly acquire a bounded most-recent winter orthophoto selection from the
-official Digitaal Vlaanderen `OMWRGBMRVL` WMS `Ortho` layer.
+Explicitly acquire a bounded orthophoto selection from a governed official
+Digitaal Vlaanderen WMS product. Arbitrary WMS URLs and layer names are not
+accepted.
 
 ```json
 {
   "bbox": {"min_x": 5.10, "min_y": 51.17, "max_x": 5.11, "max_y": 51.18, "crs": "EPSG:4326"},
   "area_id": "optional-project-area-uuid",
+  "product_key": "most_recent",
   "force_refresh": false
 }
 ```
@@ -207,7 +216,8 @@ official Digitaal Vlaanderen `OMWRGBMRVL` WMS `Ortho` layer.
 The canonical envelope contains a synchronous Job. Its `output_dataset_id`
 identifies the raster Dataset; `result_json` contains provider, layer, pixel
 dimensions, EPSG:4326/EPSG:31370 bounds, sampling resolution, attribution,
-cache reuse and limitation text.
+cache reuse and limitation text. Historical products also persist their
+observation/validity period and a spatially scoped temporal-series key.
 
 Safety contract:
 
@@ -218,8 +228,11 @@ Safety contract:
   reuse;
 - WMS bytes are georeferenced to EPSG:31370 and persisted only through
   `DatasetService`; no fetch runs on startup;
-- this is the latest mosaic available at request time, not a historical
-  observation date for every pixel.
+- only `most_recent` can enter the current configured-YOLO plus GRB-QA path;
+  historical products are visual evidence and are never validated against the
+  current GRB state;
+- product periods such as `1979_1990` remain explicitly multi-year and are not
+  presented as exact annual observations.
 
 ### GET `/api/v1/projects/{project_id}/datasets`
 
@@ -274,6 +287,13 @@ If preview dependencies are unavailable:
 - code: `RASTER_PROCESSING_UNAVAILABLE`
 - message: `Raster preview unavailable...`
 
+### GET `/api/v1/projects/{project_id}/datasets/{dataset_id}/raster/image`
+
+Return a persisted orthophoto Dataset as a bounded browser-safe PNG. This is an
+explicit binary non-envelope endpoint used by the MapLibre image source. It
+accepts only ready datasets from the governed orthophoto provider and never
+reads arbitrary filesystem paths.
+
 ### POST `/api/v1/projects/{project_id}/datasets/{dataset_id}/raster/clip`
 
 Clip raster by selected area. Returns a `202`-style accepted job payload through the job wrapper (`jobs` create/read flow).