[codex] Cache PE SOI targets for rebuild PUF uprating

[anth-volk]

Fixes #147

Summary

• Keeps --soi-path as the explicit override for PE-SOI PUF uprating.
• Adds a cache-backed default SOI resolver: when no explicit SOI path is supplied, microplex-us downloads the pinned PE-style long SOI target table from the PolicyEngine/policyengine-us-data repo into a versioned Microplex cache.
• Stops requiring a local policyengine_us_data/storage/soi.csv file for SOI resolution while preserving repo-local PE-US-data handling for other PUF inputs, including raw PUF/demographics and uprating_factors.csv.
• Adds regression coverage for cached SOI resolution, missing-cache download, schema validation, CLI/provider wiring, and PE-SOI provider behavior without repo-local soi.csv.

Root Cause

The PE-SOI PUF uprating path previously expected policyengine_us_data/storage/soi.csv when only --policyengine-us-data-repo was provided. Fresh PE-US-data checkouts do not reliably materialize that file, while the tracked historical PE-style target table lives at policyengine_us_data/storage/calibration_targets/soi_targets.csv in the PE-US-data repo.

SOI Source

For this PR, the canonical default remains the PE-US-data SOI setup: microplex-us uses the PE-style long soi_targets.csv from a pinned PolicyEngine/policyengine-us-data commit and caches it as soi_targets_pe_us_data_<commit>.csv. This is a dependency on the PE-US-data repo artifact, not an import from the PE-US-data Python package.

I checked the HF policyengine-us-data model, but it does not currently publish the historical long SOI target table needed by this uprating path. It publishes current raw/target DB artifacts that do not cover the required 2015+ historical surface.

Longer term, this should move to Arch: Arch should own source-backed IRS SOI facts/provenance across the needed years, while microplex-us owns the adapter/export into the PE-style target surface used by PUF uprating.

Validation

• uv run --no-sync pytest -q tests/test_puf_source_provider.py -k "soi or download_pe_soi" -> 8 passed, 29 deselected
• uv run --no-sync pytest -q tests/test_puf_source_provider.py tests/pipelines/test_pe_us_data_rebuild.py tests/pipelines/test_pe_us_data_rebuild_checkpoint.py::test_main_passes_donor_condition_selection_override -> 47 passed
• uv run --no-sync ruff check src/microplex_us/data_sources/puf.py tests/test_puf_source_provider.py
• uv run --no-sync python -m py_compile src/microplex_us/data_sources/puf.py tests/test_puf_source_provider.py
• git diff --check

Notes

• GitNexus tools were not exposed in this session, so I used a manual rg caller scan for the touched PUF/rebuild symbols before committing.

[anth-volk]

Review note: I was unsure how aggressively to move SOI target handling away from policyengine-us-data in this PR. Arch may be the long-term home for source-backed IRS SOI facts and provenance, and I opened PolicyEngine/ledger#51 to track backfilling SOI support to 2015. For this PR, though, microplex-us still relies heavily on the PE-style long SOI target surface from policyengine-us-data, so the implementation keeps using the pinned policyengine-us-data repo artifact as the short-term default while preserving --soi-path as the explicit override.

[MaxGhenis]

Closing rather than merging — this targets code that no longer exists in an archived repo. microplex-us was converted to spec-only content in #261 (Jun 7-8) and then archived; data_sources/puf.py and the new soi.py this PR adds are both gone from main, which is why it's CONFLICTING, and the green CI is stale (it ran on the pre-conversion branch head against workflows that were deleted in the same conversion). US build work moved to populace, which has no SOI-targets resolver of this shape and doesn't depend on microplex-us — so if #147 still bites, it needs re-triage against populace, not this repo.

For the record, the design was sound where it counts: the cache filename embeds the pinned policyengine-us-data commit so bumping the ref auto-invalidates, and the tests mock requests.get so there's no test-time network. Two things I'd have asked for were it live, both in soi.py: the cache write is non-atomic (write_bytes straight to the final path, so an interrupted download leaves a truncated file that header-only validation then accepts — temp file + os.replace fixes it), and header-only validation (nrows=0) won't catch a zero-row file. Worth carrying into whatever populace does for SOI sourcing.