Add typed local H5 request construction

[anth-volk]

Fixes #748

Summary

This is PR 2 in the incremental local H5 publication migration.

It introduces typed request construction for local H5 workers and makes USAreaCatalog the canonical owner of request-construction rules, while preserving backward compatibility at the worker boundary.

This is also the first PR that introduces the request contract types actually used by runtime code:

• AreaFilter
• AreaBuildRequest

How It Fits Into The Broader Migration

PR 1 now introduces only the pure partitioning seam.

This PR adds the next boundaries:

• local_h5/requests.py for typed request values used by the worker path
• local_h5/area_catalog.py for US request construction
• typed AreaBuildRequest support at the worker boundary
• catalog-owned default request rules

The coordinator is intentionally not migrated yet. That remains planned for PR 9.

What This PR Does

• adds policyengine_us_data/calibration/local_h5/requests.py
• adds policyengine_us_data/calibration/local_h5/area_catalog.py
• introduces AreaFilter and AreaBuildRequest
• moves state, district, city, and national request construction into the catalog
• teaches modal_app/worker_script.py to accept typed --requests-json input
• preserves legacy --work-items support
• keeps legacy request conversion per-item so malformed legacy items fail individually instead of aborting a whole worker batch
• moves default NYC and at-large request-rule ownership into the catalog via USAreaCatalog.default()
• documents in modal_app/local_area.py that coordinator-side inline request construction is temporary and scheduled for PR 9 migration
• adds narrow unit coverage for request contracts, catalog defaults, and worker request-resolution behavior

What This PR Does Not Do

• it does not migrate modal_app/local_area.py to emit typed requests
• it does not remove legacy work_items
• it does not change build_h5(...) internals
• it does not introduce worker sessions, builders, validation services, or coordinator cleanup
• it does not change coordinator fingerprinting or staging behavior

Existing Interfaces Preserved

These remain supported after this PR:

• modal_app/worker_script.py --work-items ...
• the current coordinator flow that emits legacy work items
• the existing H5 build path through build_h5(...)

Internal Boundaries Replaced Or Made Canonical

• USAreaCatalog is now the canonical place for new request rules
• typed AreaBuildRequest JSON is now supported at the worker boundary
• request-rule defaults are now owned by the catalog layer instead of the worker adapter

Migration State After This PR

After merge:

• request contracts are introduced in the first runtime path that actually uses them
• request construction is canonical in USAreaCatalog
• worker input is dual-path: typed requests or legacy work items
• coordinator request emission remains legacy and is explicitly deferred to PR 9

Testing

Ran locally:

• python -m py_compile policyengine_us_data/calibration/local_h5/__init__.py policyengine_us_data/calibration/local_h5/requests.py policyengine_us_data/calibration/local_h5/partitioning.py policyengine_us_data/calibration/local_h5/area_catalog.py modal_app/local_area.py modal_app/worker_script.py tests/unit/calibration/fixtures/test_local_h5_requests.py tests/unit/calibration/test_local_h5_requests.py tests/unit/calibration/fixtures/test_local_h5_partitioning.py tests/unit/calibration/test_local_h5_partitioning.py tests/unit/calibration/fixtures/test_local_h5_area_catalog.py tests/unit/calibration/test_local_h5_area_catalog.py tests/unit/fixtures/test_modal_local_area.py tests/unit/test_modal_local_area.py tests/unit/fixtures/test_modal_worker_script.py tests/unit/test_modal_worker_script.py
• ruff check policyengine_us_data/calibration/local_h5/__init__.py policyengine_us_data/calibration/local_h5/requests.py policyengine_us_data/calibration/local_h5/partitioning.py policyengine_us_data/calibration/local_h5/area_catalog.py modal_app/local_area.py modal_app/worker_script.py tests/unit/calibration/fixtures/test_local_h5_requests.py tests/unit/calibration/test_local_h5_requests.py tests/unit/calibration/fixtures/test_local_h5_partitioning.py tests/unit/calibration/test_local_h5_partitioning.py tests/unit/calibration/fixtures/test_local_h5_area_catalog.py tests/unit/calibration/test_local_h5_area_catalog.py tests/unit/fixtures/test_modal_local_area.py tests/unit/test_modal_local_area.py tests/unit/fixtures/test_modal_worker_script.py tests/unit/test_modal_worker_script.py
• python -m pytest --noconftest tests/unit/calibration/test_local_h5_requests.py tests/unit/calibration/test_local_h5_partitioning.py tests/unit/calibration/test_local_h5_area_catalog.py tests/unit/test_modal_local_area.py tests/unit/test_modal_worker_script.py -q

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pipeline-diagrams	Error		Apr 14, 2026 7:29pm

[juaristi22]

Approving overall because the incremental migration direction looks sound and the dual-path worker boundary is a sensible step.

Two things I want us to consider before merge:

1. AreaBuildRequest.output_relative_path is only validated as non-empty, and worker_script.py joins it directly with output_dir. That means an absolute path or ../ segments can escape the run directory. Now that --requests-json accepts typed request payloads directly, I think we should either harden this path handling or at least make the constraint explicit.

2. The new contract distinguishes area_id from display_name, but the validation path still uses display_name as the emitted area_id. Worker completion keys are built from area_id, while validation rows and downstream summaries can end up keyed by display_name, which will drift as soon as those fields differ.

Neither is blocking for me on this PR, but I do think they are worth a deliberate check before we merge.

[MaxGhenis]

Please rebase from upstream/main — there are merge conflicts.