Add simulation report outputs and regional filtering for API v2 alpha

[anth-volk]

Fixes #241

Summary

Adds the simulation report infrastructure required for the app v2 migration onto API v2 alpha. This includes regional filtering, geographic impact outputs, demographic poverty breakdowns, and supporting utilities.

Changes

Core

• Variable metadata: default_value and value_type fields on Variable
• Region abstraction: New Region class with registry pattern (core/region.py) and Simulation filtering support

Country-specific regions

• US: States, congressional districts, and places data (countries/us/)
• UK: Constituencies and local authorities (countries/uk/)

New output classes

• CongressionalDistrictImpact — per-district budgetary impact (US)
• ConstituencyImpact — per-constituency budgetary impact (UK)
• LocalAuthorityImpact — per-local-authority budgetary impact (UK)
• IntraDecileImpact — within-decile winners/losers with wealth decile support

Poverty extensions

• poverty_type field on Poverty output
• Age group, gender, and race breakdown convenience functions

US model

• Refactored reform application to construction-time (Microsimulation(reform=...))
• Extracted build_reform_dict / merge_reform_dicts utilities
• Added entity variables: is_male, race, household_state_income_tax, household_income_decile, household_count_people, congressional_district_geoid

Utilities

• entity_utils.py — shared entity-relationship builder and household-level dataset filtering
• parametric_reforms.py — reform dict construction from parameter values

Tests

• 14 new test files with fixtures covering regions, filtering, entity utils, poverty demographics, geographic impacts, and reform application

Design note: Simulation approach by country

UK simulations use the Scenario structure, while US simulations use Microsimulation directly, because policyengine-us does not support Scenarios at this time.

Test plan

• Unit tests pass for all new output classes
• Region filtering correctly subsets datasets by state/district/constituency/local authority
• Poverty demographic breakdowns produce correct age/gender/race splits
• US reform application works at construction time
• Existing tests remain green (no regressions)

🤖 Generated with Claude Code

[nikhilwoodruff]

Can you please stress test this

[anth-volk]

Had Claude work up this explanation:

Summary

Here's the full picture of why p.update() silently fails for the US:

Root cause: ParameterNode._at_instant_cache

Every ParameterNode in policyengine-core has a _at_instant_cache dict
that stores ParameterNodeAtInstant snapshots. When a formula calls
parameters(period).gov.irs.income.bracket.rates, the parameter tree
walks down the nodes and each node caches a frozen snapshot for that
instant. There were 172,651 of these cached entries after a single
income_tax calculation.

p.update() mutates the underlying parameter tree, but does not
invalidate these cached snapshots. So even after clearing all variable
holder arrays, when formulas re-execute and call parameters(period),
they hit the stale _at_instant_cache and get the old pre-update
values.

Why reform= at construction works: It creates an entirely new
TaxBenefitSystem with the reform baked into the parameter tree from
the start — before any _at_instant_cache entries exist.

Why the UK's simulation_modifier approach works: The UK creates
Microsimulation(dataset=input_data) and then calls p.update() before
any calculate() calls. Since no formulas have run yet, there are no
cached snapshots to go stale.

Why the US can't use the same pattern: The US uses the shared
default_tax_benefit_system_instance singleton. Even on a fresh
Microsimulation(), if any prior instance already computed variables,
the shared TBS's ParameterNode._at_instant_cache contains stale
snapshots.

This fits with what I found when originally working on this about a one to one and a half months ago. Hoping to isolate this issue for now, move ahead with the code we have in this PR, then revisit later.