feat(reeds): expose county membership and resolution-aware region alignment helpers

[pesap]

This was generated by AI during triage.

feat(reeds): expose county membership and resolution-aware region alignment helpers

Current behavior

ReEDS runs contain county-to-region mappings such as county2zone.csv and r_county.csv, but consumers must parse these files and implement their own handling for county-level versus balancing-area load profiles. Different regional resolutions can be silently compared at an inappropriate hierarchy level.

Desired behavior or Goal

Expose public r2x-reeds helpers for loading county membership and validating or aligning regions across runs at compatible resolutions, including complete-coverage and ambiguity checks.

Acceptance criteria

• Read supported county membership files into documented region-to-county and county-to-region structures.
• Normalize county identity by stable FIPS keys while preserving display labels.
• Detect split, ambiguous, incomplete, and duplicate county assignments with actionable errors.
• Support alignment in either run order without order-dependent behavior.
• Provide an explicit aggregation result describing matched regions, unmatched regions, coverage, and contributing counties.
• Add fixtures for county-level versus balancing-area runs, reverse order, partial coverage, and ambiguous mappings.

Non-goals

• Loading HDF5 matrices or implementing numerical load-profile comparison.
• Guessing a hierarchy level when an explicit county mapping is available.

Work Plan

Validation

• Run focused region-mapping tests.
• Run repository lint and type checks.

Documentation

• Document county mapping file formats.
• Document resolution compatibility rules and alignment result semantics.

Testing

• Add public behavior tests using representative county2zone.csv and r_county.csv fixtures.
• Add reverse-order and ambiguity fixtures.

Risks

Breaking-change

no

Review-size

medium