feat: add semantic GIS selection metrics

docs/API_CONTRACTS.md

@@ -427,6 +427,42 @@ Response:
     "geojson": {
       "type": "FeatureCollection",
       "features": []
+    },
+    "summary": {
+      "metric_label": "Wateroppervlakte",
+      "metric_value": 5.25,
+      "metric_unit": "ha",
+      "aggregation_method": "intersection_area",
+      "primary_metric_key": "water_area",
+      "feature_count": 23,
+      "is_estimate": false,
+      "warning": "Watervolume is niet berekenbaar zonder betrouwbare diepte- of bathymetrische gegevens.",
+      "metrics": [
+        {
+          "metric_key": "water_area",
+          "metric_label": "Wateroppervlakte",
+          "metric_value": 5.25,
+          "metric_unit": "ha",
+          "aggregation_method": "intersection_area",
+          "is_estimate": false
+        },
+        {
+          "metric_key": "watercourse_length",
+          "metric_label": "Lengte waterlopen",
+          "metric_value": 12.75,
+          "metric_unit": "km",
+          "aggregation_method": "intersection_length",
+          "is_estimate": false
+        },
+        {
+          "metric_key": "feature_count",
+          "metric_label": "Waterobjecten",
+          "metric_value": 23,
+          "metric_unit": "objecten",
+          "aggregation_method": "feature_count",
+          "is_estimate": false
+        }
+      ]
     }
   }
 }
@@ -439,6 +475,9 @@ Rules:
 - `area_id` is optional and must belong to the route project. When present, the bbox remains the bounded preview extent but PostGIS filtering and configured aggregations use the persisted Area geometry exactly. This prevents a municipal or regional full-work-area query from counting objects in the surrounding bbox corners.
 - Results are generated from persisted PostGIS `vector_features`, not from client-side map data.
 - `feature_count` is the number of GeoJSON features returned in the bounded preview. `total_feature_count` is the exact number of persisted rows intersecting the requested bbox or persisted Area geometry.
+- `summary` keeps one backwards-compatible primary metric and exposes all relevant measurements in `metrics`. Known themes use metric PostGIS calculations: building/forest/water/parcel surfaces in hectares, road and watercourse lengths in kilometres, population in inhabitants and intersecting feature counts as supporting evidence.
+- Area and length calculations transform geometry to Belgian Lambert 72 (`EPSG:31370`); they are never calculated in geographic degrees.
+- Water volume is not inferred from 2D GRB geometry. It remains unavailable until a source provides reliable depth or bathymetry with compatible spatial coverage and provenance.
 - The response is capped by `limit` and returns `truncated=true` when `total_feature_count` exceeds the returned preview.
 - `limit` is bounded to `1..1000`. Municipality-scale clients must page spatially by viewport instead of requesting an unbounded municipality FeatureCollection.
 - The Map workspace uses this existing endpoint for vector datasets above 5,000 features. It starts delivery at zoom level 14, debounces `moveend` requests and explicitly reports `truncated=true` as a request to zoom further in. This is a client delivery policy, not a second API or persistence path.

docs/CODEX_EXECUTION_LOG.md

@@ -8333,3 +8333,35 @@ Next:
 - Generalize the audited historical-land-use operator to the approved regional
   scope, partition source retrieval by municipality and provision the three
   official editions without merging their methodology into current GRB.
+
+## Sprint 201 - Semantic area-selection metrics (2026-07-15)
+
+Implemented:
+- Extended the canonical persisted-vector selection summary with an additive
+  metric set while preserving the existing primary metric fields and envelope.
+- Mapped known data themes to useful units: building footprint, forest, water
+  and parcel surfaces in hectares; roads and linear watercourses in kilometres;
+  population in inhabitants; and intersecting feature counts as supporting
+  evidence.
+- Kept all spatial calculations in PostGIS after transformation to EPSG:31370.
+  No browser-side area/length calculation or synthetic source value was added.
+- Added honest domain limits for building floor area, road capacity and water
+  volume. The current 2D GRB water source cannot support volume without an
+  independently governed depth/bathymetry dataset.
+- Updated the regional GRB operator metadata for future imports and added a
+  compact supporting-metric surface to the map-first result panel.
+
+Validation evidence:
+- Focused temporal and semantic-selection regression set passed 16 tests.
+- Full readiness passed 605 backend tests, backend compilation, the API
+  contract audit, one Alembic head, frontend TypeScript typecheck/build and all
+  shell syntax gates.
+
+Known limitation:
+- Water volume remains unavailable by design. Adding it requires a compatible
+  depth or bathymetry source, coverage validation, units, observation date and
+  a documented integration method.
+
+Next:
+- Validate the semantic metrics against live Mol PostGIS data and then continue
+  the audited regional historical buildings/water/roads import.

docs/TODO.md

@@ -16,6 +16,8 @@
 - [x] Default Detection Lab to the configured local YOLO asset and present measured model quality and control requirements honestly.
 - [x] Extend official population and land-use time series from Mol to the approved 28-municipality regional scope.
 - [x] Make Evolution automatically open an available regional series and distinguish historical themes from current-only snapshots.
+- [x] Replace object-count-only map results with semantic PostGIS metrics for hectares, kilometres and inhabitants while retaining counts as supporting evidence.
+- [ ] Add a governed depth/bathymetry source before exposing water volume; never infer volume from 2D GRB water geometry.
 - [ ] Extend the official 1778/1873/1969 historical buildings, water and roads series from Mol to the approved regional scope with partitioned source audits.
 - [x] Connect a drawn rectangle to bounded official orthophoto acquisition, local configured-YOLO detection and persisted GRB QA.