Federate official Belgium data sources

docs/POST_RC_DATA_COVERAGE_ROADMAP_BELGIUM_NORTH_SEA.md

@@ -0,0 +1,236 @@
+# Post-RC Data Coverage Roadmap: Belgium And The Belgian North Sea
+
+## Status and purpose
+
+This is the active autonomous implementation board after `v1.0.0-rc.1`.
+It is not an RC-12 phase. The signed RC remains immutable release evidence;
+all work below targets the next version and must preserve the frozen API,
+persistence, provenance and no-fake-data rules.
+
+The goal is to make the national workbench useful with real data:
+
+1. choose an understandable theme;
+2. select a bounded area anywhere in Belgium or the Belgian North Sea;
+3. acquire or reuse only governed data that covers that selection;
+4. calculate source-appropriate metrics;
+5. expose authority, time, licence, coverage and limitations;
+6. keep unsupported or unavailable results visibly unavailable.
+
+Mol and the Kempen remain mandatory regression areas. They do not constrain
+the geographic implementation.
+
+## Autonomous execution rules
+
+- Read `docs/CODEX_BOOTSTRAP_PROMPT.md` and
+  `docs/RC_SCOPE_FREEZE_BELGIUM_NORTH_SEA.md` before every resumed pass.
+- Never run an unbounded browser-side or application-startup provider fetch.
+- Every external endpoint must be allowlisted, strict-TLS and size/time limited.
+- Provider output must be staged, validated and persisted through
+  `DatasetService` and `VectorFeatureService`.
+- No source may become `operational` from catalogue evidence alone.
+- Do not merge semantically different regional sources into one value.
+- Do not create water volume, bathymetry, population, AI or historical values
+  when the required evidence is absent.
+- A failed source or validation gate stops only that source. Other independent
+  phases may continue.
+- Update `docs/CODEX_EXECUTION_LOG.md`, `docs/TODO.md`, relevant source/API
+  docs and this roadmap after every completed gate.
+
+## Global validation gate
+
+Run after every implementation phase:
+
+```bash
+python -m compileall backend/app
+cd backend && python -m pytest
+cd frontend && npm run test:unit
+cd frontend && npm run typecheck
+cd frontend && npm run build
+bash scripts/run_readiness_check.sh
+cd backend && python -m alembic heads
+cd backend && python -m alembic upgrade head --sql
+bash -n scripts/live_migration_smoke.sh
+```
+
+When Docker/Tower is available:
+
+```bash
+docker compose config
+curl --fail http://192.168.10.150:1202/health/ready
+bash scripts/run_rc8_release_journeys.sh \
+  http://192.168.10.150:1202 \
+  artifacts/post-rc-release-journeys \
+  artifacts/post-rc-golden-areas.json
+```
+
+No phase is complete when compile, tests, typecheck, build, migration or the
+applicable live bounded journey fails.
+
+## P0 - Existing national layers become usable
+
+**State: implemented locally; live release evidence pending under P5.**
+
+### Work
+
+- Add understandable map themes for administrative context, maritime planning
+  and marine reporting/legal context.
+- Match persisted `ngi_adminvector`, `rbins_marine_reporting_units` and
+  `rbins_msp_2026` datasets explicitly; do not rely on filename substrings.
+- Automatically select the first operational theme when the previous/default
+  theme has no matching dataset in the active workspace.
+- Add source-appropriate selection summaries. Administrative polygon area may
+  be reported in hectares; overlapping marine use zones must not be summed as
+  unique sea area.
+- Make workbench readiness distinguish stored context/reference layers from
+  actually analyzable themes.
+- Add frontend and backend regression tests and verify the live national and
+  North Sea workspaces without console errors.
+
+### Exit
+
+- Belgium land opens with a usable NGI administrative theme.
+- The Belgian North Sea opens with usable legal/reporting and marine-plan
+  themes.
+- Drawing or selecting a bounded area produces persisted-source results with
+  provenance.
+- An unavailable buildings/population/bathymetry source remains unavailable.
+
+## P1 - National Statbel population
+
+**State: implementation complete; reviewed live national materialization pending.**
+
+### Work
+
+- Extend the existing governed Statbel plan-stage-review-apply flow with a
+  national scope that uses the persisted Belgium boundary.
+- Keep the 2025 REDEGEO old/new geometries separate.
+- Validate archive checksums, schema, CRS, sector joins, `ZZZZ` accounting and
+  national totals before persistence.
+- Materialize one immutable national edition through `DatasetService`; bounded
+  map queries continue to run in PostGIS.
+- Expose inhabitants as an area-weighted estimate only when a selection cuts
+  statistical sectors, with an explicit warning and compatible time-series
+  keys.
+- Never download or replace a release automatically.
+
+### Exit
+
+- A named reviewed plan is required for live apply.
+- Belgium, Flanders, Wallonia and Brussels bounded population selections work
+  from the same authoritative Statbel edition.
+- Mol remains within its documented baseline tolerance.
+
+## P2 - Wallonia bounded topographic baseline
+
+**State: implemented locally; live Wallonia journey pending under P5.**
+
+### Governed source
+
+SPW PICC ArcGIS REST:
+
+```text
+https://geoservices.wallonie.be/arcgis/rest/services/TOPOGRAPHIE/PICC_VDIFF/MapServer
+```
+
+Initial allowlisted layers:
+
+- `11`: building footprints;
+- `21`: road axes;
+- `28`: hydrographic axes;
+- `30`: hydrographic surfaces.
+
+### Work
+
+- Add a bounded ArcGIS REST adapter using an EPSG:4326 selection transformed by
+  the official service to EPSG:3812/4326.
+- Enforce maximum selection dimensions, paging, response size, feature count,
+  strict content type, stable layer identity and source metadata.
+- Normalize geometry to EPSG:4326 while retaining provider-native attributes.
+- Persist buildings, roads and water as separate immutable datasets.
+- Add hectare/kilometre metrics without claiming semantic parity with GRB.
+- Expose the products only for Walloon intersections and keep mixed-zone
+  results split.
+
+### Exit
+
+- The Wallonia golden area can explicitly acquire and analyse all allowlisted
+  PICC themes.
+- Provider failures and record-limit truncation fail closed.
+- No direct provider-to-`vector_features` write exists.
+
+## P3 - Brussels bounded UrbIS baseline
+
+**State: implemented locally; live Brussels journey pending under P5.**
+
+### Governed source
+
+Paradigm UrbIS parcels and buildings WFS, discovered and pinned from the
+official datastore metadata. The exact service URL and type names must pass a
+capabilities probe before implementation is marked operational.
+
+### Work
+
+- Add bounded WFS acquisition for building footprints and cadastral parcels.
+- Retain the separate Paradigm and FPS Finance authorities/licences where
+  applicable.
+- Enforce bbox, paging, response size, CRS and geometry validation.
+- Persist separate immutable building and parcel datasets.
+- Add source-appropriate area/count metrics and Brussels-only coverage.
+
+### Exit
+
+- The Brussels golden area can explicitly acquire and analyse buildings and
+  parcels.
+- Catalogue-only or failed capabilities evidence remains `not_configured`.
+
+## P4 - Maritime and bathymetry hardening
+
+**State: complete with MDK acquisition visibly blocked by strict-TLS evidence.**
+
+### Work
+
+- Keep the current RBINS marine legal/reporting and 2026-2034 planning layers
+  operational and map-queryable.
+- Probe the MDK 20 m LAT product only through strict TLS and retained metadata.
+- Implement bounded GeoTIFF acquisition only after CRS, nodata, pixel
+  semantics, edition, licence and LAT evidence pass.
+- Keep depth relative to LAT separate from water-surface elevation and volume.
+- SPW mDNG bathymetry remains a separate Walloon inland/navigation source.
+
+### Exit
+
+- Maritime plan and legal/reporting queries are operational.
+- Bathymetry is either a governed analytical raster with vertical datum and
+  uncertainty evidence, or remains visibly `not_configured`.
+- No water-volume metric exists without compatible bed and water-surface data.
+
+## P5 - Federation, UX and release evidence
+
+**State: in progress.**
+
+### Work
+
+- Make on-demand products depend on the intersected zone, not on a manually
+  selected technical project.
+- Keep cross-region selections split by source and metric semantics.
+- Present loaded, available-on-demand, partial, not-configured and unsupported
+  states in ordinary Dutch language.
+- Run land, language-boundary, Brussels, Wallonia, coast and North Sea golden
+  journeys against live PostGIS.
+- Capture source checksums, selected bounds, result metrics, provenance,
+  performance, browser console/network and responsive screenshots.
+- Build, push and deploy one immutable post-RC image only after every applicable
+  gate is green.
+
+### Final acceptance
+
+- Existing RC behavior remains green.
+- At least one real bounded analytical theme is operational for Belgium,
+  Flanders, Wallonia, Brussels and the Belgian North Sea.
+- Population is nationally operational or explicitly blocked by failed source
+  evidence.
+- Buildings/roads/water are operational through the competent regional source
+  where implemented; no parity claim is made.
+- No unavailable theme is presented as measured data.
+- The live browser can select an area, acquire/reuse data, analyse it, inspect
+  provenance and export it without entering a technical project workflow.