[v4] Accept dict reforms on Simulation(policy=/dynamic=)

[MaxGhenis]

Summary

Last piece of the v4 agent-first reform surface: Simulation(policy={...}) and Simulation(dynamic={...}) now accept the same flat dict that pe.{uk,us}.calculate_household(reform=...) accepts.

Before

from policyengine.core import Simulation, Policy, Parameter, ParameterValue
import datetime

reform_policy = Policy(
    name="CTC base $3,000",
    parameter_values=[
        ParameterValue(
            parameter=Parameter(
                name="gov.irs.credits.ctc.amount.base[0].amount",
                tax_benefit_model_version=pe.us.model,
                data_type=float,
            ),
            start_date=datetime.date(2026, 1, 1),
            end_date=datetime.date(2026, 12, 31),
            value=3_000,
        )
    ],
)
reform_sim = Simulation(
    dataset=dataset, tax_benefit_model_version=pe.us.model,
    policy=reform_policy,
)

After

reform_sim = Simulation(
    dataset=dataset, tax_benefit_model_version=pe.us.model,
    policy={"gov.irs.credits.ctc.amount.base[0].amount": 3_000},
)

Same shape accepted by both entry points. Same effective-date semantics (scalars default to {year}-01-01 using dataset.year). Same validation (unknown paths raise with close-match suggestions).

Implementation

• New compile_reform_to_policy / compile_reform_to_dynamic helpers in tax_benefit_models.common.reform.
• Simulation.policy / Simulation.dynamic typed as Optional[Union[Policy, dict[str, Any]]] / Optional[Union[Dynamic, dict[str, Any]]].
• @model_validator(mode="after") compiles dicts to full Policy / Dynamic once tax_benefit_model_version and dataset are on self.
• Missing tax_benefit_model_version with a dict reform raises a directed error.

Tests

tests/test_dict_reforms_on_simulation.py (6 tests, no network, no HF token):

• scalar reform → ParameterValue with start_date = {year}-01-01
• {date: value} mapping → multiple ParameterValues with matching start_date
• unknown parameter path → ValueError with "did you mean" hint
• existing Policy object → passes through unchanged
• dict without tax_benefit_model_version → raises
• dynamic={...} coerces to Dynamic

Full suite: 397/397 pass locally. End-to-end microsim sanity-checked: Simulation(policy={"gov.irs.credits.ctc.amount.base[0].amount": 3_000}) produces -$25.5B revenue impact, identical to the hand-built Policy path.

Stack

Stacked on #295 (docs refresh). Retargets to main once the earlier stack merges.

🤖 Generated with Claude Code

[MaxGhenis]

Superseded by #298 (consolidated v4 launch PR). All commits cherry-picked cleanly onto v4.