geointel/docs/accuracy-program/02-data-lineage.md

# GeoIntel Accuracy Improvement Program — 02 Data-lineage

## 1. Scope en bewijsregel

Deze lineage-audit volgt een resultaat terug naar project/AOI, bronbestand, datasetversie, tile of vectorfeature, model of algoritme, runparameters, QA/QC en export. Een veld dat in het schema bestaat maar leeg is, geldt niet als lineagebewijs. Een door de gebruiker aangeleverde string geldt evenmin als bewijs van officiële bronautoriteit.

De runtimecijfers komen uit de gebonden read-only snapshot van 1 augustus 2026 in:

- `C:\Projects\geointel\artifacts\evidence\accuracy\P1\tower-runtime-database-snapshot-detailed.json`;
- `C:\Projects\geointel\artifacts\evidence\accuracy\P1\tower-gpu-inference-smoke.json`;
- `C:\Projects\geointel\artifacts\evidence\accuracy\P1\tower-ml-data-lineage-snapshot.json`.

Containerpaden beginnen met `/app`; dezelfde persistente volumes staan op de host onder `/mnt/user/appdata/geointel`.

## 2. Canonieke resultaatketen

```mermaid
flowchart LR
    S["Externe bron of upload"] --> F["Bestand / API-respons"]
    F --> D["Dataset + DatasetVersion"]
    D --> V["VectorFeature(s)"]
    D --> T["Rastertiles + manifest"]
    V --> A["AnalysisRun / geoprocessing"]
    T --> M["Modelbestand + adapter"]
    M --> R["Detection / Segmentation"]
    A --> Q["QualityCheck + Metric"]
    R --> Q
    A --> E["Export"]
    R --> E
    Q --> E
```

De feitelijke persistencevelden staan in `backend/app/models/entities.py`:

- `Dataset`: `project_id`, `area_id`, `storage_path`, `checksum_sha256`, `derived_from_dataset_id`, CRS/bounds/resolutie/banden, `dataset_role`, `source_name`, `reference_layer_name`, source- en provenance-metadata, tijdvelden, `source_version` en status;
- `DatasetVersion`: versie, storagepad, checksum, bronversie, observatietijd, validiteitsvenster en source/provenance-metadata;
- `VectorFeature`: `dataset_id`, bronfeature-id, klasse, properties en PostGIS-geometrie met SRID 4326;
- `AnalysisRun`: project/AOI/dataset/job, analysetype, status, modelnaam/-versie, parameters, resultaat en tijden;
- `Detection`/`Segmentation`: dataset/run/job, modelnaam/-versie, klasse, confidence, EPSG:4326-geometrie, pixelbbox, bron-tile en properties/provenance;
- `QualityCheck` en `Metric`: kandidaat-, referentie- en runkoppelingen, parameters, bevindingen en losse metricwaarden;
- `Export`: project, optionele run, type, storagepad en metadata.

Dat is een bruikbaar schema, maar de audit toont breuken tussen schema, invoercontrole en opgeslagen werkelijkheid.

## 3. Brondatasets en versies

### 3.1 Volledigheid van kernvelden

| Controle | Datasetresultaat | DatasetVersion-resultaat | Interpretatie |
|---|---:|---:|---|
| totaal | 3.377 | 1.671 | alle 3.377 datasets hebben status `ready` |
| checksum ontbreekt | 0 | 0 | bestandsidentiteit is op rijniveau aanwezig |
| CRS ontbreekt | 0 | n.v.t. | aanwezigheid bewijst nog niet dat coördinaten correct getransformeerd zijn |
| `imported_at` ontbreekt | 0 | n.v.t. | importtijd is gevuld |
| source metadata ontbreekt | 0 | 0 | metadataobject aanwezig; semantische authenticiteit niet bewezen |
| provenance metadata ontbreekt | 0 | 0 | provenanceobject aanwezig; inhoud kan caller-controlled zijn |
| storagepad ontbreekt | n.v.t. in deze query | 0 | 5.816 directe storagepaden apart fysiek gecontroleerd |
| `observed_at` ontbreekt | 2.377 | niet in deze gapquery | bronfamiliebeleid nodig: sommige vaste/scenariobronnen kunnen legitiem geen observatietijd hebben |
| `source_version` ontbreekt | 1.761 | niet in deze gapquery | geen betrouwbare freshness/reproduceerbaarheid zonder bronfamilieclassificatie |

“Metadata aanwezig” mag niet worden omgezet in “officiële lineage geldig”. `POST /datasets/upload` in `backend/app/api/routes/datasets.py:142-163` laat de caller `source_name`, `reference_layer_name`, source-/provenance-metadata en `source_version` invullen. De dekkingsresolver vertrouwt die waarden later als materialisatiebewijs. Een in-memory reproductie met een user-upload die zich als `grb`/`buildings` presenteerde, werd als operationele, gezaghebbende GRB-dekking teruggegeven. Er is dus een cryptografische bestandsketen, maar geen afgedwongen bronautoriteitsketen.

### 3.2 Waargenomen bronnen

De volgende rijen zijn feitelijk in de Tower-database waargenomen. `reference` is alleen de opgeslagen datasetrol/-metadata, geen onafhankelijke bevestiging door de genoemde instantie.

| `source_name` | datasets | reference |
|---|---:|---:|
| `manual` | 1.751 | 660 |
| `vmm_flood_hazard` | 339 | 0 |
| `vmm_vha_bathymetry_profiles` | 273 | 273 |
| `department_omgeving_thematic_raster` | 210 | 0 |
| `grb` | 179 | 179 |
| `digitaal_vlaanderen_orthophoto` | 168 | 0 |
| `spw_orthophoto` | 107 | 0 |
| `spw_picc` | 68 | 68 |
| `digitaal_vlaanderen_dhmv` | 60 | 0 |
| `urbis` | 36 | 36 |
| `urbis_orthophoto` | 26 | 0 |
| `waterinfo` | 26 | 26 |
| `department_omgeving_land_use` | 25 | 25 |
| `historical_landuse` | 21 | 21 |
| `agentschap_landbouw_zeevisserij_agricultural_parcels` | 18 | 18 |
| `statbel` | 15 | 15 |
| `dov_soil_map` | 13 | 13 |
| `inbo_bwk_natura2000` | 12 | 12 |
| `spw_walous_land_cover` | 7 | 0 |
| `vrbg` | 6 | 0 |
| `fixture` | 5 | 1 |
| `ngi_adminvector` | 4 | 4 |
| `map_selection` | 3 | 0 |
| `digitaal_vlaanderen_buildings_addresses_register` | 1 | 1 |
| `rbins_marine_reporting_units` | 1 | 1 |
| `rbins_msp_2026` | 1 | 1 |
| `spw_bathymetry` | 1 | 0 |
| `spw_terrain` | 1 | 0 |

Deze telling bewijst historische materialisatie, niet dat iedere externe endpoint op de peildatum bereikbaar of actueel was.

## 4. Vectorlineage

### 4.1 Bedoelde keten

`bron/upload -> Dataset + checksum/CRS/provenance -> VectorFeature rows -> spatial operation/AnalysisRun -> derived Dataset -> QA/export`.

De database bevat 6.689.447 vectorfeatures. De gebonden PostGIS-query vond 0 lege, 0 ongeldige, 0 niet-4326 en 0 buiten-4326-domeingeometrieën in de huidige tabel. Dat sluit drie concrete codeproblemen niet uit:

1. `backend/app/services/geojson_service.py:70-94` leest CRS-metadata, maar `vector_feature_service.py:271-299` krijgt die CRS niet mee en schrijft iedere feature met `srid=4326`. Een EPSG:31370-geometrie rond `(150000, 210000)` kon daardoor ongetransformeerd als 4326 worden opgebouwd. De huidige tabelquery bewijst alleen dat zo'n waarde nu niet in `vector_features` staat; het importpad blijft foutgevoelig.
2. `vector_operations_service.py:179-190` voert `geometry.buffer(distance_m)` uit op de geladen geometrie zonder metrische reprojection. De retained reproductie van een 100-meterbuffer leverde 200 graden span en bounds `[-95, -49, 105, 151]`.
3. `_persist_derived_dataset` heeft in `vector_operations_service.py:414-427` standaard `persist_vector_features=False`. Clip, buffer en intersect kunnen daardoor een `ready` GeoJSON-artifact en dataset opleveren zonder querybare `vector_features`, zonder AnalysisRun-koppeling en met een niet-atomische persistenceketen.

Lineageconclusie: validiteit van de huidige PostGIS-rijen is bewezen; een algemeen correct vectorimport-/operatiecontract is dat niet.

## 5. Raster- en tilelineage

Een rasterdataset bewaart bestandspad, checksum, CRS, bounds, resolutie en bandmetadata. Inference gebruikt een tegelmap onder `/app/storage/tiles/<project>/<dataset>/<run>/` met `manifest.json` en GeoTIFF-tiles.

De representatieve read-only smoke gebruikte:

| Artifact | Pad | SHA-256 |
|---|---|---|
| manifest | `/app/storage/tiles/cb80638d-dbef-48ac-b19c-cec7c3efc96e/ae0ff76d-70c0-404f-b777-54d14517179a/b191c968-7d56-4e0d-afbb-8b5baaa62470/manifest.json` | `6ab8a96bf2a1405e224932afb90255311a09bbeaed4e9a2fdcdf8b1bc2230abd` |
| tile | dezelfde map, `tile_0000.tif` | `134a9e86850c92c577c73bc6ee57a9df7d4c1c513ae6450263e800b6dd47b6ee` |
| actief model | `/app/models/geointel-building-yolov8s-smallbld-minpx3-img640-ft30.pt` | `a9088b8491dfae36694b53e9e9406cb4e3511d334a5712fa34f75078a47759c1` |

De tile is 669.227 bytes, 512×512, 3×`uint8`, CRS EPSG:31370, resolutie 0,9765625 meter/pixel en bounds `[193277.53584918313, 205708.27443503588, 193777.53584918313, 206208.27443503588]`. Dit is voldoende om deze ene inference-input exact te identificeren. Er is nog geen corpusbrede toets op duplicate/near-duplicate imagery, nodata, source-date/label-date, WMS-resampling, grenspadding of resolutieconsistentie.

## 6. Detectielineage

### 6.1 Persistente productieketen

`Dataset -> tile manifest -> AnalysisRun(parameters/model_name/model_version) -> Detection(source_tile_path/pixelbbox/confidence/EPSG:4326 geometry) -> QualityCheck/Metrics -> Export`.

Tower bevat 1.146 `analysis_runs`, alle type `detection` met modelnaam `yolo-configured`: 1.144 success en 2 failed. Daaruit zijn 299.233 detecties aanwezig. Geen confidence lag buiten `[0,1]`. De modelversie is bij alle 1.146 runs leeg. 1.143 runs bewaren wel een modelassethash; drie niet. Alle runs bewaren een tile-manifestpad, maar geen tile-manifest-SHA, runtime-/hardware-identiteit of seed. De drie hashloze runs zijn niet sluitend aan een checkpoint te koppelen; ook de overige missen het volledige reproduceerbare inferencecontract.

De read-only smoke riep de productieadapter rechtstreeks aan met seed `20260801`, deterministische algoritmen, confidence 0,5, `imgsz=640`, `max_det=1000` en `cuda:0`. Resultaat: 17 `building`-boxes, confidence 0,500877–0,814435, gemiddelde 0,559481. De smoke schreef geen DB-records en testte dus niet de volledige georeference-/persistence-/QA-keten.

### 6.2 Bewezen historische lineagebreuk

Vier detecties in run `7ba34274-411d-45e3-8f54-c37baec598b1` hebben een PostGIS-geometrie met SRID 4326 maar numerieke Lambertwaarden rond X 193.278–193.774 en Y 205.708–206.054. Alle vier verwijzen naar:

- project `GeoIntel Real Data Validation 20260706T235847Z`;
- dataset `ae0ff76d-70c0-404f-b777-54d14517179a`, `geel_orthophoto_wms_512.tif`, bron `manual`;
- tile `/app/storage/tiles/cb80638d-dbef-48ac-b19c-cec7c3efc96e/ae0ff76d-70c0-404f-b777-54d14517179a/b191c968-7d56-4e0d-afbb-8b5baaa62470/tile_0000.tif`;
- creatietijd 6 juli 2026 en class `building`.

Dit zijn aantoonbaar buiten-domeindetecties; de collector markeerde de sectie desondanks generiek als `status: ok`, zodat consumenten de detailtellingen moeten gebruiken. De huidige `detection_georeferencing.py` bevat wel een pyproj-transformatie naar EPSG:4326; op basis van deze audit kan niet worden bewezen via welke historische codeversie de vier rijen ontstonden. Ze mogen niet in QA, kaarten of exports blijven zonder quarantaine/herberekening.

### 6.3 Scopebinding

`detection_service.py:223-232` laat configured YOLO alleen toe wanneer één van `Mol,Kempen` als substring in de muteerbare `Area.name` voorkomt. Een area met naam `Mol validation bypass` en een geometrie buiten de gevalideerde zone werd in de reproductie geaccepteerd. De model-toepassingsscope heeft daardoor geen onveranderlijke geometrische lineage.

## 7. QA/QC-, review- en exportlineage

Tower bevat 697 quality checks en 4.182 metrics. De metricgapquery toont:

| Metric | total checks | null |
|---|---:|---:|
| precision | 697 | 58 |
| recall | 697 | 1 |
| F1 | 697 | 58 |
| mean IoU | 697 | 90 |
| false positives | 697 | 0 |
| false negatives | 697 | 0 |

De golden fixturebenchmark koppelt kandidaat/referentie, QualityCheck en zes metrics correct in-memory. Bij het no-overlapscenario zijn precision en recall `0`, maar F1 en mean IoU `null`. Zolang het API-/metriccontract niet expliciet vastlegt of F1 daar `0` of “undefined” hoort te zijn, kunnen aggregaties dezelfde run verschillend behandelen.

Er staan 0 `detection_reviews` in de productiedatabase. De aanwezigheid van review-UI, contact sheets of reviewtabellen bewijst dus geen uitgevoerde menselijke productiereview. De 768 exportrecords verwijzen naar concrete storagepaden; dat bewijst artifactpersistentie, niet dat upstream geometrie/model/QA correct was.

## 8. Trainings- en corpuslineage

### 8.1 Bewezen v56-keten

De retained snapshot telt in totaal 26 modelassets, 229 trainingscheckpoints (28.512.052.142 bytes), 424 JSON-trainingsrapporten en 36 operator-manifests. Die inventarisclaim zegt niets over menselijke acceptatie of releasekwaliteit.

Het canonieke v56-manifest is `/app/storage/operator-data/building-be-v56-hard-negative-instance-roofs-r1/operator_samples_manifest.json`, 212.185 bytes, SHA-256 `27a9b09f184bb9a0cc4897f1cfab7f1e953af5715c1b97a5ec1a7b80a2d270f1`. De corpusaudit `/app/storage/training/building-be-v56-corpus-audit-r1/belgium-building-corpus-audit.json` (SHA-256 `cbb9802aec1b780b306318fc172e470d29166574e9bf13d28e3107ae42f4d63c`) rapporteert:

- datasetversie `building-be-v56-hard-negative-instance-roofs-r1`, immutable manifest;
- 180 AOI-samples: Vlaanderen 89 train/2 val/3 calibration/3 test/2 background-test; Wallonië 43/2/3/3/2; Brussel 18/2/3/3/2;
- 132 positieve samples en 48 `background_candidate`-samples;
- 31.452 inputfeatures, 30.662 geaccepteerd, 326 onder resolveerbare pixelgrootte en 464 na de beeldperiode;
- automated `spatial_leakage_status=ok` en 0 temporal-unknown samples;
- `status=needs_human_review`, `reviewed_sample_count=0`, `review_complete=false`, alle 180 in de reviewqueue.

Van de zes `background-test`-AOI's zijn er slechts drie aantoonbaar puur leeg: twee in Vlaanderen, één in Wallonië en nul in Brussel. De andere drie bevatten respectievelijk 2, 107 en 141 referentiefeatures en zijn moeilijke negatieven, geen pure backgrounds. Dit is te weinig om een regionale pure-background false-positiveclaim te dragen.

De bounded duplicaatscreen vond 0 exacte cross-split rasterhashduplicates en 0 hergebruikte raster-dataset-id's. Voor 4.833 cross-split dHash-paren was de minimum-Hammingafstand 17 en waren er geen paren op of onder 4. Dat sluit semantische, instance-level of flight-stripduplicatie niet uit. De AOI-bboxscreen vond een minimale cross-splitafstand van 95,7203 meter tussen `anderlecht-industry-train` en `jette-test`, 24 paren onder 2 km en 0 onder 64 meter. De auditstatus `ok` is daarom niet voldoende voor de strengere onafhankelijkheidseis; nabijheid is een risico dat instance-/imagerylineage vereist, geen bewijs op zichzelf van leakage.

De tile-qualityaudit `/app/storage/training/building-be-v56-rotated-quality-audit-r1/operator_yolo_dataset_quality_audit.json` (SHA-256 `da0d4648ee2365ab949f1b00518ddba0a17cb722a41cb228525b4d2e7657ce36`) rapporteert geautomatiseerd `status=ok`, 2.496 tiles, 60.229 labels, 0 ongeldige/missende labelfiles, 2.072 positieve en 424 negatieve tiles, waarvan 411 negatieve trainingtiles. Dat syntactische bewijs vervangt de ontbrekende menselijke semantische review niet.

De v58/v62-calibratierapporten verwijzen naar een afgeleide root `/app/storage/operator-data/building-be-v56-hard-negative-rotated-holdouts-r1`. Een releasebundel moet de transformatie van het canonieke instance-roofs-manifest naar deze rotated-holdouts-dataset expliciet, gehasht en reproduceerbaar vastleggen.

### 8.2 Bewezen v58/v62-preview, niet gepromoveerd

V58 `/app/storage/training/building-be-v58-v56-clean-pretrained-r1/preview-epoch-015/calibration.json` (SHA-256 `60538573a734d91107e25fb2a8a640ce45d90c482acfb65ed7110ff884f2f4c7`) en v62 `/app/storage/training/building-be-v62-v58-flanders-balanced-transfer-r1/preview-epoch-006/calibration-routed.json` (SHA-256 `05d8c8f0ade55907e37668758ac225aeff60cbb45604de662944fa447f6d590f`) zijn beide 144-tile, `split=val`, IoU-0,5 calibratiepreviews met 13 thresholds. Ze zijn geen protected-test-, unieke-gebouwen- of nationale releaseresultaten.

Bij threshold 0,15 rapporteren beide artifacts aggregate F1 0,512905, precision 0,545647 en recall 0,483871, maar Vlaanderen heeft true positives 0, recall 0 en F1 0. Bij threshold 0,02 heeft v58 aggregate F1 0,240667 en Vlaanderen F1 0,080402/recall 0,103380; v62 heeft aggregate F1 0,208283 en Vlaanderen F1 0,067111/recall 0,275348. Geen van deze observaties voldoet aan een geloofwaardige drie-regio-gate.

De v62-checkpointhash `889ee5…` verschilt van de actieve productiemodelhash `a9088b…`; de v62-run is dus niet het actieve model.

### 8.3 V66 is een gerichte trial

Het immutable manifest `/app/storage/operator-data/building-be-v66-lowrise-temporal-r1/operator_samples_manifest.json` (SHA-256 `d861da48aca40121e158e6ab243a6ccbe53e14d500a186af64b620f612935b07`) bevat drie positieve Vlaamse trainingssamples, nul andere splits/regio's en nul background-test-samples. Het kan v56 niet als nationale corpusbaseline vervangen.

### 8.4 Protected-testleakage in de loop

`scripts/run_belgium_building_training_loop.py:417-449` opent test en background nadat calibration slaagt. Wanneer de volledige assessment niet `training_complete` is, wordt die assessment op regels 477-498 als input gebruikt voor de volgende failure-driven trainingsset. `scripts/build_failure_driven_yolo_sampling.py:98-120` kiest expliciet `assessment.get("test") or assessment.get("calibration")` en gebruikt ook background-failures; regels 130-201 sturen vervolgens regionale/contextuele repeats van trainingtiles.

De sampler neemt geen protected tiles zelf op, maar de protected-testuitkomsten beïnvloeden wél de volgende trainingsverdeling. Daarmee is de testset een tuningbron geworden en kan zij niet langer als onafhankelijke, eenmalige protected test voor de uiteindelijke kandidaat gelden.

## 9. Lineagebreuken die Phase 2 moeten blokkeren

| ID | Breuk | Bewijs | Gevolg |
|---|---|---|---|
| LIN-01 | caller-controlled bronautoriteit | uploadvelden + coverage-reproductie | “officieel/operationeel” kan vals zijn |
| LIN-02 | cross-theme coverage-union | `coverage_registry_service.py:481-504` | kleine juiste laag kan volledige dekking erven van verkeerde laag |
| LIN-03 | niet-4326 import als SRID 4326 | `geojson_service.py` versus `_feature_row` | geometrie kan valide lijken maar ruimtelijk betekenisloos zijn |
| LIN-04 | meters als graden bij buffer | 100 m-reproductie | extreme, foutieve derived geometrieën |
| LIN-05 | derived artifact zonder querybare features/run | `persist_vector_features=False` | UI/artifact en PostGIS geven verschillende waarheid |
| LIN-06 | modelscope via naamsubstring | area-name-reproductie | inference buiten gevalideerde scope mogelijk |
| LIN-07 | lege modelversie bij 1.146 runs; 3 zonder modelhash; 1.146 zonder tile-manifest-SHA/runtime/seed | Tower-runtime-snapshot | historische run niet volledig reproduceerbaar; drie runs niet sluitend aan checkpoint te koppelen |
| LIN-08 | vier Lambert-detecties als SRID 4326 | gedetailleerde DB-snapshot | kaart, QA en export kunnen corrupte geometrie consumeren |
| LIN-09 | 0 menselijke productiereviews | `detection_reviews=0` | geen bewijs van representatieve operatoracceptatie |
| LIN-10 | v56 human review 0/180 | corpusaudit | label-/tijd-/contextkwaliteit niet semantisch vrijgegeven |
| LIN-11 | slechts 3 pure-empty backgrounds; 24 cross-split AOI-paren onder 2 km | retained v56-manifestanalyse | regionale background- en onafhankelijkheidsclaims zijn niet vrijgegeven |
| LIN-12 | v66 bevat alleen 3 Vlaamse training-AOI's | retained v66-manifest | gerichte trial mag niet als nationale opvolger worden behandeld |
| LIN-13 | protected test stuurt retraining | trainingloop + sampler | evaluatieleakage; releaseclaim ongeldig |

## 10. Reproduceerbare controles

Lokale evidence opnieuw opbouwen:

```powershell
cd C:\Projects\geointel
python scripts\run_accuracy_phase1_baseline.py --output-dir artifacts\evidence\accuracy\P1
$env:PYTHONPATH = "$(Resolve-Path backend);$(Resolve-Path .)"
python scripts\run_golden_qa_benchmark.py --json
```

Tower-artifactidentiteit read-only controleren:

```bash
sha256sum \
  /mnt/user/appdata/geointel/models/geointel-building-yolov8s-smallbld-minpx3-img640-ft30.pt \
  /mnt/user/appdata/geointel/storage/operator-data/building-be-v56-hard-negative-instance-roofs-r1/operator_samples_manifest.json \
  /mnt/user/appdata/geointel/storage/training/building-be-v56-corpus-audit-r1/belgium-building-corpus-audit.json \
  /mnt/user/appdata/geointel/storage/training/building-be-v62-v58-flanders-balanced-transfer-r1/preview-epoch-006/calibration-routed.json
```

De runtimecollector is read-only en gebruikt een SQL-statementtimeout van 30 seconden. Een toekomstige releasegate moet dezelfde queries uitvoeren én detailtellingen laten falen; een generiek `status=ok` mag vier buiten-domeinrecords niet maskeren.