Initial public release

docs/BATHYMETRY_EXPANSION_ROADMAP.md

@@ -0,0 +1,152 @@
+# Bathymetry expansion roadmap
+
+## Purpose
+
+GeoIntel must distinguish three different questions:
+
+1. Where were cross-sections measured and what does the source document say?
+2. What is the continuous elevation of the bed at a specific survey epoch?
+3. What is the water depth or volume at a specific moment?
+
+The first question is operational for Flanders through VHA cross-section
+profiles. The second is now operational for bounded, surveyed Walloon
+waterways through the official SPW raster. A bed model does not provide water
+depth without a compatible water-surface elevation. Flood-hazard maximum depth
+is a scenario result and must not be reused as current water level.
+
+## Governed source matrix
+
+| Source | Coverage | Data | Vertical reference | GeoIntel status |
+| --- | --- | --- | --- | --- |
+| VMM VHA Digital Atlas | Flanders | Point locations, structured profile fields, PDF evidence | Document-specific | Operational, bounded vector acquisition |
+| MDK Belgian Continental Shelf model | Belgian North Sea | Continuous 20 x 20 m bathymetric raster | LAT | Available, not integrated |
+| SPW navigable waterways and reservoir lakes | Wallonia | 0.5 m bed-elevation raster and XYZ cloud | mDNG | Operational, pinned operator archive and bounded COG |
+| Port of Antwerp-Bruges publications | Port survey areas | Periodic soundings | Product-specific | Catalog candidate |
+
+VHA contains approximately 129,643 profile points across Flanders at the
+observed catalog state. This is a scale indication, not a fixed contractual
+count. Mol contained 828 exact in-boundary points during source validation,
+715 with document links and 112 with a structured depth field. Production
+provisioning always records the live counts and checksums.
+
+## Operational tier 1: Mol
+
+- Query only an explicit EPSG:4326 bbox.
+- Intersect the bbox with the exact persisted Mol Area.
+- Page the official ArcGIS FeatureServer response without truncation.
+- Resolve VHA watercourse names from the official atlas layer.
+- Normalize profile points to EPSG:4326.
+- Persist the artifact through `DatasetService.import_vector_bytes`.
+- Persist every point through `VectorFeatureService`; the provider never
+  writes directly to `vector_features`.
+- Expose document, measurement date, depth and width fields without parsing or
+  inventing values from scanned PDFs.
+- Keep volume unsupported.
+
+## Tier 2: all of Flanders
+
+Flanders must be provisioned as exact municipality or other approved Area
+partitions, not as one monolithic request. The backend feature limit protects
+the provider and the application. A regional logical layer may group complete
+partitions, but each Dataset retains its Area id, query URLs, checksums, exact
+count and measurement-date range.
+
+Regional activation now uses the complete checksum-bound municipality
+manifest. The Map flow chooses the exact Area partition for a municipality and
+uses a bounded multi-Dataset PostGIS query for regional rectangles or the
+complete Flanders Area. GeoJSON remains limited to 1,000 rendered features;
+counts and configured metrics cover the complete spatial result. Individual
+profile dates remain authoritative and no Dataset-level survey date is
+fabricated.
+
+Remaining operational follow-up:
+
+- add freshness/version probing for the VHA MapServer;
+- keep selection-performance evidence as the profile inventory grows;
+- retain explicit no-profile municipalities in every refreshed manifest.
+
+## Tier 3: Belgium
+
+Belgian coverage is a federation of source adapters with one normalized
+contract, not one assumed national dataset:
+
+- Flanders: VHA profiles and future validated bed rasters;
+- Wallonia: SPW bathymetry for measured navigable waterways/reservoirs;
+- Brussels: hydrological context until an authoritative public bathymetric
+  product is identified;
+- federal/maritime: MDK and legally appropriate maritime boundaries.
+
+Every adapter must emit:
+
+- authority and owner;
+- exact geographic and temporal coverage;
+- horizontal and vertical CRS/datum;
+- survey/acquisition time;
+- resolution or sample density;
+- source URL, request identity, checksum, attribution and license;
+- explicit supported and unsupported metrics.
+
+LAT, TAW and mDNG values must never be merged or compared without a documented,
+tested vertical transformation and uncertainty statement.
+
+## Tier 4: the Belgian North Sea
+
+The map must distinguish:
+
+- the Belgian land boundary and baseline;
+- the territoriale zee (up to 12 nautical miles);
+- the Belgian EEZ and continental shelf, which are jurisdictional maritime
+  zones and should not be labelled ordinary municipal or provincial
+  "grondgebied".
+
+The MDK bathymetry WCS is the preferred continuous source candidate. Activation
+requires a live Docker validation of TLS/certificates, GetCapabilities,
+coverage identifiers, bounded GeoTIFF retrieval, CRS, LAT, nodata, pixel size,
+response limits and maritime clipping. WMTS can support visual context but is
+not the analytical source.
+
+## Depth and volume rules
+
+For a compatible bed raster and water-surface raster at the same time and
+vertical datum:
+
+`volume_m3 = sum(max(0, water_surface_z - bed_z) * cell_area_m2)`
+
+For surveyed cross-sections along a connected reach:
+
+`volume_m3 = sum(((section_area_i + section_area_i+1) / 2) * reach_length_i)`
+
+The second method requires complete profile geometry, ordered chainage,
+contemporaneous water level and defensible interpolation. VHA profile points
+alone do not satisfy those prerequisites.
+
+Historical evolution compares only survey epochs with documented compatible
+coverage, datum and method. A changed raster footprint is not automatically
+bed evolution.
+
+## Implementation order
+
+1. Operate and validate the Mol VHA profile Dataset and map flow. **Done.**
+2. Add VHA municipal partition orchestration for Flanders. **Done and live:
+   285/285 municipality partitions accounted for, 269 with data, 16 explicit
+   no-profile results, 128,913 profile points and zero failures. Regional
+   selection and export now aggregate the latest complete manifest in
+   PostGIS.**
+3. Implement a bounded MDK WCS probe, then acquisition behind live evidence.
+   **Probe implemented. Acquisition blocked because the live endpoint fails
+   strict hostname validation and does not expose usable capabilities.**
+4. Implement SPW download staging and vertical-datum metadata validation.
+   **Done: pinned official ZIP, safe `/vsizip/` access, bounded COG,
+   DatasetService persistence, map overlay and mDNG selection metrics.**
+5. Add maritime boundaries as separate authoritative scope layers.
+   **Done for the Belgian territorial sea, EEZ and continental shelf.**
+6. Add cross-source vertical-datum transformation only with authoritative
+   grids/parameters and uncertainty tests.
+7. Add volume only after a compatible measured or modeled water-surface source
+   is part of the same analysis contract.
+
+The Flanders scope is land-only and is dynamically derived from the complete
+current VRBG municipality collection (285 members at the 2026-07-17
+validation). Belgium is not represented by expanding that polygon. Wallonia,
+Brussels, the territorial sea and the Belgian EEZ/continental shelf require
+their own authoritative adapters and legal scope labels.