Add governed buildings register snapshot

docs/API_CONTRACTS.md

@@ -1639,6 +1639,21 @@ Datasets share one scope-specific temporal series, but declare
 `identity_stable=false`; their temporal response compares area totals and
 returns no parcel-level added/removed/modified claims.
 
+For `reference_layer_name=building_registry`, the primary metric is exact
+intersected building-footprint area in hectares. Supplemental server-owned
+metrics expose register building/status counts, aggregate building-unit and
+address-status counts, and confirmed GRB matches. Filtered `feature_count`
+metrics apply their configured property filter in PostGIS just like filtered
+area/sum metrics. Address labels and house/box numbers are never part of the
+queryable Feature properties or response contract.
+
+The governed snapshot is scoped to its persisted `area_id`. The frontend may
+prefer it over the regional GRB building layer only when that exact Area is
+active; another municipality or the full region must continue to use the
+regional GRB Dataset. No new register-specific API endpoint exists: upload,
+GeoJSON, exact selection and temporal provenance use the existing Dataset
+contracts.
+
 ## Local GeoIntel assistant
 
 The assistant is an optional read-only language interface over persisted

docs/DATA_SOURCES.md

@@ -329,12 +329,44 @@ quality metrics.
 
 ## Gebouwenregister
 
-- Naam: Gebouwenregister Vlaanderen
-- Type: vector/API/metadata
-- Gebruik: gebouwmetadata en statusinformatie
-- Toegang: nader te bepalen
-- Cache: PostGIS/metadata tabellen
-- Prioriteit: V2
+The governed operator `scripts/provision_buildings_addresses_register.py`
+reads the official Digitaal Vlaanderen OGC API Features collections
+`Gebouw`, `Gebouweenheid` and `Adres`. The source is continuously updated;
+GeoIntel therefore creates a dated snapshot rather than claiming an annual
+historical series. Raw response pages, request URLs and SHA256 checksums are
+retained as operator evidence.
+
+Building polygons are clipped against the exact persisted Area in
+EPSG:31370, transformed to EPSG:4326 and persisted through the normal Dataset
+upload route with `source_name=digitaal_vlaanderen_buildings_addresses_register`
+and `reference_layer_name=building_registry`. Register lifecycle state remains
+separate from GRB geometry. Each register building receives an explicit
+`matched`, `review`, `ambiguous` or `unmatched` GRB reconciliation result; a
+low-confidence or duplicate match is never silently promoted.
+
+Building units use the official `GebouwObjectId` relation. The public address
+collection does not expose that relation directly, so addresses are linked
+only through an exact, unambiguous unit position or unambiguous polygon
+containment. Ambiguous and unmatched rows are counted in the manifest and are
+never forced to the nearest building.
+
+The queryable layer contains building polygons, lifecycle status and aggregate
+unit/address counts only. Street names, full addresses, house numbers and box
+numbers are excluded. Address counts are not households, dwellings, residents
+or population. Raw source pages remain restricted operator evidence and are
+not exposed by the API or map.
+
+Official endpoints and catalogues:
+
+- https://geo.api.vlaanderen.be/Gebouwenregister/ogc/features/v1/collections/Gebouw/items
+- https://geo.api.vlaanderen.be/Gebouwenregister/ogc/features/v1/collections/Gebouweenheid/items
+- https://geo.api.vlaanderen.be/Adressenregister/ogc/features/v1/collections/Adres/items
+- https://www.vlaanderen.be/datavindplaats/catalogus/gebouwen-en-adressenregister
+- https://www.vlaanderen.be/datavindplaats/catalogus/gebouwenregister
+
+Digitaal Vlaanderen is transitioning the download products in summer 2026.
+This operator uses the current production OGC API and does not depend on the
+retiring `/v2/extract` path.
 
 ## Lokale demo datasets
 

docs/DATA_SPECIFICATION.md

@@ -61,22 +61,43 @@ GRB-gebouwpolygonen worden gebruikt als ground-truth proxy. Niet absoluut perfec
 
 ### Rol
 
-Aanvullende gebouwinformatie bij geometrieën.
+Authoritative register lifecycle and relation metadata attached to a dated
+building snapshot. It complements GRB; it does not replace the separate GRB
+footprint evidence or its QA role.
 
 ### Gebruik
 
-- gebouwmetadata
-- identificatie
-- status
-- koppeling met GRB-gebouwpolygonen indien mogelijk
+- stable building object and version identity
+- official lifecycle status and geometry method
+- aggregate registered building-unit counts by lifecycle status
+- aggregate address counts by register status
+- classified reconciliation against persisted GRB geometry
 
 ### Type
 
-Vector/API/metadata.
+Official OGC API Features input, normalized polygon GeoJSON upload and
+PostGIS `vector_features` output.
 
-### Prioriteit
+### Persisted contract
 
-V2 of V1.5.
+- `dataset_role=reference`
+- `source_name=digitaal_vlaanderen_buildings_addresses_register`
+- `reference_layer_name=building_registry`
+- `temporal_granularity=snapshot`
+- stable building identity within the register, but no fabricated historical
+  observation between snapshots
+- polygon geometry clipped in EPSG:31370 and persisted as EPSG:4326
+- selection metrics: exact footprint hectares, building lifecycle counts,
+  unit counts, address-status counts and confirmed GRB match counts
+
+### Privacy and semantics
+
+Queryable properties may contain register object ids, lifecycle status,
+geometry method, aggregate unit/address counts and GRB reconciliation evidence.
+They must not contain `VolledigAdres`, `Straatnaam`, `Huisnummer`,
+`HuisnummerLabel` or `Busnummer`. Address and unit counts may not be labelled
+as population, residents, households or dwellings. Building footprint is
+ground area, not floor area, height or volume.
 
 ## OpenStreetMap
 

docs/STORAGE_ARCHITECTURE.md

@@ -133,6 +133,27 @@ artifact; Dataset and vector_feature rows remain the queryable PostGIS state.
 The manifest binds source, crop-code list and upload artifact checksums. A
 checksum conflict with an existing annual Dataset fails closed.
 
+Buildings and Addresses Register snapshot evidence lives under:
+
+```text
+storage/operator-evidence/buildings-addresses-register/mol/{observed-date}/
+  raw/
+    buildings_page_*.json
+    building_units_page_*.json
+    addresses_page_*.json
+  buildings_addresses_register.geojson
+  buildings_addresses_register.manifest.json
+```
+
+Raw pages contain the unmodified official response and are retained only as
+checksummed operator evidence. They can contain address labels and must never
+be served as a map/API artifact. The normalized GeoJSON deliberately contains
+one polygon per register building with lifecycle state, aggregate relation
+counts and classified GRB reconciliation only. It enters PostGIS exclusively
+through DatasetService and ordinary `vector_features`; the operator never
+writes database rows directly. The manifest binds all raw pages, the normalized
+artifact, exact Area boundary and every GRB partition used for reconciliation.
+
 Offline demo export artifacts can be inspected and cleaned with:
 
 ```bash