Add local H5 contracts and partitioning seam

[anth-volk]

Fixes #744

Context

This starts the H5 architecture migration as a series of smaller,
scoped, backwards-compatible PRs instead of one large overhaul branch.

The live pipeline on main works. The goal here is not to replace the
runtime flow yet. The goal is to introduce the first internal seams that
later PRs can build on without continuing to widen the legacy
procedural surface.

How This Fits The Broader Migration

This is PR 1 in the incremental local_h5 migration.

It establishes:

• typed internal contracts for requests, worker results, and validation
  results
• a pure extracted partitioning seam for weighted work scheduling

It does not yet move:

• request construction
• traceability or fingerprinting
• worker bootstrap artifacts
• worker-scoped setup
• one-area build logic
• worker execution orchestration
• coordinator semantics beyond partitioning ownership

Those land in later migration PRs.

What This PR Does

• adds policyengine_us_data/calibration/local_h5/__init__.py
• adds policyengine_us_data/calibration/local_h5/contracts.py
• adds policyengine_us_data/calibration/local_h5/partitioning.py
• introduces:
  AreaFilter
AreaBuildRequest
PublishingInputBundle
ValidationPolicy
ValidationIssue
ValidationResult
AreaBuildResult
WorkerResult
• extracts pure weighted work partitioning into
  partition_weighted_work_items(...)
• updates modal_app/local_area.py::partition_work(...) to become a
  compatibility wrapper over the new pure helper
• adds focused unit tests for contracts and partitioning

What This PR Does Not Do

• does not change public Modal entrypoints
• does not change build_h5(...)
• does not change worker input format
• does not introduce USAreaCatalog
• does not introduce WorkerSession
• does not change geography loading
• does not change fingerprinting
• does not change staging or release behavior

Existing Interface: Preserved vs Replaced

Preserved:

• modal_app/local_area.py public behavior
• partition_work(...) compatibility wrapper and call shape
• current work-item format:
  {"type": ..., "id": ..., "weight": ...}
• current completion-key convention:
  "type:id"
• all current H5 build and publish entrypoints

Replaced internally:

• inline heapq scheduling logic in modal_app/local_area.py is no
  longer the canonical implementation

New canonical internal owner:

• policyengine_us_data.calibration.local_h5.partitioning.partition_weighted_work_items

Testing

Passed:

• python -m py_compile on touched modules and tests
• direct import smoke for the new contracts and partitioning modules

Blocked in this environment:

• uv run pytest tests/unit/calibration/test_local_h5_contracts.py tests/unit/calibration/test_local_h5_partitioning.py tests/unit/test_modal_local_area.py
  because torch==2.9.1 has no compatible wheel for macOS x86_64 here
• python -m pytest ...
  because shared tests/conftest.py imports google.auth, which is not
  installed in the active environment

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
pipeline-diagrams	Error		Apr 13, 2026 8:53pm