ADR-011: Replace runtime mapper with precomputed lookup table (C-23, D-05) #16

Context

ADR-011 documents the decision to replace the 3,122-line runtime spatial mapper (PriogridCountryMapper) with a precomputed Parquet lookup table. The area-majority algorithm is a confirmed FAO requirement (Release Note 02). The decision is made; implementation is blocked by infrastructure.

See docs/ADRs/011_replace_runtime_mapper_with_precomputed_lookup.md for the full ADR.
See docs/ADR-011_implementation_assessment.md for the detailed assessment of current state, unknowns, risks, and 4 possible approaches.

What's needed to unblock

1. Git LFS access — to run the precomputation against real shapefiles
2. views-pipeline-core in test environment — to test the full pipeline
3. Appwrite access — to verify output against current production data
4. Diff test — run both old mapper and new enricher on same data, verify identical results

Implementation plan (when unblocked)

1. Write precomputation script (scripts/precompute_gaul_lookup.py)
2. Build lookup enricher (views_postprocessing/unfao/enrichment.py)
3. Build alongside the current mapper (config flag to switch)
4. Verify on real data before switching
5. Remove mapper only after production verification

What this resolves

~12 of 22 open risk register concerns (Clusters A, C, D, plus standalones C-07, C-08, C-11, C-12, C-17, C-20).

Risk Register

C-23 (Tier 2, algorithmic divergence), D-05 (resolved: area-based confirmed).

Related

• Falsification campaign: all Layer 2 claims SURVIVED (algorithm correct)
• Sprint 1 tests (PR Sprint 1: Test safety net for source code work #9): integration test is the acceptance test for the replacement
• D-06 resolved: column names pass through to FAO unmodified, keep current names