Add bounded GRB map acquisition

docs/API_CONTRACTS.md

@@ -64,23 +64,23 @@ Returns enabled feature flags and tool availability.
   "geopandas": true,
   "yolo": false,
   "sam": false,
-  "grb": "planned",
+  "grb": "bounded",
   "sentinel": "planned",
   "providers": [
     {
       "provider_name": "grb",
       "display_name": "GRB",
       "authority_level": "authoritative",
-      "supported_layers": ["buildings", "roads", "parcels"],
+      "supported_layers": ["buildings", "roads", "water", "parcels"],
       "supported_geometry_types": ["Polygon", "MultiPolygon", "LineString", "MultiLineString"],
-      "supported_query_modes": ["area"],
-      "fetch_signature": "POST /api/v1/external/grb/fetch",
-      "configured": false,
-      "status": "not_configured",
-      "limitation_message": "GRB live WFS/download integration is not configured in Sprint 7B.",
-      "attribution": "Digitaal Vlaanderen - Basiskaart Vlaanderen (GRB)",
-      "license_note": "Use must follow Digitaal Vlaanderen open data and attribution terms.",
-      "not_configured_reason": "Provider integration is not configured yet"
+      "supported_query_modes": ["bbox", "persisted_area"],
+      "fetch_signature": "POST /api/v1/projects/{project_id}/datasets/grb/acquire",
+      "configured": true,
+      "status": "configured",
+      "limitation_message": "Alleen expliciet begrensde selecties tot 20 km per zijde worden opgehaald.",
+      "attribution": "Bron: Grootschalig Referentie Bestand Vlaanderen, Digitaal Vlaanderen",
+      "license_note": "Hergebruik volgens de open-datavoorwaarden en bronvermelding van Digitaal Vlaanderen.",
+      "not_configured_reason": null
     }
   ]
 }
@@ -233,6 +233,45 @@ 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/grb/products`
+
+Returns the fixed official GRB vector registry in the canonical envelope.
+Only `buildings` (`GBG`), `roads` (`Wegsegment`), `water`
+(`WTZ`/`WLAS`/`WGR`) and `parcels` (`ADP`) are exposed. Each product reports
+its exact source collections, supported geometry types, attribution, licence
+and semantic limitation.
+
+### POST `/api/v1/projects/{project_id}/datasets/grb/acquire`
+
+Acquires one explicitly bounded GRB product from the allowlisted Digitaal
+Vlaanderen OGC API Features service behind the synchronous Job abstraction:
+
+```json
+{
+  "bbox": {"min_x": 5.12, "min_y": 51.18, "max_x": 5.17, "max_y": 51.22, "crs": "EPSG:4326"},
+  "area_id": "optional-project-area-uuid",
+  "product_key": "buildings",
+  "force_refresh": false
+}
+```
+
+The backend requires EPSG:4326, intersects the rectangle with the optional
+persisted Area, rejects sides below 10 m or above 20 km, follows only
+same-host allowlisted collection pagination and fails instead of truncating
+when page, transfer or feature limits are reached. Every official feature id,
+request URL, response checksum and artifact checksum remains provenance.
+Although GRB is stored natively in EPSG:31370, the service explicitly
+negotiates OGC CRS84 longitude/latitude GeoJSON for both bbox and output before
+performing the exact geometry intersection.
+
+Output is an ordinary reference Dataset persisted through `DatasetService`,
+`DatasetVersion` and `VectorFeatureService`; providers never write directly
+to `vector_features`. Exact requests are reused for 24 hours unless
+`force_refresh=true`. Selection metrics are footprint hectares for buildings,
+line kilometres for roads, hectares plus supporting line kilometres for
+water, and hectares for parcels. Water volume is unsupported because GRB
+contains no depth or bathymetry.
+
 ### GET `/api/v1/projects/{project_id}/datasets/dhmv/products`
 
 Returns the fixed official DHMV II product registry in the canonical envelope.
@@ -898,7 +937,8 @@ Returns configured/status/limitation fields.
 
 ### POST `/api/v1/external/providers/{provider_name}/import`
 
-Defines the future provider import contract. Sprint 7B does not perform live imports or write datasets.
+Compatibility contract for provider-specific import flows. It never writes
+datasets itself.
 
 Request:
 
@@ -911,13 +951,13 @@ Request:
 }
 ```
 
-GRB/OSM response:
+GRB response:
 
 ```json
 {
   "provider_name": "grb",
-  "status": "not_configured",
-  "message": "No live GRB import is configured in Sprint 7B.",
+  "status": "bounded_request_required",
+  "message": "Use the governed project GRB acquisition endpoint with an EPSG:4326 bounding box and one supported layer.",
   "requested_layers": ["buildings"],
   "dataset_id": null,
   "dataset_role": "reference",
@@ -925,7 +965,10 @@ GRB/OSM response:
 }
 ```
 
-Manual and fixture providers point callers to existing upload/fixture flows. No provider writes directly to `vector_features`; all future provider output must flow through `DatasetService` and `VectorFeatureService`.
+OSM still returns `not_configured`. Manual and fixture providers point callers
+to existing upload/fixture flows. No provider writes directly to
+`vector_features`; the bounded GRB integration and all future provider output
+flow through `DatasetService` and `VectorFeatureService`.
 
 ## External data fetchers
 
@@ -953,7 +996,10 @@ Request:
 }
 ```
 
-V1 may initially implement this as a service interface with a clear `not_configured` response until the exact WFS endpoint is wired.
+This legacy compatibility endpoint never fetches. It returns
+`bounded_request_required` and directs callers to
+`POST /api/v1/projects/{project_id}/datasets/grb/acquire`, where bbox, Area,
+product allowlist, limits and persistence are enforceable.
 
 Sprint 7B provider contract responses expose capabilities only. Providers must report:
 
@@ -973,7 +1019,8 @@ Sprint 7B provider contract responses expose capabilities only. Providers must r
 }
 ```
 
-No GRB WFS, OSM Overpass or provider downloads are implemented in Sprint 7B.
+No unbounded GRB WFS download or OSM Overpass integration is implemented.
+Bounded GRB OGC API Features acquisition is documented under Datasets.
 
 ## Demo workflow
 
@@ -1518,7 +1565,8 @@ GeoJSON feature properties include:
 
 Limitations:
 
-- No live GRB/OSM/Sentinel fetching.
+- Change detection itself performs no provider fetch. Bounded GRB acquisition
+  is a separate explicit Dataset operation; OSM and Sentinel remain disabled.
 - No fake object lifecycle classification.
 - No `changed` classification without durable object ids/versioning.
 - No first-class change table yet; the current output is stored in job