Initial public release

docs/POST_RC_DATA_COVERAGE_ROADMAP_BELGIUM_NORTH_SEA.md

@@ -0,0 +1,297 @@
+# Post-RC Data Coverage Roadmap: Belgium And The Belgian North Sea
+
+## Status and purpose
+
+This is the completed autonomous implementation board after `v1.0.0-rc.1`.
+It is not an RC-12 phase. The signed `v1.0.0` release remains immutable
+evidence; any future work 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.0.2.10:1202/health/ready
+bash scripts/run_rc8_release_journeys.sh \
+  http://192.0.2.10: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: complete; live national and maritime source journeys proven.**
+
+### 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: complete; reviewed 2021-2025 national series materialized live.**
+
+### 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.
+
+### Live evidence
+
+- Reviewed immutable datasets:
+  - 2021: `27b2aaba-6ec4-42d8-91c3-9085456b5e7a`;
+  - 2022: `312e8278-5552-4dd0-abf7-7e1f17d2562a`;
+  - 2023: `72bfb8a7-9ecb-462d-a622-f8cf693a3cfb`;
+  - 2024: `e7846fc6-85d1-4120-9442-e62a5b1cd346`;
+  - 2025: `ee0a46e5-6139-4b0a-93b5-9dabb3b3dfc7`.
+- The 2021-2024 editions each retain 19,795 sector geometries. The 2025
+  REDEGEO edition retains 20,781 sectors and represents all 565 municipalities.
+- The 2025 national reconciliation reports 11,825,551 inhabitants, including
+  7,654 explicitly retained as unlocated rather than silently assigned to
+  geometry.
+- A bounded Mol selection returns an explicitly labelled area-weighted estimate.
+
+## P2 - Wallonia bounded topographic baseline
+
+**State: complete; bounded Wallonia acquisition and analysis proven live.**
+
+### 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.
+
+### Live evidence
+
+- Dataset `0c3c0a11-c00e-4c84-87be-8ffa64302dec` retained 54 valid building
+  geometries for the bounded Wallonia smoke selection.
+- The persisted selection reported 54 buildings and 0.525363 ha without
+  extending operational coverage beyond the retained bbox.
+
+## P3 - Brussels bounded UrbIS baseline
+
+**State: complete; bounded Brussels acquisition and analysis proven live.**
+
+### 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`.
+
+### Live evidence
+
+- Dataset `de53ccc0-a494-4c4e-bd0d-16d807bfefe7` retained 47 UrbIS building
+  geometries for the bounded Brussels smoke selection.
+- The persisted selection reported 47 buildings and 0.528894 ha without
+  claiming coverage outside the retained bbox.
+
+## P4 - Maritime and bathymetry hardening
+
+**State: complete; SPW live persistence and browser acceptance passed for
+`v1.0.0`; MDK acquisition remains 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.
+- The bounded SPW operator stages the fixed official GeoTIFF archive, validates
+  its checksum and raster identity, writes a clipped COG through the canonical
+  Dataset flow and reports only waterbed elevation and surveyed coverage.
+
+### 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: complete; live federation, responsive map UX and release evidence proven.**
+
+### 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.
+
+### Live evidence
+
+- Immutable AI image `04b8373d7ece0f5eb29674507d718f0ea51ed5c4-ai` passed live
+  PostGIS migration, browser proxy smoke and the final SPW bathymetry journey.
+- The release journey reused all seven deterministic golden Areas and passed
+  Brussels, Wallonia, language-boundary, coast, Mol, Kempen and North Sea
+  coverage without creating duplicates.
+- National population resolves from the persisted reviewed Statbel 2025
+  edition; selection-bounded PICC and UrbIS results remain separate governed
+  regional datasets.
+- The live map now keeps persisted sources ahead of on-demand placeholders,
+  gives the selected Area camera priority and bounds the responsive MapLibre
+  canvas to its visible grid row. Belgium, Brussels, Wallonia and the North Sea
+  switched without manual zoom, horizontal overflow or console warnings.
+- The evidence manifest retained exact area geometry hashes, coverage states,
+  temporal forest metrics, a 49-feature persisted export, a grounded Ollama
+  answer and a configured local-YOLO Job/AnalysisRun with map handoff.
+- PyTorch `2.13.0+cpu` and Ultralytics `8.4.99` import in the deployed AI
+  runtime. No model download or fabricated detection was used.
+- The final repository gate passed 1,052 backend tests, 22 frontend tests,
+  frontend typecheck/build, one Alembic head, the full offline migration SQL
+  chain and live-smoke syntax.
+- MDK bathymetry remains `not_configured` because strict hostname validation
+  still fails. Marine planning/reporting remains operational and no depth or
+  water-volume value is fabricated.
+- Rectangle-based golden scopes that cross an irregular legal boundary retain
+  the truthful `outside_supported_scope` warning for the uncovered corners.