Add governed source freshness audit

2026-07-16 15:05:42 +02:00
parent 2723043e3d
commit 1e0e7b6499
22 changed files with 1148 additions and 0 deletions
@@ -1419,3 +1419,27 @@ evidence and existing Dataset. `--force` explicitly refetches the WFS but still
 fails closed if a different state-2025 checksum is already persisted. The
 regional output uses the same selection-summary API as Mol; no new endpoint or
 direct PostGIS write is introduced.
+
+## Source freshness and version audit
+
+`GET /api/v1/projects/{project_id}/datasets/source-freshness` derives a
+read-only source status from persisted Dataset, DatasetVersion and storage
+evidence. It distinguishes rolling snapshots and annual publications from
+fixed editions, scenarios, historical archives and local artifacts. Fixed
+source editions are never called stale solely because they are old.
+
+The endpoint checks missing versions, checksum disagreement, missing local
+files and stored-size disagreement. It performs no provider request and no
+database write. The packaged operator command is suitable for an explicit
+Unraid cron entry:
+
+```bash
+docker exec geointel python /app/scripts/audit_source_freshness.py \
+  --project-id 82a85913-c522-45d7-84a1-02b393d89e55 \
+  --api-url http://127.0.0.1/api/v1 \
+  --fail-on integrity \
+  --output /app/storage/operator-evidence/source-freshness/latest.json
+```
+
+Use `--fail-on due` to make a planned review date fail automation, or
+`--fail-on never` for reporting only. The command never starts a refresh.