feat: add governed agricultural parcel history

docs/API_CONTRACTS.md

@@ -1632,6 +1632,13 @@ Added/removed/modified object changes are calculated only when source
 provenance declares stable feature identities; otherwise
 `object_changes.available=false` and no object history is inferred.
 
+For `reference_layer_name=agriculture`, the primary map metric is exact
+intersected declared-use area in hectares. Supplemental metrics use
+server-owned filters on the normalized official main-crop group. Annual ALZ
+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.
+
 ## Local GeoIntel assistant
 
 The assistant is an optional read-only language interface over persisted

docs/DATA_SOURCES.md

@@ -217,9 +217,6 @@ until a governed operator import, provenance record and validation pass exist.
 - Biologische Waarderingskaart / Natura 2000 (INBO), state 2025: suitable for
   habitat, biotope and ecological-value analysis, not a continuous annual
   series.
-- Agricultural-use parcels (Agentschap Landbouw en Zeevisserij): annual files
-  suitable for crop and agricultural-surface evolution after schema/version
-  harmonization.
 - Buildings and Addresses Register (Digitaal Vlaanderen): continuously updated
   building status, life cycle and address linkage; complementary to GRB
   geometry and not yet imported.
@@ -248,6 +245,32 @@ especially outside Habitats Directive areas, can still be based on older
 mapping. GeoIntel therefore preserves origin fields and never presents this
 single edition as a historical trend.
 
+## Governed annual agricultural-use parcels
+
+`scripts/provision_agricultural_parcel_history.py` uses the official annual
+download archives published by Agentschap Landbouw en Zeevisserij. Only the
+definitive editions 2008-2025 are allowed. The provisional current-campaign
+snapshot is deliberately excluded, and the retiring Digitaal Vlaanderen
+`Landbgebrperc` WFS is not used as the long-term source path.
+
+Each official ZIP, SHA256 checksum, full-edition crop code list and manifest is
+retained. The temporary GeoPackage is validated as EPSG:31370 with the stable
+annual field set, read through the GIS optional dependencies and deleted after
+the normalized GeoJSON has been built. Geometry is clipped exactly against the
+persisted scope Area in Lambert 72 and imported only through DatasetService.
+
+The regional default creates the series
+`alz:agricultural-use-parcels:kempen-transport-region`; `--scope mol` creates an
+independent Mol series. Selection and evolution expose exact intersected
+hectares for total declared use and official main-crop groups. Individual
+parcel additions/removals are unavailable because parcel identity is not
+stable across campaign years.
+
+Official catalogues:
+
+- https://landbouwcijfers.vlaanderen.be/open-geodata-landbouwgebruikspercelen
+- https://www.vlaanderen.be/datavindplaats/catalogus/open-geodata-landbouwgebruikspercelen
+
 ## Governed Waterinfo station history
 
 `scripts/provision_waterinfo_station_history.py` uses the public Waterinfo

docs/DATA_SPECIFICATION.md

@@ -228,6 +228,27 @@ an estimate warning, especially for partial rectangle intersections. State
 2025 is a product edition and must not be presented as a uniform 2025 field
 survey or an annual time series.
 
+### Annual agricultural-use parcels
+
+Definitive Agentschap Landbouw en Zeevisserij editions from 2008 through 2025
+are stored as separate annual vector Datasets. The retained source is the
+official ZIP archive containing a Belgian Lambert 72 GeoPackage. Queryable
+geometry is clipped against the persisted Area in EPSG:31370 and normalized to
+EPSG:4326 before canonical `vector_features` persistence.
+
+Stable source fields include `agpakey`, parcel number, declared source area,
+reference id, spring crop, main crop, official main-crop group, production
+method and source municipality. All annual source properties remain available,
+but only `maincropgroup_title` is normalized to a controlled comparison key.
+Detailed crop codes and titles can change meaning or wording between editions;
+their complete annual code list is therefore retained with the source archive.
+
+Historical analysis compares intersected hectares for the complete declaration
+and official main-crop groups. It must not compare individual parcel lineage:
+identifiers, boundaries and declarations are not stable between campaign years.
+The declaration can include water, hedges, buildings and infrastructure, so its
+total is not a cadastral ownership area or cultivated-crop area.
+
 ### Vector
 
 Ondersteund:

docs/STORAGE_ARCHITECTURE.md

@@ -116,6 +116,23 @@ checksums, boundary checksum, page/feature counts, clipping diagnostics and
 official class totals. The final GeoJSON is the retained source artifact while
 `datasets` and `vector_features` remain the canonical queryable PostGIS state.
 
+Definitive agricultural-use parcel evidence lives under:
+
+```text
+storage/operator-evidence/agricultural-use-parcels/{scope}/{year}/
+  agpa_{year}_*_public.zip
+  agricultural_use_parcels_{year}_{scope}.geojson
+  agricultural_use_parcels_{year}_crop_codes.json
+  agricultural_use_parcels_{year}_{scope}.manifest.json
+```
+
+The official ZIP is immutable source evidence and is never removed by normal
+cache cleanup. The extracted GeoPackage is temporary to avoid retaining a
+second full source copy. The normalized GeoJSON is the canonical upload
+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.
+
 Offline demo export artifacts can be inspected and cleaned with:
 
 ```bash