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.

docs/CODEX_EXECUTION_LOG.md

@@ -9339,3 +9339,36 @@ Next:
 - Extend the same probe pattern only where another official source publishes a
   stable machine-readable edition. Do not infer release versions from service
   protocol versions, ETags or HTTP modification dates.
+
+## Sprint 223 - Governed regional GRB refresh (2026-07-16)
+
+Implemented:
+- Added a canonical read-only refresh plan that maps the official dated GRB
+  edition onto the immutable regional buildings, roads, water and parcel
+  temporal series.
+- Added explicit per-layer current/update/review states, existing Dataset,
+  feature/storage impact and non-destructive action guidance.
+- Added `manage_grb_refresh.py` with separate plan, fetch-only stage and
+  checksum-confirmed apply phases. Stage validates all retained artifacts and
+  municipality partitions; apply revalidates the exact staged plan before
+  calling the existing regional DatasetService-based operators.
+- Added a compact Status surface after the explicit official catalog check.
+
+Boundaries:
+- No migration, scheduler, arbitrary provider URL, browser-triggered heavy
+  import, direct vector-feature write or automatic Dataset replacement was
+  introduced.
+- Existing GRB snapshots remain immutable historical observations. Exact
+  remote deltas are reported only after full staging, never guessed from
+  capabilities metadata.
+
+Validation so far:
+- Backend compile and frontend typecheck passed.
+- Source-catalog plus governed-refresh focused suite passed: 20 tests.
+- Full `scripts/run_readiness_check.sh` passed: 779 backend tests, 110
+  documented route contracts, one Alembic head, frontend typecheck/build and
+  all packaged smoke checks.
+
+Next:
+- Run the full release gate, deploy to Tower, execute a live read-only plan and
+  then stage/apply only the exact confirmed official edition.

docs/DATABASE_IMPLEMENTATION_PLAN.md

@@ -267,6 +267,13 @@ evidence audit. External catalogue checks and refresh jobs remain explicit
 operator actions; they may never overwrite a fixed edition or scenario in
 place.
 
+Regional GRB refreshes add no lifecycle table. A read-only plan compares the
+official dated edition with the latest Dataset in each governed temporal
+series. Staging is filesystem evidence only. Checksum-confirmed apply creates a
+new Dataset plus DatasetVersion and vector_features through the existing
+DatasetService/VectorFeatureService transaction; prior snapshots remain
+unchanged and queryable for temporal comparison.
+
 ## Geometry normalization
 
 - User-drawn polygons arrive as EPSG:4326.

docs/TODO.md

@@ -40,6 +40,7 @@
 - [x] Present municipal DHMV/VMM partitions as logical regional layers and analyse cross-boundary rectangles without a municipality prerequisite.
 - [x] Add a read-only source freshness/version audit with explicit publication policies, local integrity checks, operator CLI and compact Status workspace surface.
 - [x] Add explicit bounded GRB/orthophoto catalogue release probes using official capabilities and ISO metadata; keep every acquisition separate and operator-controlled.
+- [x] Add a governed regional GRB plan -> stage -> checksum-confirmed apply workflow that preserves every previous snapshot.
 - [ ] Extend catalogue probes only to additional sources that publish a stable machine-readable edition contract; do not add background polling or infer releases from HTTP dates alone.
 
 ## Governed source expansion backlog