Add CTC artifact comparison diagnostics to national validation

[MaxGhenis]

Summary

• add compare-mode support to validate_national_h5 for artifact-to-artifact CTC comparisons
• report current-law CTC total drift plus AGI, filing-status, child-count, and child-age diagnostic deltas
• report canonical CTC reform drift between two national artifacts
• add focused unit coverage and a changelog fragment

Why

This implements the validation half of #725. We can already compare aggregate CTC totals, but recent adjacent artifacts showed that CTC reform sensitivity can move because the child composition moves even when top-line current-law totals stay close.

Using the new comparison output on adjacent staged national artifacts showed:

• total ctc_qualifying_children moved only about -570k
• but the mix shifted materially from 1- and 2-child units toward 3+ child units
• the biggest shifts were compositional inside low/mid AGI and filing-status cells

That is exactly the failure mode we need the validator to surface.

Issue tracking

• Closes Add child-composition CTC targets or validation #725
• Follow-on sourcing issue for external child-composition benchmarks: Source external benchmarks for CTC child-composition calibration #729

Testing

• uv run pytest tests/unit/calibration/test_validate_national_h5.py -q
• uv run pytest tests/unit/calibration/test_ctc_diagnostics.py -q
• uv run ruff check policyengine_us_data/calibration/validate_national_h5.py tests/unit/calibration/test_validate_national_h5.py
• uv run python -m policyengine_us_data.calibration.validate_national_h5 --help

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
pipeline-diagrams	Error		Apr 11, 2026 2:15pm