EEA source contract

# H05 PM2.5 — EEA source contract v0

Status: RESEARCH / REVIEW  
Scope: source acquisition contract only; no metric validation or publication.

## Purpose
Replace the legacy WebDAV/Datashare discovery path with an explicit official-source contract for H05 PM2.5 gridded annual exposure inputs.

## Authoritative source family
European Environment Agency (EEA) Datahub: **PM2.5, European air quality data (interpolated data)**.

Canonical landing page:
`https://www.eea.europa.eu/en/datahub/datahubitem-view/938bea70-07fc-47e9-8559-8a09f7f92494`

EEA describes this dataset as Europe-wide grid-level PM2.5 concentrations produced by a regression/interpolation/merging mapping methodology combining monitoring data and observational station values. The PM2.5 indicator is annual average concentration. The series currently exposes annual datasets from 2007–2008 and 2010–2025; the 2025 artifact is explicitly interim data published 29 May 2026.

A broader EEA interpolated-air-quality series page also exposes annual GeoTIFF datasets and direct-download links:
`https://www.eea.europa.eu/en/datahub/datahubitem-view/82700fbd-2953-467b-be0a-78a520c3a7ef`

## Acquisition rule
The pipeline MUST resolve an annual artifact from the official EEA Datahub record or an EEA-owned direct-download target linked by that record. It MUST NOT treat the historical WebDAV/Datashare path as the production contract.

For every acquired artifact, persist at minimum:
- pollutant = PM2.5;
- statistic = annual average;
- reference year;
- publication/release date when supplied;
- validation status when supplied (for example interim/provisional vs validated/final);
- EEA landing-page URL;
- exact resolved download URL or immutable artifact identifier if available;
- retrieval timestamp;
- file name, byte size and SHA-256 checksum;
- source metadata/factsheet URL when available;
- declared spatial reference, grid/resolution and nodata semantics from the artifact/metadata;
- licence/reuse evidence and attribution text.

## Fail-closed gates
Acquisition fails and the artifact MUST NOT enter a validated H05 pipeline when any of the following is unresolved:
1. artifact cannot be traced to an official EEA Datahub record;
2. reference year or annual-average statistic is ambiguous;
3. interim/provisional status is unknown when relevant;
4. checksum cannot be recorded after retrieval;
5. CRS/grid/nodata semantics cannot be established before spatial processing;
6. dataset-specific rights or applicable EEA reuse terms cannot be documented;
7. the resolved target is only a legacy discovery endpoint with no stable EEA Datahub provenance.

## Rights posture
EEA pages state a standard reuse policy permitting reuse unless otherwise indicated, subject to acknowledgement. This is useful evidence but is **not yet sufficient to promote H05 acquisition to VALIDATED**: the annual dataset metadata/factsheet and any dataset-specific rights statement must be captured with the artifact before promotion.

## Temporal policy
- Prefer the latest **validated/final** annual artifact for validated comparisons.
- Interim/provisional annual artifacts may be ingested only as `RESEARCH` and must retain that status in downstream outputs.
- Do not silently mix final and interim years in a trend without explicit status fields.

## Validation checks for the acquisition implementation
A future downloader/resolver should be tested to prove that it:
- resolves a requested year from the official EEA Datahub family;
- rejects an unavailable or ambiguous year;
- records the exact resolved artifact and checksum;
- records release/validation status;
- does not fall back silently to legacy WebDAV;
- emits provenance metadata independently of the raster computation core.

## Evidence checked 2026-09-12
- EEA FAQ confirms that historical/current air-pollutant concentration data behind its viewers are downloadable.
- EEA PM2.5 Datahub record identifies a Europe-wide interpolated annual-average grid series and exposes annual GeoTIFF datasets/direct downloads.
- EEA 2025/2026 air-quality material distinguishes validated historical data from provisional/up-to-date or interim data, supporting explicit release-status handling.
- EEA map metadata states the standard EEA reuse policy, while this contract still requires dataset-level rights capture before validation.

## Remaining gate
The 2024 official artifact is now resolved and retrieved; byte size, SHA-256, CRS, grid, band type, scale/offset and technical nodata are captured. Promotion remains blocked because the band does not encode its unit and 786,227 non-masked cells equal `-99.0` without documented semantics in the inspected official metadata. Resolve those two source-semantic issues before spatial processing. No territorial H05 value should be promoted beyond `RESEARCH` until they and the previously defined spatial alignment/resampling tests pass.