feat: basin-aware region clustering

[koen-vg]

Rebased onto main after the #31 squash; all commits are in scope. Do not merge before the water restructure PR, which carries the single recalibration for the whole structural series; see "Calibration" below.

Model regions are now built basin-aware. GADM provinces are split along AWARE hydrological basin boundaries before clustering, so a province straddling an abundant and a scarce basin is no longer pooled into one region — which averaged away exactly the sub-provincial scarcity that constrains irrigation. Each country is then partitioned into exactly target_count regions balancing geography against basin scarcity.

The nesting invariant is preserved: every region is either contained in one province (large provinces split into sub-regions) or a union of whole provinces (small provinces merged), never a mix of partial pieces across provinces — so regions stay comparable to political units. The allow_cross_border config option is removed entirely: basin-aware clustering has no cross-border path, so a key whose only valid value is false was dead weight.

Two corrections relative to the water-aware original

The per-country region budget was wrong. It summed the geodesic area of one arbitrary basin fragment per province, so countries whose provinces are cut into many basins were systematically starved of regions: Russia lost 27, China 12, Indonesia 10, while the DRC gained 12 and Nigeria 11. Area is now summed over all pieces, and the capacity cap is the piece count rather than the province count, since a province can now legitimately yield more than one region. A regression test covers this and fails against the original code.

basin_scarcity_weight is 2.0, not 3.0. The original comment claimed it was "tuned empirically against region-size evenness", which the data did not support. Swept on the full 750-region default set:

weight	within-region CF spread	p95/median area	largest region
0 (geographic)	10.34	2.38	92 Mha
1	8.27	2.71	91 Mha
2	7.60	3.21	91 Mha
3	7.40	3.27	110 Mha
5	7.18	3.29	133 Mha

Scarcity separation saturates by weight 2 (against a floor of ~7.2), beyond which only the size tail degrades. The config comment now states this trade-off honestly.

Also

The basin overlay is guarded: a configured country with no basin overlap is an error rather than a silent disappearance, and the dropped sliver area — 0.05% of land on the default country set, coastal fragments and small islands outside every basin — is logged.

Only the AWARE basin geopackage (5.3 MB) is fetched here. The two AWARE workbooks that the water supply restructure needs are left for that PR.

Impact

This changes default region geometry for every config, so Snakemake rebuilds the whole processing/{name}/ tree, and regional doc figures will need regenerating.

Calibration

test_calibration_provenance.py::test_default_stamp_matches_default_config fails on this branch by design: basin_scarcity_weight is a new structural key absent from the tracked stamps, and region geometry genuinely changes, so grassland yields, feed conversion, costs and deviation penalties are all fit against a different spatial partition. Per the repo owner's decision, the structural series (multi-cropping → this → water restructure) ends with a single tools/calibrate run for both tracked sets rather than three thrown-away ones. That is why this must not merge on its own.

Review follow-ups

Post-review polish: dropped a redundant buffer(0) after set_precision (whose valid_output mode already guarantees validity) and flagged empty geometries alongside invalid ones in both validity checks; removed the allow_cross_border option; factored the duplicated area-weighted province-centroid computation into a helper; k-means now weights samples by piece area so slivers don't pull centroids; the pieces-scarce test now actually exercises the reconciliation split path.

Verification

Build and integration tests (dryrun + build/solve/analyze) pass with the new geometry; 8 unit tests cover apportionment, the exact region count, the nesting invariant, scarcity-driven splitting, reconciliation, cross-border rejection, and the budget regression.