Add governed bathymetry profile workflow

docs/API_CONTRACTS.md

@@ -2055,3 +2055,37 @@ specifically, no water volume is inferred from 2D water geometry. The backend
 sets an explicit Ollama context window and returns
 `OLLAMA_RESPONSE_TRUNCATED` instead of accepting a response with
 `done_reason=length` as a complete answer.
+
+## Bathymetry and VHA profile acquisition
+
+### GET `/api/v1/projects/{project_id}/datasets/bathymetry/sources`
+
+Returns the governed bathymetry source registry in the canonical envelope.
+VHA inland profiles are `operational`. MDK Belgian Continental Shelf and SPW
+Walloon bathymetry remain `available_not_integrated`; they cannot be acquired
+through this contract until their raster/download and vertical-datum flows
+pass live validation.
+
+### POST `/api/v1/projects/{project_id}/datasets/bathymetry/profiles/acquire`
+
+```json
+{
+  "bbox": {"min_x": 5.0, "min_y": 51.0, "max_x": 5.3, "max_y": 51.3, "crs": "EPSG:4326"},
+  "area_id": "optional persisted Area uuid",
+  "force_refresh": false
+}
+```
+
+The endpoint creates a synchronous `vector.bathymetry_profiles.acquire` Job.
+It queries the official VHA Digital Atlas in bounded pages, intersects every
+point with the persisted Area when supplied and persists one ordinary
+reference Dataset plus VectorFeature rows. The result reports exact profile,
+document, structured-depth/width and watercourse counts and the source
+measurement-date range.
+
+The acquired Dataset uses
+`source_name=vmm_vha_bathymetry_profiles`,
+`dataset_role=reference` and
+`reference_layer_name=bathymetry_profiles`. Existing vector content and
+selection endpoints provide GeoJSON and metrics. The contract does not expose
+a continuous bathymetric surface, current water depth or water volume.

docs/BATHYMETRY_EXPANSION_ROADMAP.md

@@ -0,0 +1,131 @@
+# 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?
+
+Only the first question is operational for Mol through the VHA cross-section
+profile layer. 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 | Available, not integrated |
+| 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.
+
+Before regional activation:
+
+- add a governed Flanders boundary manifest and partition coordinator;
+- prove idempotent resume and no duplicate VHA `OBJECTID` within a partition;
+- benchmark PostGIS point selection and viewport delivery;
+- add freshness/version probing for the VHA MapServer;
+- keep individual profile dates instead of fabricating one Dataset
+  `observed_at`.
+
+## 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.
+2. Add VHA municipal partition orchestration for Flanders.
+3. Implement a bounded MDK WCS probe, then acquisition behind live evidence.
+4. Implement SPW download staging and vertical-datum metadata validation.
+5. Add maritime boundaries as separate authoritative scope layers.
+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.

docs/CODEX_EXECUTION_LOG.md

@@ -10010,3 +10010,27 @@ Validation:
   stays within its 375 px client width; the theme inventory is bounded to a
   compact scrollable selector so it no longer pushes the map behind all 15
   theme cards.
+
+## Sprint 235 - Governed bathymetry profiles and Belgian expansion model (2026-07-17)
+
+Implemented:
+- Audited official VHA, MDK Belgian Continental Shelf and SPW Walloon
+  bathymetry services and separated profile evidence, continuous bed models
+  and time-specific water depth/volume.
+- Added bounded, paged VHA profile acquisition with exact persisted-Area
+  clipping, official watercourse names, document links, checksums and standard
+  Dataset/VectorFeature persistence.
+- Added reusable vector-byte import and governed `min`/`max` property metrics
+  to the existing selection aggregation path.
+- Added the bathymetry source and acquisition API, environment controls, Mol
+  operator command, map theme, profile inspector and source inventory.
+- Documented partitioned Flanders scaling and federated Belgium/maritime
+  scaling with explicit territorial sea, EEZ/continental shelf and
+  TAW/LAT/mDNG semantics.
+
+Validation:
+- Backend compilation, 914 backend tests, documentation/contract audits,
+  Alembic head `202607160001`, frontend TypeScript typecheck and the production
+  Vite build passed in the complete readiness gate.
+- Full readiness and live Mol acceptance are recorded after final validation
+  and deployment below.

docs/DATABASE_IMPLEMENTATION_PLAN.md

@@ -360,3 +360,18 @@ the composite expression index
 It supports exact preclipped municipality selection without changing the
 canonical `vector_features` schema or introducing operator-specific tables.
 Free rectangle queries continue to use the geometry GiST index.
+
+## Bathymetry profile persistence
+
+VHA profile points require no new table or migration. The immutable GeoJSON
+artifact is stored as one normal reference `datasets` row and
+`dataset_versions` row; each exact point is a normal `vector_features` row with
+EPSG:4326 geometry and source properties. Existing dataset, source-feature and
+GiST indexes support selection.
+
+Profile measurement dates remain feature properties because a bounded Dataset
+can contain many historical campaigns. No artificial Dataset `observed_at` or
+temporal series is assigned. A future bed raster remains file/object storage
+plus Dataset metadata, not raster-in-database storage. Any national/maritime
+extension keeps source vertical datum, survey epoch and Area partition
+explicit and does not create a provider-specific shadow schema.

docs/DATA_SOURCES.md

@@ -709,3 +709,26 @@ thematic rasters for space occupation, open space, population density, node
 value and service level. The digital soil map should follow the existing
 canonical vector persistence path. Watercourse/runoff additions remain in the
 roadmap but no longer precede these cross-domain gaps.
+
+## Bathymetry, inland profiles and maritime scope
+
+The official VHA Digital Atlas profile-point layer is the first operational
+bathymetry-adjacent source. GeoIntel requests an explicit bbox, clips against
+the exact persisted Area and retains VHA point identifiers, watercourse names,
+profile numbers, measurement dates, available structured depth/width values
+and official document URLs. Scanned documents remain evidence; missing fields
+are not filled by fabricated OCR output.
+
+The following sources are audited but not yet operational:
+
+- MDK Dieptemodel Belgisch Continentaal Plat/Noordzee: 20 x 20 m continuous
+  raster in LAT, exposed through WCS/WMTS.
+- SPW bathymetry of navigable waterways and reservoir lakes: 0.5 m bed
+  elevation and XYZ data in mDNG.
+- Port of Antwerp-Bruges periodic soundings: catalog candidate pending a
+  stable public machine contract.
+
+See `docs/BATHYMETRY_EXPANSION_ROADMAP.md`. TAW, LAT and mDNG remain separate
+until an authoritative vertical transformation is implemented and tested.
+The territorial sea, EEZ and continental shelf are separate scope layers and
+must be labelled according to their legal meaning.

docs/DATA_SPECIFICATION.md

@@ -438,3 +438,22 @@ Sprint 7B makes provider architecture operationally visible without performing l
 - status: `configured`
 - dataset mapping: `dataset_role=reference`, `source_name=fixture`
 - write path: checked-in demo/test fixture flow
+
+## Bathymetry profile vector contract
+
+The operational VHA layer is an EPSG:4326 point FeatureCollection. Required
+normalized properties are:
+
+- `provider_record_id` and `source_feature_id`;
+- `watercourse_vhag`, `watercourse_name` and alternative names;
+- `profile_number` and `measurement_date`;
+- nullable `recorded_depth_m`, `recorded_crown_width_m` and
+  `recorded_floor_width_m`;
+- nullable allowlisted `source_document_url`;
+- `document_available`, `structured_depth_available`;
+- `measurement_semantics=historical_cross_section_profile_point`;
+- `vertical_reference=document-specific`.
+
+Null means the provider did not expose a structured value. It is never
+converted to zero. Dataset metadata records exact counts, measurement range,
+scope, attribution and `volume_supported=false`.

docs/TODO.md

@@ -749,3 +749,18 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Keep orthophoto pixel refresh manual through a separate
   plan-stage-review-apply flow that retains the passed preflight identity and
   creates a new immutable Dataset with official `YYYY.NN` source version.
+# Bathymetry follow-up
+
+- [ ] Add governed municipality partition orchestration for all of Flanders
+  after the Mol VHA operator passes live acceptance.
+- [ ] Add read-only MDK WCS capability/TLS probe and maritime scope metadata.
+- [ ] Add bounded MDK GeoTIFF acquisition only after live CRS, LAT, nodata and
+  response-limit validation.
+- [ ] Add SPW staged-download adapter with mDNG metadata and survey-epoch
+  coverage validation.
+- [ ] Add authoritative territorial-sea, EEZ and continental-shelf boundary
+  layers with legally accurate labels.
+- [ ] Add vertical-datum conversion only when authoritative transforms and
+  uncertainty tests exist; never merge TAW, LAT and mDNG implicitly.
+- [ ] Add water volume only when bed and water-surface inputs share a governed
+  time, datum and coverage contract.