Add FY2026 HUD Fair Market Rents and rebuild HUD annual income on 24 CFR 5.609

changelog.d/hud-fmr-fy2026.changed.md

@@ -0,0 +1,2 @@
+- Add FY2026 county-level HUD Fair Market Rents so simulations at period 2026 use FY2026 values, falling back to the nearest earlier bundled year for any county missing from the queried year.
+- Align HUD annual income with 24 CFR 5.609 by counting additional sources, excluding children's and full-time-student dependents' earned income and foster members' income, and no longer counting capital gains or retirement-account distributions.

policyengine_us/parameters/gov/hud/annual_income/sources/earned.yaml

@@ -0,0 +1,14 @@
+description: HUD counts these income sources as earned income under its assisted housing programs.
+values:
+  2024-01-01:
+    - employment_income
+    - self_employment_income
+    - sstb_self_employment_income
+    - farm_operations_income
+metadata:
+  unit: list
+  period: year
+  label: HUD earned income sources
+  reference:
+    - title: 24 CFR § 5.609(a), (b)(3), (b)(14), (b)(28)
+      href: https://www.law.cornell.edu/cfr/text/24/5.609

policyengine_us/parameters/gov/hud/annual_income/sources/unearned.yaml

@@ -0,0 +1,35 @@
+description: HUD counts these income sources as unearned income under its assisted housing programs.
+values:
+  2024-01-01:
+    - pension_income
+    # - retirement_distributions: 24 CFR 5.609(b)(26) excludes retirement-account
+    #   income except periodic distributions, which count. PolicyEngine's
+    #   retirement_distributions variable doesn't distinguish periodic from
+    #   lump-sum withdrawals, so it is left out entirely rather than overcounting
+    #   lump-sum distributions that should be excluded.
+    - dividend_income
+    - interest_income
+    - gi_cash_assistance
+    - rental_income
+    - farm_rent_income
+    - partnership_s_corp_income
+    - illicit_income
+    - miscellaneous_income
+    - alimony_income
+    - strike_benefits
+    - social_security
+    - ssi
+    - general_assistance
+    - unemployment_compensation
+    - child_support_received
+    - veterans_benefits
+    - disability_benefits
+    - survivor_benefits
+    - financial_assistance
+metadata:
+  unit: list
+  period: year
+  label: HUD unearned income sources
+  reference:
+    - title: 24 CFR § 5.609(a)(1), (a)(2)
+      href: https://www.law.cornell.edu/cfr/text/24/5.609

policyengine_us/parameters/gov/hud/fmr/README.md

@@ -5,23 +5,36 @@
 `fair_market_rents.csv` holds HUD's published Fair Market Rents at the FMR-area
 level, indexed by `(state, hud_fmr_area_code, year, bedrooms)`. FMRs are the
 40th-percentile gross-rent estimates HUD uses to cap rents under the Housing
-Choice Voucher program, set Low-Income Housing Tax Credit rent limits, and
-size other federal housing subsidies (24 CFR Part 888).
+Choice Voucher program and size other federal housing subsidies (24 CFR Part
+888).
 
 The model variable `hud_fair_market_rent` reads from this CSV and normalizes
 HUD FMR-area codes to PolicyEngine's five-digit `county_fips` input. When
 several HUD FMR areas map to one county and no direct county row exists, the
 loader uses the median FMR-area value as a lossy county-level fallback.
 
-## Scope today (Phase 1)
+## Scope today
 
-- **Year**: FY2025 only. The variable imputes unsupported years with the
-  nearest bundled FMR year until more years are added.
+- **Years**: FY2025 and FY2026. `nearest_fmr_year` resolves each queried
+  period to the matching fiscal year when its rows are present (period 2025 →
+  FY2025, period 2026 → FY2026). Periods outside the bundled range fall back to
+  the nearest bundled year (e.g. 2024 → FY2025, 2027 → FY2026).
 - **Geography**: county-level lookup from HUD FMR areas (no SAFMR ZIP-level
-  resolution yet — that lands in Phase 1B). Where HUD publishes one pseudo-area
-  for a territory, that pseudo-area is expanded to the territory's county FIPS
-  codes.
-- **Data**: full FY2025 county-level HUD file.
+  resolution here). Where HUD publishes one pseudo-area for a territory, that
+  pseudo-area is expanded to the territory's county FIPS codes.
+- **Connecticut**: HUD's FY2026 file adopts Connecticut's nine Census planning
+  regions (FIPS `09110`–`09190`) in place of the eight legacy counties (FIPS
+  `09001`–`09015`); Connecticut abolished county government in 1960 and the
+  Census Bureau approved the planning regions as county-equivalents in 2022.
+  PolicyEngine's `County` enum still uses the legacy counties. When a queried
+  county/bedroom row is absent from the preferred fiscal year, such as legacy
+  Connecticut counties in FY2026, `hud_fair_market_rent` falls back to the most
+  recent earlier bundled year with a matching row rather than returning zero.
+  **TODO**: this fallback depends on FY2025 remaining in the bundle. Migrate
+  the `County` enum to Connecticut's planning regions (tracked in #8803)
+  before FY2025 rows are ever dropped, or legacy CT counties will silently
+  resolve to $0.
+- **Data**: full FY2025 and FY2026 county-level HUD files.
 
 ## Schema
 
@@ -35,18 +48,31 @@ loader uses the median FMR-area value as a lossy county-level fallback.
 
 ## Refresh
 
+Two equivalent tools write this CSV; both **append** a new `--year` rather than
+overwriting, so multiple fiscal years coexist.
+
+From the HUD User API (needs a free `HUD_API_TOKEN`, register at
+<https://www.huduser.gov/hudapi/>):
+
 ```
 python -m policyengine_us.tools.download_hud_fmr --year 2025 --output \
     policyengine_us/parameters/gov/hud/fmr/fair_market_rents.csv
 ```
 
-The script reads `HUD_API_TOKEN` from the environment (register a free key
-at <https://www.huduser.gov/hudapi/>). Re-running with a different `--year`
-appends rather than overwriting.
+From HUD's published per-year Excel workbook (no token; needs `python-calamine`
+— browse to Datasets > Fair Market Rents and download `FYXX_FMRs.xlsx`):
+
+```
+python -m policyengine_us.tools.convert_hud_fmr_xlsx --input FY26_FMRs.xlsx \
+    --year 2026 --output \
+    policyengine_us/parameters/gov/hud/fmr/fair_market_rents.csv
+```
 
 ## Source
 
-- HUD User FY2025 FMR documentation: <https://www.huduser.gov/portal/datasets/fmr.html>
-- Federal Register notice: <https://www.federalregister.gov/documents/2024/08/14/2024-18002>
+- HUD User FMR documentation: <https://www.huduser.gov/portal/datasets/fmr.html>
+- FY2025 Federal Register notice: <https://www.federalregister.gov/documents/2024/08/14/2024-18002>
+- FY2026 Federal Register notice: <https://www.federalregister.gov/documents/2025/08/22/2025-16060>
+  (effective 2025-10-01).
 - Regulatory citation: 24 CFR §888 (FMR rules), 24 CFR §982.503 (HCV payment
   standards bound to 90-110 percent of FMR).