Add governed GRB refresh workflow

docs/API_CONTRACTS.md

@@ -432,6 +432,30 @@ not fetch vector features, raster pixels or models, create jobs/datasets, write
 to PostGIS or trigger an import. The normal `source-freshness` endpoint remains
 local-only and never invokes this probe implicitly.
 
+### GET `/api/v1/projects/{project_id}/datasets/grb-refresh-plan`
+
+Builds a read-only refresh decision for the governed
+`kempen-transport-region` GRB snapshot series. Query parameter
+`refresh_catalog=true` explicitly bypasses the catalog cache. The response
+maps the official dated edition to `buildings`, `roads`, `water` and `parcels`
+and reports each latest local Dataset, source version, observation date,
+feature count, artifact size and refresh state.
+
+Layer state is `current`, `update_available`, `not_loaded`, `review_required`
+or `remote_unavailable`. The summary reports how many new immutable Datasets
+would be created and how many existing snapshots remain retained. The endpoint
+does not fetch GRB features, stage files, create a Job, write to PostGIS or
+start an operator process. Exact remote deltas remain unavailable until every
+municipality partition has been staged and validated.
+
+Regional execution uses `scripts/manage_grb_refresh.py` outside the request
+cycle. `stage` requires the exact official ISO edition, invokes the existing
+regional GRB operators with `--fetch-only`, validates all artifact/partition
+checksums and emits a SHA-256-bound plan. `apply` requires that exact plan hash,
+revalidates every staged byte and delegates persistence to DatasetService and
+VectorFeatureService. It creates new temporal snapshots and never deletes or
+overwrites an older Dataset.
+
 ### GET `/api/v1/projects/{project_id}/datasets/{dataset_id}`
 
 Return metadata.