feat: stream municipality vectors by viewport

docs/API_CONTRACTS.md

@@ -405,6 +405,8 @@ Rules:
 - Coordinates are EPSG:4326 longitude/latitude.
 - Results are generated from persisted PostGIS `vector_features`, not from client-side map data.
 - The response is capped by `limit` and returns `truncated=true` when more matching rows exist.
+- `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.
 
 ### POST `/api/v1/projects/{project_id}/datasets/{dataset_id}/vector/select/derive`
 

docs/CODEX_EXECUTION_LOG.md

@@ -7474,3 +7474,39 @@ Open:
   layering additional municipality-wide reference classes. Then acquire and
   tile georeferenced imagery only for an explicitly selected Mol analysis zone
   and run configured-YOLO plus QA/QC against the persisted GRB reference.
+
+# Sprint 182 - Municipality viewport delivery and bounded AI handoff
+
+## Implementation
+
+- Added `useViewportVectorLayer` with centralized feature threshold, minimum
+  zoom, response limit and debounce policy. Vector datasets above 5,000
+  features now use the existing canonical PostGIS bbox-selection endpoint from
+  zoom level 14 instead of downloading the full stored GeoJSON file.
+- Added MapLibre `moveend` viewport reporting, stale-request protection and
+  disabled automatic fit for viewport slices. AOI changes still frame the map;
+  small vectors and persisted analysis/evidence layers retain their existing
+  complete-layer fit behavior.
+- Added explicit low-zoom, loading, visible/total, truncation and error states.
+  A selected large database layer is no longer presented as an empty or missing
+  layer before the first detail request.
+- Extended the real-data detection/QA workflow with validated existing-project
+  reuse, safe distinct upload filenames and actual Area linkage for the raster
+  and matching reference vector. The workflow still consumes operator-provided
+  files and an existing local model asset; it performs no provider fetch or
+  model download.
+
+## Local validation
+
+- `python -m compileall backend/app` passed.
+- Full backend suite passed: `500` tests.
+- `npm run typecheck` and `npm run build` passed; the production build contains
+  85 transformed modules and preserves the dedicated MapLibre chunk.
+- `bash scripts/run_readiness_check.sh` passed with the 81-route API contract
+  audit, one Alembic head `202606120900`, shell syntax checks and full frontend
+  build.
+- Internal browser validation against the local frontend and live Tower API
+  selected `mol_grb_gbg_buildings.geojson`, showed the zoom-14 PostGIS delivery
+  guard, suppressed the incorrect empty-layer state and loaded an actual
+  viewport slice with `2 visible of 36,941 total features`. No browser warnings
+  or errors were recorded.

docs/TODO.md

@@ -525,6 +525,16 @@ This file now starts with the current implementation status. Older preparation/b
 - [ ] Acquire and tile a georeferenced raster only for an explicitly selected
   Mol analysis zone before running the next configured-YOLO validation.
 
+# Sprint 182 - Municipality viewport delivery and bounded AI handoff
+
+- [x] Stop downloading municipality-scale vector datasets as one frontend GeoJSON payload.
+- [x] Deliver large persisted layers through the existing PostGIS bbox endpoint from zoom level 14.
+- [x] Report visible/total counts and explicit truncation instead of silently hiding omitted features.
+- [x] Preserve complete loading and auto-fit behavior for small vectors and persisted AI/QA overlays.
+- [x] Allow the real raster/detection/QA operator smoke to reuse the definitive Mol project.
+- [x] Link operator raster/reference uploads to the persisted analysis Area and keep their names distinct from municipality-wide layers.
+- [ ] Execute the bounded Mol-Centrum configured-YOLO/QA workflow in the deployed runtime and retain its persisted ids as release evidence.
+
 # Sprint 171 - Positive AOI expansion and small-building recovery
 
 - [x] Reject cross-model false-negative comparisons when reference populations differ.