From 7a864a14eeeb031d13839ec3394ca97087e699b4 Mon Sep 17 00:00:00 2001
From: Max Ghenis <max@policyengine.org>
Date: Mon, 12 Oct 2026 09:25:54 -0400
Subject: [PATCH 1/5] Date the Texas SSI supplement's PNA history from primary
 sources

The personal needs allowance parameter started on 1999-09-01, so any Texas
simulation for 1999 or earlier raised ParameterNotFoundError. H-1500 and the
2002 DHS handbook say the PNA was $30 before September 1999; date that value
from July 1, 1988, when 42 USC 1396a(q)(2) set the $30 federal minimum, so the
supplement is $0 until September 1999.

The existing values match HHSC's own records for every period, including
2007-2011, where SSA's State Assistance Programs tables list a $60 state
supplement but HHSC's handbook (H-6000, revisions 09-4 and 11-2) says $30.
Add the dated sources, a test case for each period, and property tests that
the supplement does not vary with a recipient's own income.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../tx-ssi-supplement-history.fixed.md        |   1 +
 .../personal_needs_allowance.yaml             |  17 ++
 ...test_tx_ssi_state_supplement_invariants.py | 211 ++++++++++++++++++
 .../tx_ssi_state_supplement.yaml              | 196 +++++++++++++++-
 .../tx_ssi_state_supplement.py                |  15 +-
 5 files changed, 437 insertions(+), 3 deletions(-)
 create mode 100644 changelog.d/tx-ssi-supplement-history.fixed.md
 create mode 100644 policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py

diff --git a/changelog.d/tx-ssi-supplement-history.fixed.md b/changelog.d/tx-ssi-supplement-history.fixed.md
new file mode 100644
index 00000000000..4941da0831b
--- /dev/null
+++ b/changelog.d/tx-ssi-supplement-history.fixed.md
@@ -0,0 +1 @@
+Define the Texas SSI supplement's personal needs allowance before September 1999 ($30, no supplement), so Texas simulations for 1999 and earlier no longer fail, and document the supplement's sources from 1999 to 2026.
diff --git a/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml b/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml
index eea60dbf67f..e8b9c5fd3b8 100644
--- a/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml
+++ b/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml
@@ -1,6 +1,9 @@
 description: Texas provides this amount as the personal needs allowance for Supplemental Security Income recipients in Medicaid-funded long-term care facilities under the Optional State Supplement program.
 
 values:
+  # H-1500 and the 2002 DHS handbook give $30 before September 1999 without a
+  # start date. 42 USC 1396a(q)(2) set the $30 federal minimum from July 1, 1988.
+  1988-07-01: 30
   1999-09-01: 45
   2001-09-01: 60
   2003-09-01: 45
@@ -16,3 +19,17 @@ metadata:
       href: https://statutes.capitol.texas.gov/Docs/HR/htm/HR.32.htm
     - title: HHSC MEPD Handbook Section H-1500 - Personal Needs Allowance
       href: https://www.hhs.texas.gov/handbooks/medicaid-elderly-people-disabilities-handbook/h-1500-personal-needs-allowance
+    - title: 1 Texas Administrative Code Section 358.381(c)
+      href: https://www.law.cornell.edu/regulations/texas/1-Tex-Admin-Code-SS-358-381
+    - title: 42 USC 1396a(q)(2) - Minimum monthly personal needs allowance
+      href: https://www.law.cornell.edu/uscode/text/42/1396a#q_2
+    - title: Texas DHS Medicaid Eligibility Handbook Revision Notice 02-1 (December 21, 2001), Personal Needs Allowance - Effective September 1, 2001
+      href: https://web.archive.org/web/20020504200936/http://www.dhs.state.tx.us:80/handbooks/archives/meh/02-1/memo.htm
+    - title: H.B. 2292, 78th Texas Legislature (2003), Section 2.207
+      href: https://capitol.texas.gov/tlodocs/78R/billtext/html/HB02292F.htm
+    - title: Texas DHS Medicaid Eligibility Handbook Item 3231, Personal Needs Allowance (Revision 03-7, effective September 1, 2003)
+      href: https://web.archive.org/web/20030910100506/http://www.dhs.state.tx.us:80/handbooks/meh/3000/3231.htm
+    - title: HHSC MEPD Handbook Section H-6000 (Revision 09-4, effective December 1, 2009)
+      href: https://web.archive.org/web/20100126020411/http://www.dads.state.tx.us/handbooks/mepd/H/H-6000.htm
+    - title: H.B. 54, 88th Texas Legislature (2023)
+      href: https://capitol.texas.gov/tlodocs/88R/billtext/html/HB00054F.htm
diff --git a/policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py b/policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py
new file mode 100644
index 00000000000..cecb95255ac
--- /dev/null
+++ b/policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py
@@ -0,0 +1,211 @@
+"""Invariants for the Texas SSI supplement for Medicaid-facility residents.
+
+HHSC MEPD Handbook H-6000: "HHSC supplements the reduced SSI payment standard
+by $45 per month to ensure SSI recipients also have a $75 personal needs
+allowance." The supplement is the personal needs allowance (PNA) less the $30
+reduced federal benefit, and a recipient's other income goes to the facility
+co-payment rather than reducing it (H-6000, H-1200).
+
+Checked for single residents of a Medicaid facility with generated pensions,
+earnings and ages:
+
+1. Income invariance: every eligible resident whose SSI countable income is
+   at most the $30 reduced standard (an SSI recipient under H-6000) gets
+   exactly PNA - $30 a month, whatever that income is.
+2. Federal side of the identity: for those residents federal SSI plus
+   countable income equals the $30 reduced standard.
+3. Agreement with the "allowance less federal SSI less countable income"
+   reading of SSA's description: PNA - SSI - countable income equals the
+   supplement for those residents.
+4. The supplement is never negative and never above PNA - $30.
+
+And for every month from July 1988 to December 2026, the monthly amount for an
+eligible resident matches the dated HHSC history: $0 before September 1999,
+then $15, $30 (September 2001), $15 (September 2003), $30 (January 2006) and
+$45 (January 2024).
+
+Residents with countable income above $30 are not SSI recipients; whether they
+are eligible is tested with the eligibility variable, not here.
+"""
+
+import numpy as np
+import pytest
+from hypothesis import HealthCheck, given, settings
+from hypothesis import strategies as st
+
+from policyengine_us import Simulation
+from policyengine_us.system import system
+
+PERIODS = ("2011-06", "2024-06", "2026-01")
+TOLERANCE = 0.01
+FACILITY_INPUTS = dict(
+    is_in_medicaid_facility=True,
+    ssi_lives_in_medical_treatment_facility=True,
+    ssi_medicaid_pays_majority_of_care=True,
+)
+# (start month, monthly supplement): H-1500's PNA less the $30 reduced benefit.
+HISTORY = (
+    ("1988-07", 0),
+    ("1999-09", 15),
+    ("2001-09", 30),
+    ("2003-09", 15),
+    ("2006-01", 30),
+    ("2024-01", 45),
+)
+
+
+def _situation(residents, years):
+    situation = {
+        group: {}
+        for group in (
+            "people",
+            "tax_units",
+            "marital_units",
+            "spm_units",
+            "families",
+            "households",
+        )
+    }
+    for index, (age, pension, earnings) in enumerate(residents):
+        name = f"resident{index}"
+        person = {
+            "age": {year: age for year in years},
+            "pension_income": {year: 12 * pension for year in years},
+            "employment_income": {year: 12 * earnings for year in years},
+        }
+        for variable, value in FACILITY_INPUTS.items():
+            person[variable] = {year: value for year in years}
+        situation["people"][name] = person
+        for group in ("tax_units", "marital_units", "spm_units", "families"):
+            situation[group][f"{group}_{index}"] = {"members": [name]}
+        situation["households"][f"household_{index}"] = {
+            "members": [name],
+            "state_code": {year: "TX" for year in years},
+        }
+    return situation
+
+
+def _check(residents):
+    years = sorted({int(period[:4]) for period in PERIODS})
+    simulation = Simulation(situation=_situation(residents, years))
+    for period in PERIODS:
+        parameters = simulation.tax_benefit_system.parameters(period)
+        pna = (
+            parameters.gov.states.tx.hhsc.ssi_state_supplement.personal_needs_allowance
+        )
+        reduced = parameters.gov.ssa.ssi.amount.institutional.individual
+        eligible = simulation.calculate("tx_ssi_state_supplement_eligible", period)
+        supplement = simulation.calculate("tx_ssi_state_supplement", period)
+        ssi = simulation.calculate("ssi", period)
+        countable = simulation.calculate("ssi_countable_income", period)
+        recipient = eligible & (countable <= reduced + TOLERANCE)
+
+        # 4. Bounds.
+        assert (supplement >= 0).all()
+        assert (supplement <= pna - reduced + TOLERANCE).all()
+        # 1. Income invariance.
+        np.testing.assert_allclose(supplement[recipient], pna - reduced, atol=TOLERANCE)
+        # 2. Federal SSI plus countable income is the reduced standard.
+        np.testing.assert_allclose(
+            (ssi + countable)[recipient], reduced, atol=TOLERANCE
+        )
+        # 3. Agreement with "allowance less federal SSI less countable income".
+        np.testing.assert_allclose(
+            supplement[recipient],
+            (pna - ssi - countable)[recipient],
+            atol=TOLERANCE,
+        )
+    return recipient, countable
+
+
+residents = st.tuples(
+    st.integers(min_value=65, max_value=95),
+    # Monthly pension: $0-$150, so countable unearned income spans the $30
+    # reduced standard.
+    st.integers(min_value=0, max_value=150),
+    # Monthly earnings: $0-$250.
+    st.integers(min_value=0, max_value=250),
+)
+
+# A batch's cost is mostly per-variable overhead, so each example is a large
+# batch and there are few examples.
+SETTINGS = dict(
+    max_examples=5,
+    deadline=None,
+    derandomize=True,
+    suppress_health_check=[HealthCheck.too_slow, HealthCheck.data_too_large],
+)
+
+
+@settings(**SETTINGS)
+@given(st.lists(residents, min_size=10, max_size=30))
+def test_generated_residents(population):
+    _check(population)
+
+
+def test_seeded_residents():
+    # Pensions at and around the $50 that puts countable income at the $30
+    # standard, earnings with and without a pension, and no income.
+    population = [
+        (age, pension, earnings)
+        for age in (66, 85)
+        for pension in (0, 20, 40, 49, 50, 51, 120)
+        for earnings in (0, 100, 145, 200)
+    ]
+    recipient, countable = _check(population)
+    # The grid reaches residents on both sides of the $30 standard.
+    assert recipient.any()
+    assert (countable > 30).any()
+
+
+def _expected(month):
+    return [amount for start, amount in HISTORY if start <= month][-1]
+
+
+def test_dated_history_every_month():
+    # Leaf parameter lookups are cheap, so check every month at that level.
+    parameters = system.parameters
+    pna = parameters.gov.states.tx.hhsc.ssi_state_supplement.personal_needs_allowance
+    reduced = parameters.gov.ssa.ssi.amount.institutional.individual
+    for year in range(1988, 2027):
+        for month in range(1, 13):
+            period = f"{year}-{month:02d}"
+            if period < HISTORY[0][0]:
+                continue
+            instant = f"{period}-01"
+            assert max(pna(instant) - reduced(instant), 0) == _expected(period), period
+
+
+def test_dated_history():
+    years = (1998, 1999, 2000, 2001, 2003, 2005, 2006, 2023, 2024)
+    simulation = Simulation(
+        situation={
+            "people": {
+                "resident": {
+                    "tx_ssi_state_supplement_eligible": {year: True for year in years}
+                }
+            },
+            "households": {
+                "household": {
+                    "members": ["resident"],
+                    "state_code": {year: "TX" for year in years},
+                }
+            },
+        }
+    )
+
+    def supplement(period):
+        return simulation.calculate("tx_ssi_state_supplement", period)[0]
+
+    # The month before and the month of each change, and the first month the
+    # federal $30 reduced benefit applies.
+    for start, _ in HISTORY:
+        year, month = map(int, start.split("-"))
+        before = f"{year - 1}-12" if month == 1 else f"{year}-{month - 1:02d}"
+        months = (start,) if start == HISTORY[0][0] else (before, start)
+        for period in months:
+            assert supplement(period) == pytest.approx(_expected(period)), period
+    # Annual totals sum the months in the years with a September change.
+    for year in (1999, 2001, 2003):
+        expected = sum(_expected(f"{year}-{month:02d}") for month in range(1, 13))
+        assert supplement(str(year)) == pytest.approx(expected), year
diff --git a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
index 12f2413e89b..b57934704d5 100644
--- a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
+++ b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
@@ -1,6 +1,14 @@
 # Unit tests for Texas SSI State Supplement benefit amount
-# Supplement = max(0, (PNA - Federal institutional SSI rate) * 12)
-# For 2024: ($75 - $30) * 12 = $45/month * 12 = $540/year
+# Monthly supplement = max(0, PNA - federal reduced SSI benefit of $30).
+# Annual periods sum the months, so years with a September 1 change mix
+# two amounts.
+# PNA history (HHSC MEPD Handbook H-1500):
+#   $30 before Sept. 1, 1999 (no supplement)
+#   $45 Sept. 1, 1999 - Aug. 31, 2001 ($15 supplement)
+#   $60 Sept. 1, 2001 - Aug. 31, 2003 ($30 supplement)
+#   $45 Sept. 1, 2003 - Dec. 31, 2005 ($15 supplement)
+#   $60 Jan. 1, 2006 - Dec. 31, 2023 ($30 supplement)
+#   $75 from Jan. 1, 2024 ($45 supplement)
 # Reference: Texas Human Resources Code Section 32.024(w)
 
 - name: Case 1, eligible individual receives full supplement.
@@ -27,3 +35,187 @@
     # PNA = $60/month (2006-2023), Federal reduced SSI = $30/month
     # Supplement = ($60 - $30) * 12 = $360/year
     tx_ssi_state_supplement: 360
+
+- name: Case 4, 1998, before the supplement began.
+  period: 1998
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # H-1500: before Sept. 1, 1999 the PNA was $30, equal to the reduced
+    # federal benefit, so there was no supplement.
+    tx_ssi_state_supplement: 0
+
+- name: Case 5, 1999, supplement starts September 1.
+  period: 1999
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # Jan.-Aug.: $30 - $30 = $0; Sept.-Dec.: $45 - $30 = $15
+    # 4 * $15 = $60/year
+    tx_ssi_state_supplement: 60
+
+- name: Case 6, 2000, $45 PNA all year.
+  period: 2000
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # SSA, State Assistance Programs for SSI Recipients, January 2002 (Texas):
+    # combined federal and state $45, state-supplemented portion $15.
+    # $15 * 12 = $180/year
+    tx_ssi_state_supplement: 180
+
+- name: Case 7, 2001, supplement rises to $30 on September 1.
+  period: 2001
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # DHS Revision Notice 02-1: PNA $60 effective Sept. 1, 2001; "the state
+    # will supplement their incomes by $30 per month".
+    # 8 * $15 + 4 * $30 = $240/year
+    tx_ssi_state_supplement: 240
+
+- name: Case 8, 2002, $60 PNA all year.
+  period: 2002
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # DHS Medicaid Eligibility Handbook Item 3231 (40 TAC 15.450(h)):
+    # "the state supplements their incomes by $30 per month".
+    # $30 * 12 = $360/year
+    tx_ssi_state_supplement: 360
+
+- name: Case 9, 2003, supplement falls to $15 on September 1.
+  period: 2003
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # H.B. 2292 (2003) Section 2.207 and Item 3231 (Revision 03-7): PNA $45
+    # from Sept. 1, 2003.
+    # 8 * $30 + 4 * $15 = $300/year
+    tx_ssi_state_supplement: 300
+
+- name: Case 10, 2005, $45 PNA all year.
+  period: 2005
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # SSA January 2005 (Texas): combined $45, state $15.
+    # $15 * 12 = $180/year
+    tx_ssi_state_supplement: 180
+
+- name: Case 11, 2006, PNA restored to $60 on January 1.
+  period: 2006
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # SSA January 2006 (Texas): combined $60, state $30.
+    # $30 * 12 = $360/year
+    tx_ssi_state_supplement: 360
+
+- name: Case 12, 2011, $30 supplement despite SSA's $60 listing.
+  period: 2011
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # SSA's January 2007-2011 Texas tables list a $60 state supplement
+    # ($90 combined). HHSC's own handbook for the same years (MEPD H-6000,
+    # Revision 09-4 of Dec. 2009 and Revision 11-2 of June 2011) says "HHSC
+    # supplements the reduced SSI payment standard by $30 per month so that
+    # SSI persons also have a $60 personal needs allowance."
+    # $30 * 12 = $360/year
+    tx_ssi_state_supplement: 360
+
+- name: Case 13, 2026, $75 PNA.
+  period: 2026
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # H-6000 (Revision 26-1): "HHSC supplements the reduced SSI payment
+    # standard by $45 per month".
+    # $45 * 12 = $540/year
+    tx_ssi_state_supplement: 540
+
+- name: Case 14, facility resident with a pension gets the full supplement.
+  # A $40/month pension less the $20 general exclusion is $20 of countable
+  # income, so SSI pays $30 - $20 = $10/month. The supplement is still $45:
+  # it is added to the reduced standard, and the pension is counted in the
+  # facility co-payment instead (H-6000).
+  period: 2024
+  input:
+    people:
+      person1:
+        age: 80
+        pension_income: 480
+        is_in_medicaid_facility: true
+        ssi_lives_in_medical_treatment_facility: true
+        ssi_medicaid_pays_majority_of_care: true
+    tax_units:
+      tax_unit:
+        members: [person1]
+    spm_units:
+      spm_unit:
+        members: [person1]
+    households:
+      household:
+        members: [person1]
+        state_code: TX
+  output:
+    ssi_countable_income: 240
+    ssi: 120
+    tx_ssi_state_supplement_eligible: true
+    # ($75 - $30) * 12 = $540/year
+    tx_ssi_state_supplement: 540
+
+- name: Case 15, facility resident with earnings gets the full supplement.
+  # $100/month of earnings less the $20 general and $65 earned income
+  # exclusions, halved, is $7.50 of countable income, so SSI pays
+  # $30 - $7.50 = $22.50/month.
+  period: 2024
+  input:
+    people:
+      person1:
+        age: 70
+        employment_income: 1_200
+        is_in_medicaid_facility: true
+        ssi_lives_in_medical_treatment_facility: true
+        ssi_medicaid_pays_majority_of_care: true
+    tax_units:
+      tax_unit:
+        members: [person1]
+    spm_units:
+      spm_unit:
+        members: [person1]
+    households:
+      household:
+        members: [person1]
+        state_code: TX
+  output:
+    ssi_countable_income: 90
+    ssi: 270
+    tx_ssi_state_supplement_eligible: true
+    tx_ssi_state_supplement: 540
+
+- name: Case 16, 2011 facility resident with no other income.
+  # Federal SSI is the $30 reduced benefit; HHSC adds $30 for a $60 PNA.
+  period: 2011
+  input:
+    people:
+      person1:
+        age: 80
+        is_in_medicaid_facility: true
+        ssi_lives_in_medical_treatment_facility: true
+        ssi_medicaid_pays_majority_of_care: true
+    tax_units:
+      tax_unit:
+        members: [person1]
+    spm_units:
+      spm_unit:
+        members: [person1]
+    households:
+      household:
+        members: [person1]
+        state_code: TX
+  output:
+    ssi: 360
+    tx_ssi_state_supplement_eligible: true
+    tx_ssi_state_supplement: 360
diff --git a/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py b/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py
index e1d858ee45e..4a97bbc4af5 100644
--- a/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py
+++ b/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py
@@ -10,11 +10,24 @@ class tx_ssi_state_supplement(Variable):
     defined_for = "tx_ssi_state_supplement_eligible"
     reference = (
         "https://statutes.capitol.texas.gov/Docs/HR/htm/HR.32.htm",
+        "https://www.hhs.texas.gov/handbooks/medicaid-elderly-people-disabilities-handbook/h-1500-personal-needs-allowance",
         "https://www.hhs.texas.gov/handbooks/medicaid-elderly-people-disabilities-handbook/h-6000-co-payment-ssi-cases",
+        "https://www.law.cornell.edu/regulations/texas/1-Tex-Admin-Code-SS-358-381",
     )
 
     def formula(person, period, parameters):
-        # Per 42 USC 1382(e)(1)(B) and Texas HR Code 32.024(w)
+        # 1 TAC 358.381(c)(2): "For a person receiving the reduced SSI federal
+        # benefit rate, HHSC issues a supplement to give the person a PNA at
+        # the minimum level set by the HHSC executive commissioner." MEPD
+        # Handbook H-6000: "HHSC supplements the reduced SSI payment standard
+        # by $45 per month to ensure SSI recipients also have a $75 personal
+        # needs allowance", i.e. the allowance (Texas HR Code 32.024(w)) less
+        # the $30 reduced federal benefit (42 USC 1382(e)(1)(B)).
+        # The supplement sits on top of the reduced standard: a recipient's
+        # other income does not reduce it but is counted in the facility
+        # co-payment (H-6000, H-1200). For an individual on the reduced
+        # standard, federal SSI plus countable income equals the $30
+        # standard, so the allowance less both is the same amount.
         p = parameters(period).gov.states.tx.hhsc.ssi_state_supplement
         pna = p.personal_needs_allowance
         federal_reduced = parameters(period).gov.ssa.ssi.amount.institutional.individual

From 8e8cf53f98d92da5368e16ecf97f5c9046d9527b Mon Sep 17 00:00:00 2001
From: Max Ghenis <max@policyengine.org>
Date: Mon, 12 Oct 2026 11:15:47 -0400
Subject: [PATCH 2/5] Address review: bound the claims, move dated checks to
 YAML

- Python invariants now cover only residents paid SSI (positive federal
  payment); the zero-payment boundary at $30 countable income is left to the
  eligibility tests, since the sources do not settle it.
- The variable comment and Case 14 no longer say other income goes to the
  co-payment "instead"; they state H-6000's fixed amount and that no Texas
  source subtracts the recipient's income.
- The dated-history checks move from Python to YAML monthly cases at each
  change (Cases 17-27); the Python file keeps only the generated-resident
  properties YAML cannot express, and says why.
- The parameter comment and changelog call July 1988 the modeled backfill
  start and state the repaired range.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../tx-ssi-supplement-history.fixed.md        |   2 +-
 .../personal_needs_allowance.yaml             |   4 +-
 ...test_tx_ssi_state_supplement_invariants.py | 141 +++++-------------
 .../tx_ssi_state_supplement.yaml              |  92 +++++++++++-
 .../tx_ssi_state_supplement.py                |  11 +-
 5 files changed, 140 insertions(+), 110 deletions(-)

diff --git a/changelog.d/tx-ssi-supplement-history.fixed.md b/changelog.d/tx-ssi-supplement-history.fixed.md
index 4941da0831b..00c3204dc5b 100644
--- a/changelog.d/tx-ssi-supplement-history.fixed.md
+++ b/changelog.d/tx-ssi-supplement-history.fixed.md
@@ -1 +1 @@
-Define the Texas SSI supplement's personal needs allowance before September 1999 ($30, no supplement), so Texas simulations for 1999 and earlier no longer fail, and document the supplement's sources from 1999 to 2026.
+Backfill the Texas SSI supplement's personal needs allowance at $30 from July 1988 (no supplement before September 1999), so Texas simulations for months from July 1988 through August 1999 no longer fail, and document the supplement's sources from 1999 to 2026.
diff --git a/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml b/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml
index e8b9c5fd3b8..568a2a49625 100644
--- a/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml
+++ b/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml
@@ -2,7 +2,9 @@ description: Texas provides this amount as the personal needs allowance for Supp
 
 values:
   # H-1500 and the 2002 DHS handbook give $30 before September 1999 without a
-  # start date. 42 USC 1396a(q)(2) set the $30 federal minimum from July 1, 1988.
+  # start date. The modeled backfill starts July 1, 1988, when the $30 federal
+  # minimum in 42 USC 1396a(q)(2) took effect; Texas's own adoption date is
+  # not in these sources.
   1988-07-01: 30
   1999-09-01: 45
   2001-09-01: 60
diff --git a/policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py b/policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py
index cecb95255ac..440228f83a6 100644
--- a/policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py
+++ b/policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py
@@ -1,57 +1,46 @@
-"""Invariants for the Texas SSI supplement for Medicaid-facility residents.
-
-HHSC MEPD Handbook H-6000: "HHSC supplements the reduced SSI payment standard
-by $45 per month to ensure SSI recipients also have a $75 personal needs
-allowance." The supplement is the personal needs allowance (PNA) less the $30
-reduced federal benefit, and a recipient's other income goes to the facility
-co-payment rather than reducing it (H-6000, H-1200).
-
-Checked for single residents of a Medicaid facility with generated pensions,
-earnings and ages:
-
-1. Income invariance: every eligible resident whose SSI countable income is
-   at most the $30 reduced standard (an SSI recipient under H-6000) gets
-   exactly PNA - $30 a month, whatever that income is.
-2. Federal side of the identity: for those residents federal SSI plus
-   countable income equals the $30 reduced standard.
-3. Agreement with the "allowance less federal SSI less countable income"
-   reading of SSA's description: PNA - SSI - countable income equals the
-   supplement for those residents.
-4. The supplement is never negative and never above PNA - $30.
-
-And for every month from July 1988 to December 2026, the monthly amount for an
-eligible resident matches the dated HHSC history: $0 before September 1999,
-then $15, $30 (September 2001), $15 (September 2003), $30 (January 2006) and
-$45 (January 2024).
-
-Residents with countable income above $30 are not SSI recipients; whether they
-are eligible is tested with the eligibility variable, not here.
+"""Income invariance of the Texas SSI supplement for Medicaid-facility residents.
+
+1 TAC 358.381(c)(2): "For a person receiving the reduced SSI federal benefit
+rate, HHSC issues a supplement to give the person a PNA at the minimum level
+set by the HHSC executive commissioner." HHSC MEPD Handbook H-6000 states it as
+a fixed amount: "HHSC supplements the reduced SSI payment standard by $45 per
+month". No Texas source subtracts the recipient's own income from it.
+
+Checked for single residents of a Medicaid facility who are paid SSI on the
+reduced standard (a positive federal payment), with generated pensions,
+earnings and ages, in June 2011 and June 2024:
+
+1. Income invariance: each such eligible resident gets exactly PNA - $30 a
+   month, whatever their income.
+2. Federal identity: federal SSI plus countable income equals the $30 reduced
+   standard.
+3. Differential: PNA - SSI - countable income, the reading of SSA's
+   description that subtracts the recipient's income, equals the supplement.
+4. Bounds: 0 <= supplement <= PNA - $30 for every resident.
+
+Residents with no federal payment (countable income at or above $30) are left
+to the eligibility tests: the sources do not settle whether Texas pays one
+whose countable income is exactly $30.
+
+Why Python: YAML checks fixed expected outputs for listed households. These
+properties compare three computed variables against each other for generated
+residents, which YAML cannot express. The dated amounts are in
+tx_ssi_state_supplement.yaml.
 """
 
 import numpy as np
-import pytest
 from hypothesis import HealthCheck, given, settings
 from hypothesis import strategies as st
 
 from policyengine_us import Simulation
-from policyengine_us.system import system
 
-PERIODS = ("2011-06", "2024-06", "2026-01")
+PERIODS = ("2011-06", "2024-06")
 TOLERANCE = 0.01
 FACILITY_INPUTS = dict(
     is_in_medicaid_facility=True,
     ssi_lives_in_medical_treatment_facility=True,
     ssi_medicaid_pays_majority_of_care=True,
 )
-# (start month, monthly supplement): H-1500's PNA less the $30 reduced benefit.
-HISTORY = (
-    ("1988-07", 0),
-    ("1999-09", 15),
-    ("2001-09", 30),
-    ("2003-09", 15),
-    ("2006-01", 30),
-    ("2024-01", 45),
-)
 
 
 def _situation(residents, years):
@@ -88,6 +77,7 @@ def _situation(residents, years):
 def _check(residents):
     years = sorted({int(period[:4]) for period in PERIODS})
     simulation = Simulation(situation=_situation(residents, years))
+    paid = []
     for period in PERIODS:
         parameters = simulation.tax_benefit_system.parameters(period)
         pna = (
@@ -98,7 +88,8 @@ def _check(residents):
         supplement = simulation.calculate("tx_ssi_state_supplement", period)
         ssi = simulation.calculate("ssi", period)
         countable = simulation.calculate("ssi_countable_income", period)
-        recipient = eligible & (countable <= reduced + TOLERANCE)
+        recipient = eligible & (ssi > 0)
+        paid.append(recipient)
 
         # 4. Bounds.
         assert (supplement >= 0).all()
@@ -115,7 +106,7 @@ def _check(residents):
             (pna - ssi - countable)[recipient],
             atol=TOLERANCE,
         )
-    return recipient, countable
+    return np.any(paid, axis=0)
 
 
 residents = st.tuples(
@@ -144,68 +135,16 @@ def test_generated_residents(population):
 
 
 def test_seeded_residents():
-    # Pensions at and around the $50 that puts countable income at the $30
-    # standard, earnings with and without a pension, and no income.
+    # Pensions below, at and above the $50 that puts countable income at the
+    # $30 standard, earnings with and without a pension, and no income.
     population = [
         (age, pension, earnings)
         for age in (66, 85)
         for pension in (0, 20, 40, 49, 50, 51, 120)
         for earnings in (0, 100, 145, 200)
     ]
-    recipient, countable = _check(population)
-    # The grid reaches residents on both sides of the $30 standard.
-    assert recipient.any()
-    assert (countable > 30).any()
-
-
-def _expected(month):
-    return [amount for start, amount in HISTORY if start <= month][-1]
-
-
-def test_dated_history_every_month():
-    # Leaf parameter lookups are cheap, so check every month at that level.
-    parameters = system.parameters
-    pna = parameters.gov.states.tx.hhsc.ssi_state_supplement.personal_needs_allowance
-    reduced = parameters.gov.ssa.ssi.amount.institutional.individual
-    for year in range(1988, 2027):
-        for month in range(1, 13):
-            period = f"{year}-{month:02d}"
-            if period < HISTORY[0][0]:
-                continue
-            instant = f"{period}-01"
-            assert max(pna(instant) - reduced(instant), 0) == _expected(period), period
-
-
-def test_dated_history():
-    years = (1998, 1999, 2000, 2001, 2003, 2005, 2006, 2023, 2024)
-    simulation = Simulation(
-        situation={
-            "people": {
-                "resident": {
-                    "tx_ssi_state_supplement_eligible": {year: True for year in years}
-                }
-            },
-            "households": {
-                "household": {
-                    "members": ["resident"],
-                    "state_code": {year: "TX" for year in years},
-                }
-            },
-        }
-    )
-
-    def supplement(period):
-        return simulation.calculate("tx_ssi_state_supplement", period)[0]
-
-    # The month before and the month of each change, and the first month the
-    # federal $30 reduced benefit applies.
-    for start, _ in HISTORY:
-        year, month = map(int, start.split("-"))
-        before = f"{year - 1}-12" if month == 1 else f"{year}-{month - 1:02d}"
-        months = (start,) if start == HISTORY[0][0] else (before, start)
-        for period in months:
-            assert supplement(period) == pytest.approx(_expected(period)), period
-    # Annual totals sum the months in the years with a September change.
-    for year in (1999, 2001, 2003):
-        expected = sum(_expected(f"{year}-{month:02d}") for month in range(1, 13))
-        assert supplement(str(year)) == pytest.approx(expected), year
+    paid = _check(population)
+    # The grid reaches residents paid SSI with and without other income, and
+    # residents with no federal payment.
+    assert paid.sum() >= 10
+    assert (~paid).any()
diff --git a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
index b57934704d5..cd093cbbe83 100644
--- a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
+++ b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
@@ -138,8 +138,8 @@
 - name: Case 14, facility resident with a pension gets the full supplement.
   # A $40/month pension less the $20 general exclusion is $20 of countable
   # income, so SSI pays $30 - $20 = $10/month. The supplement is still $45:
-  # it is added to the reduced standard, and the pension is counted in the
-  # facility co-payment instead (H-6000).
+  # H-6000 states it as a fixed amount on the reduced standard, and no Texas
+  # source reduces it by the recipient's income.
   period: 2024
   input:
     people:
@@ -219,3 +219,91 @@
     ssi: 360
     tx_ssi_state_supplement_eligible: true
     tx_ssi_state_supplement: 360
+
+- name: Case 17, 1988-07.
+  period: 1988-07
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # First modeled month: PNA $30 equals the reduced federal benefit.
+    tx_ssi_state_supplement: 0
+
+- name: Case 18, 1999-08.
+  period: 1999-08
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # Last month before the supplement began.
+    tx_ssi_state_supplement: 0
+
+- name: Case 19, 1999-09.
+  period: 1999-09
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # 25 TexReg 558: $15 supplement retroactive to Sept. 1, 1999.
+    tx_ssi_state_supplement: 15
+
+- name: Case 20, 2001-08.
+  period: 2001-08
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # Last month of the $45 PNA.
+    tx_ssi_state_supplement: 15
+
+- name: Case 21, 2001-09.
+  period: 2001-09
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # DHS Revision Notice 02-1: $30 effective Sept. 1, 2001.
+    tx_ssi_state_supplement: 30
+
+- name: Case 22, 2003-08.
+  period: 2003-08
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # Last month of the $60 PNA.
+    tx_ssi_state_supplement: 30
+
+- name: Case 23, 2003-09.
+  period: 2003-09
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # H.B. 2292 Section 2.207: $45 PNA from Sept. 1, 2003.
+    tx_ssi_state_supplement: 15
+
+- name: Case 24, 2005-12.
+  period: 2005-12
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # Last month of the $45 PNA.
+    tx_ssi_state_supplement: 15
+
+- name: Case 25, 2006-01.
+  period: 2006-01
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # PNA restored to $60 on Jan. 1, 2006.
+    tx_ssi_state_supplement: 30
+
+- name: Case 26, 2023-12.
+  period: 2023-12
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # Last month of the $60 PNA.
+    tx_ssi_state_supplement: 30
+
+- name: Case 27, 2024-01.
+  period: 2024-01
+  input:
+    tx_ssi_state_supplement_eligible: true
+  output:
+    # IL 2023-45: $45 from January 2024.
+    tx_ssi_state_supplement: 45
diff --git a/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py b/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py
index 4a97bbc4af5..ef6f2e4c6fa 100644
--- a/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py
+++ b/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py
@@ -23,11 +23,12 @@ def formula(person, period, parameters):
         # by $45 per month to ensure SSI recipients also have a $75 personal
         # needs allowance", i.e. the allowance (Texas HR Code 32.024(w)) less
         # the $30 reduced federal benefit (42 USC 1382(e)(1)(B)).
-        # The supplement sits on top of the reduced standard: a recipient's
-        # other income does not reduce it but is counted in the facility
-        # co-payment (H-6000, H-1200). For an individual on the reduced
-        # standard, federal SSI plus countable income equals the $30
-        # standard, so the allowance less both is the same amount.
+        # H-6000 states the supplement as a fixed amount on the reduced
+        # standard and, separately, has workers check SSI recipients for other
+        # income and calculate a co-payment; no Texas source subtracts the
+        # recipient's income from the supplement. For an individual paid SSI
+        # on the reduced standard, federal SSI plus countable income equals
+        # the $30 standard, so the allowance less both is the same amount.
         p = parameters(period).gov.states.tx.hhsc.ssi_state_supplement
         pna = p.personal_needs_allowance
         federal_reduced = parameters(period).gov.ssa.ssi.amount.institutional.individual

From 0be5cb674d3979b0021e9cea3df4a4f353b4250d Mon Sep 17 00:00:00 2001
From: Max Ghenis <max@policyengine.org>
Date: Mon, 19 Oct 2026 13:51:21 -0400
Subject: [PATCH 3/5] Address DTrim99's review: bound the changelog, drop the
 Python test

- The changelog now says tx_ssi_state_supplement returns $0 instead of
  raising for July 1988 through August 1999; household totals before 2015
  still fail on other parameters (FIRST_MODELED_YEAR).
- Remove test_tx_ssi_state_supplement_invariants.py: its properties hold by
  construction (the formula reads no income variable) and YAML Cases 14-16
  pin them with SSI computed from real inputs. Add Case 28, a resident with
  both a pension and earnings, which the seeded grid covered.
- Cite the Pub. L. 100-203 section 9119(d)(2) note for the July 1, 1988 date.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../tx-ssi-supplement-history.fixed.md        |   2 +-
 .../personal_needs_allowance.yaml             |   4 +-
 ...test_tx_ssi_state_supplement_invariants.py | 150 ------------------
 .../tx_ssi_state_supplement.yaml              |  31 ++++
 4 files changed, 35 insertions(+), 152 deletions(-)
 delete mode 100644 policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py

diff --git a/changelog.d/tx-ssi-supplement-history.fixed.md b/changelog.d/tx-ssi-supplement-history.fixed.md
index 00c3204dc5b..4d6a460dcfd 100644
--- a/changelog.d/tx-ssi-supplement-history.fixed.md
+++ b/changelog.d/tx-ssi-supplement-history.fixed.md
@@ -1 +1 @@
-Backfill the Texas SSI supplement's personal needs allowance at $30 from July 1988 (no supplement before September 1999), so Texas simulations for months from July 1988 through August 1999 no longer fail, and document the supplement's sources from 1999 to 2026.
+Backfill the Texas SSI supplement's personal needs allowance at $30 from July 1988 (no supplement before September 1999), so `tx_ssi_state_supplement` returns $0 instead of raising `ParameterNotFoundError` for July 1988 through August 1999, and document the supplement's sources from 1999 to 2026.
diff --git a/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml b/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml
index 568a2a49625..0fa05f76148 100644
--- a/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml
+++ b/policyengine_us/parameters/gov/states/tx/hhsc/ssi_state_supplement/personal_needs_allowance.yaml
@@ -3,7 +3,9 @@ description: Texas provides this amount as the personal needs allowance for Supp
 values:
   # H-1500 and the 2002 DHS handbook give $30 before September 1999 without a
   # start date. The modeled backfill starts July 1, 1988, when the $30 federal
-  # minimum in 42 USC 1396a(q)(2) took effect; Texas's own adoption date is
+  # minimum in 42 USC 1396a(q)(2) took effect: Pub. L. 100-203 section
+  # 9119(d)(2), in the statutory note to 42 USC 1396a, applies it to "calendar
+  # quarters beginning on or after July 1, 1988". Texas's own adoption date is
   # not in these sources.
   1988-07-01: 30
   1999-09-01: 45
diff --git a/policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py b/policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py
deleted file mode 100644
index 440228f83a6..00000000000
--- a/policyengine_us/tests/core/test_tx_ssi_state_supplement_invariants.py
+++ /dev/null
@@ -1,150 +0,0 @@
-"""Income invariance of the Texas SSI supplement for Medicaid-facility residents.
-
-1 TAC 358.381(c)(2): "For a person receiving the reduced SSI federal benefit
-rate, HHSC issues a supplement to give the person a PNA at the minimum level
-set by the HHSC executive commissioner." HHSC MEPD Handbook H-6000 states it as
-a fixed amount: "HHSC supplements the reduced SSI payment standard by $45 per
-month". No Texas source subtracts the recipient's own income from it.
-
-Checked for single residents of a Medicaid facility who are paid SSI on the
-reduced standard (a positive federal payment), with generated pensions,
-earnings and ages, in June 2011 and June 2024:
-
-1. Income invariance: each such eligible resident gets exactly PNA - $30 a
-   month, whatever their income.
-2. Federal identity: federal SSI plus countable income equals the $30 reduced
-   standard.
-3. Differential: PNA - SSI - countable income, the reading of SSA's
-   description that subtracts the recipient's income, equals the supplement.
-4. Bounds: 0 <= supplement <= PNA - $30 for every resident.
-
-Residents with no federal payment (countable income at or above $30) are left
-to the eligibility tests: the sources do not settle whether Texas pays one
-whose countable income is exactly $30.
-
-Why Python: YAML checks fixed expected outputs for listed households. These
-properties compare three computed variables against each other for generated
-residents, which YAML cannot express. The dated amounts are in
-tx_ssi_state_supplement.yaml.
-"""
-
-import numpy as np
-from hypothesis import HealthCheck, given, settings
-from hypothesis import strategies as st
-
-from policyengine_us import Simulation
-
-PERIODS = ("2011-06", "2024-06")
-TOLERANCE = 0.01
-FACILITY_INPUTS = dict(
-    is_in_medicaid_facility=True,
-    ssi_lives_in_medical_treatment_facility=True,
-    ssi_medicaid_pays_majority_of_care=True,
-)
-
-
-def _situation(residents, years):
-    situation = {
-        group: {}
-        for group in (
-            "people",
-            "tax_units",
-            "marital_units",
-            "spm_units",
-            "families",
-            "households",
-        )
-    }
-    for index, (age, pension, earnings) in enumerate(residents):
-        name = f"resident{index}"
-        person = {
-            "age": {year: age for year in years},
-            "pension_income": {year: 12 * pension for year in years},
-            "employment_income": {year: 12 * earnings for year in years},
-        }
-        for variable, value in FACILITY_INPUTS.items():
-            person[variable] = {year: value for year in years}
-        situation["people"][name] = person
-        for group in ("tax_units", "marital_units", "spm_units", "families"):
-            situation[group][f"{group}_{index}"] = {"members": [name]}
-        situation["households"][f"household_{index}"] = {
-            "members": [name],
-            "state_code": {year: "TX" for year in years},
-        }
-    return situation
-
-
-def _check(residents):
-    years = sorted({int(period[:4]) for period in PERIODS})
-    simulation = Simulation(situation=_situation(residents, years))
-    paid = []
-    for period in PERIODS:
-        parameters = simulation.tax_benefit_system.parameters(period)
-        pna = (
-            parameters.gov.states.tx.hhsc.ssi_state_supplement.personal_needs_allowance
-        )
-        reduced = parameters.gov.ssa.ssi.amount.institutional.individual
-        eligible = simulation.calculate("tx_ssi_state_supplement_eligible", period)
-        supplement = simulation.calculate("tx_ssi_state_supplement", period)
-        ssi = simulation.calculate("ssi", period)
-        countable = simulation.calculate("ssi_countable_income", period)
-        recipient = eligible & (ssi > 0)
-        paid.append(recipient)
-
-        # 4. Bounds.
-        assert (supplement >= 0).all()
-        assert (supplement <= pna - reduced + TOLERANCE).all()
-        # 1. Income invariance.
-        np.testing.assert_allclose(supplement[recipient], pna - reduced, atol=TOLERANCE)
-        # 2. Federal SSI plus countable income is the reduced standard.
-        np.testing.assert_allclose(
-            (ssi + countable)[recipient], reduced, atol=TOLERANCE
-        )
-        # 3. Agreement with "allowance less federal SSI less countable income".
-        np.testing.assert_allclose(
-            supplement[recipient],
-            (pna - ssi - countable)[recipient],
-            atol=TOLERANCE,
-        )
-    return np.any(paid, axis=0)
-
-
-residents = st.tuples(
-    st.integers(min_value=65, max_value=95),
-    # Monthly pension: $0-$150, so countable unearned income spans the $30
-    # reduced standard.
-    st.integers(min_value=0, max_value=150),
-    # Monthly earnings: $0-$250.
-    st.integers(min_value=0, max_value=250),
-)
-
-# A batch's cost is mostly per-variable overhead, so each example is a large
-# batch and there are few examples.
-SETTINGS = dict(
-    max_examples=5,
-    deadline=None,
-    derandomize=True,
-    suppress_health_check=[HealthCheck.too_slow, HealthCheck.data_too_large],
-)
-
-
-@settings(**SETTINGS)
-@given(st.lists(residents, min_size=10, max_size=30))
-def test_generated_residents(population):
-    _check(population)
-
-
-def test_seeded_residents():
-    # Pensions below, at and above the $50 that puts countable income at the
-    # $30 standard, earnings with and without a pension, and no income.
-    population = [
-        (age, pension, earnings)
-        for age in (66, 85)
-        for pension in (0, 20, 40, 49, 50, 51, 120)
-        for earnings in (0, 100, 145, 200)
-    ]
-    paid = _check(population)
-    # The grid reaches residents paid SSI with and without other income, and
-    # residents with no federal payment.
-    assert paid.sum() >= 10
-    assert (~paid).any()
diff --git a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
index cd093cbbe83..4d48d38aed6 100644
--- a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
+++ b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
@@ -307,3 +307,34 @@
   output:
     # IL 2023-45: $45 from January 2024.
     tx_ssi_state_supplement: 45
+
+- name: Case 28, facility resident with a pension and earnings gets the full supplement.
+  # $30/month pension less the $20 general exclusion is $10 of countable
+  # unearned income; $100/month of earnings less the $65 earned income
+  # exclusion, halved, is $17.50. Countable income is $27.50, so SSI pays
+  # $30 - $27.50 = $2.50/month. The supplement does not depend on income.
+  period: 2024
+  input:
+    people:
+      person1:
+        age: 80
+        pension_income: 360
+        employment_income: 1_200
+        is_in_medicaid_facility: true
+        ssi_lives_in_medical_treatment_facility: true
+        ssi_medicaid_pays_majority_of_care: true
+    tax_units:
+      tax_unit:
+        members: [person1]
+    spm_units:
+      spm_unit:
+        members: [person1]
+    households:
+      household:
+        members: [person1]
+        state_code: TX
+  output:
+    ssi_countable_income: 330
+    ssi: 30
+    tx_ssi_state_supplement_eligible: true
+    tx_ssi_state_supplement: 540

From 2a8117fb74935bf70a5e4b78fac89033ee138f9b Mon Sep 17 00:00:00 2001
From: Max Ghenis <max@policyengine.org>
Date: Mon, 19 Oct 2026 14:15:22 -0400
Subject: [PATCH 4/5] Read SSI's medical treatment facility rate in Texas;
 retire the duplicate

gov.ssa.ssi.amount.institutional.individual held the same $30 reduced
federal benefit (42 USC 1382(e)(1)(B)) as gov.ssa.ssi.amount.medical_facility,
the parameter federal SSI reads, but only from July 1988. Texas's supplement
and its eligibility test read the duplicate, so for 1988-06 federal SSI paid
$25 while the Texas eligibility test raised ParameterNotFoundError. Point
both Texas readers at medical_facility and remove the institutional node
(its couple value, $60, had no reader; SSI pays the per-person rate to each
spouse). medical_facility's citation moves from (e)(1)(A), the public
institution bar, to (e)(1)(B), and notes the July 1988 increase.

Values match for every month from 1988-07 through 2100-12, and the Texas
outputs are unchanged across 126 probed months from 1988-07 to 2027-09.
Adds 2011 and 1989 cases at the $30 standard's boundary.

Raised by DTrim99 on #10148 (suggestion 4).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ...ssi-institutional-single-source.removed.md |  1 +
 .../ssa/ssi/amount/institutional/couple.yaml  | 14 -----
 .../ssi/amount/institutional/individual.yaml  | 14 -----
 .../gov/ssa/ssi/amount/medical_facility.yaml  | 10 +++-
 .../tx_ssi_state_supplement.yaml              | 59 +++++++++++++++++++
 .../tx_ssi_state_supplement_eligible.yaml     | 27 +++++++++
 .../tx_ssi_state_supplement.py                |  2 +-
 .../tx_ssi_state_supplement_eligible.py       |  2 +-
 8 files changed, 97 insertions(+), 32 deletions(-)
 create mode 100644 changelog.d/ssi-institutional-single-source.removed.md
 delete mode 100644 policyengine_us/parameters/gov/ssa/ssi/amount/institutional/couple.yaml
 delete mode 100644 policyengine_us/parameters/gov/ssa/ssi/amount/institutional/individual.yaml

diff --git a/changelog.d/ssi-institutional-single-source.removed.md b/changelog.d/ssi-institutional-single-source.removed.md
new file mode 100644
index 00000000000..d918d0a1c9f
--- /dev/null
+++ b/changelog.d/ssi-institutional-single-source.removed.md
@@ -0,0 +1 @@
+Remove the duplicate `gov.ssa.ssi.amount.institutional` parameters; the Texas SSI supplement and its eligibility test now read `gov.ssa.ssi.amount.medical_facility`, the reduced federal rate federal SSI uses. Results are unchanged from July 1988; for earlier months the eligibility test applies the $25 rate then in force instead of raising `ParameterNotFoundError`.
diff --git a/policyengine_us/parameters/gov/ssa/ssi/amount/institutional/couple.yaml b/policyengine_us/parameters/gov/ssa/ssi/amount/institutional/couple.yaml
deleted file mode 100644
index 75c194fb60b..00000000000
--- a/policyengine_us/parameters/gov/ssa/ssi/amount/institutional/couple.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-description: The Social Security Administration provides this reduced Supplemental Security Income amount for an eligible couple both residing in a Medicaid-funded institution.
-
-values:
-  1988-07-01: 60
-
-metadata:
-  unit: currency-USD
-  period: month
-  label: Federal SSI reduced institutional payment for couples
-  reference:
-    - title: 42 USC 1382(e)(1)(B)
-      href: https://www.law.cornell.edu/uscode/text/42/1382
-    - title: HHSC MEPD Handbook Section H-6000 - Co-Payment for SSI Cases
-      href: https://www.hhs.texas.gov/handbooks/medicaid-elderly-people-disabilities-handbook/h-6000-co-payment-ssi-cases
diff --git a/policyengine_us/parameters/gov/ssa/ssi/amount/institutional/individual.yaml b/policyengine_us/parameters/gov/ssa/ssi/amount/institutional/individual.yaml
deleted file mode 100644
index 386d859f571..00000000000
--- a/policyengine_us/parameters/gov/ssa/ssi/amount/institutional/individual.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-description: The Social Security Administration provides this reduced Supplemental Security Income amount for an eligible individual residing in a Medicaid-funded institution.
-
-values:
-  1988-07-01: 30
-
-metadata:
-  unit: currency-USD
-  period: month
-  label: Federal SSI reduced institutional payment for individuals
-  reference:
-    - title: 42 USC 1382(e)(1)(B)
-      href: https://www.law.cornell.edu/uscode/text/42/1382
-    - title: HHSC MEPD Handbook Section H-6000 - Co-Payment for SSI Cases
-      href: https://www.hhs.texas.gov/handbooks/medicaid-elderly-people-disabilities-handbook/h-6000-co-payment-ssi-cases
diff --git a/policyengine_us/parameters/gov/ssa/ssi/amount/medical_facility.yaml b/policyengine_us/parameters/gov/ssa/ssi/amount/medical_facility.yaml
index 3a0a43f1d6f..405dff3c1fa 100644
--- a/policyengine_us/parameters/gov/ssa/ssi/amount/medical_facility.yaml
+++ b/policyengine_us/parameters/gov/ssa/ssi/amount/medical_facility.yaml
@@ -1,6 +1,12 @@
 description: SSA sets this amount as the monthly federal SSI payment for an eligible individual residing in a medical treatment facility where Medicaid pays more than half the cost of care.
 
 values:
+  # 42 USC 1382(e)(1)(B)(i) sets "$360 per year". Pub. L. 100-203 section
+  # 9119(a) substituted that for "$300 per year", effective July 1, 1988
+  # (section 9119(c)). 20 CFR 416.414(b)(1): "For months after June 1988, the
+  # benefit rate for an eligible individual with no eligible spouse is $30 per
+  # month." Clause (iii) sets $720 per year for a couple both in a facility;
+  # ssi_amount_if_eligible applies this per-person amount to each spouse.
   1975-01-01: 25
   1988-07-01: 30
 
@@ -9,7 +15,7 @@ metadata:
   period: month
   label: SSI medical treatment facility monthly payment
   reference:
-    - title: 42 U.S.C. § 1382(e)(1)(A) - Amount of benefits for individuals in medical treatment facilities
-      href: https://www.law.cornell.edu/uscode/text/42/1382#e_1_A
+    - title: 42 U.S.C. § 1382(e)(1)(B) - Benefits for individuals in medical treatment facilities
+      href: https://www.law.cornell.edu/uscode/text/42/1382#e_1_B
     - title: 20 CFR § 416.414 - Amount of benefits; eligible individual or eligible couple in a medical treatment facility
       href: https://www.law.cornell.edu/cfr/text/20/416.414
diff --git a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
index 4d48d38aed6..692350cf5b8 100644
--- a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
+++ b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.yaml
@@ -338,3 +338,62 @@
     ssi: 30
     tx_ssi_state_supplement_eligible: true
     tx_ssi_state_supplement: 540
+
+- name: Case 29, 2011 facility resident whose countable income equals the $30 reduced standard.
+  # A $50/month pension less the $20 general exclusion is $30 of countable
+  # income. Federal SSI and the eligibility test read the same $30 standard
+  # (gov.ssa.ssi.amount.medical_facility): SSI pays $30 - $30 = $0 and the
+  # resident still gets the $30 supplement ($60 PNA less $30).
+  period: 2011
+  input:
+    people:
+      person1:
+        age: 80
+        pension_income: 600
+        is_in_medicaid_facility: true
+        ssi_lives_in_medical_treatment_facility: true
+        ssi_medicaid_pays_majority_of_care: true
+    tax_units:
+      tax_unit:
+        members: [person1]
+    spm_units:
+      spm_unit:
+        members: [person1]
+    households:
+      household:
+        members: [person1]
+        state_code: TX
+  output:
+    ssi_countable_income: 360
+    ssi: 0
+    tx_ssi_state_supplement_eligible: true
+    # ($60 - $30) * 12 = $360/year
+    tx_ssi_state_supplement: 360
+
+- name: Case 30, 2011 facility resident whose countable income exceeds the $30 reduced standard.
+  # A $51/month pension gives $31 of countable income, so neither SSI nor the
+  # supplement is paid.
+  period: 2011
+  input:
+    people:
+      person1:
+        age: 80
+        pension_income: 612
+        is_in_medicaid_facility: true
+        ssi_lives_in_medical_treatment_facility: true
+        ssi_medicaid_pays_majority_of_care: true
+    tax_units:
+      tax_unit:
+        members: [person1]
+    spm_units:
+      spm_unit:
+        members: [person1]
+    households:
+      household:
+        members: [person1]
+        state_code: TX
+  output:
+    ssi_countable_income: 372
+    ssi: 0
+    tx_ssi_state_supplement_eligible: false
+    tx_ssi_state_supplement: 0
diff --git a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.yaml b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.yaml
index 37defc1922a..bc580932635 100644
--- a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.yaml
+++ b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.yaml
@@ -138,3 +138,30 @@
     state_code: TX
   output:
     tx_ssi_state_supplement_eligible: false
+
+- name: Case 12, countable income equal to the $30 reduced standard in its first full year.
+  # 42 USC 1382(e)(1)(B) has paid $30/month since July 1, 1988 (Pub. L.
+  # 100-203 section 9119). $360/year = $30/month.
+  period: 1989
+  input:
+    is_ssi_eligible: true
+    ssi_countable_income: 360
+    is_in_medicaid_facility: true
+    ssi_lives_in_medical_treatment_facility: true
+    ssi_medicaid_pays_majority_of_care: true
+    state_code: TX
+  output:
+    tx_ssi_state_supplement_eligible: true
+
+- name: Case 13, countable income above the $30 reduced standard in its first full year.
+  # $372/year = $31/month.
+  period: 1989
+  input:
+    is_ssi_eligible: true
+    ssi_countable_income: 372
+    is_in_medicaid_facility: true
+    ssi_lives_in_medical_treatment_facility: true
+    ssi_medicaid_pays_majority_of_care: true
+    state_code: TX
+  output:
+    tx_ssi_state_supplement_eligible: false
diff --git a/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py b/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py
index ef6f2e4c6fa..a4089b06579 100644
--- a/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py
+++ b/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement.py
@@ -31,5 +31,5 @@ def formula(person, period, parameters):
         # the $30 standard, so the allowance less both is the same amount.
         p = parameters(period).gov.states.tx.hhsc.ssi_state_supplement
         pna = p.personal_needs_allowance
-        federal_reduced = parameters(period).gov.ssa.ssi.amount.institutional.individual
+        federal_reduced = parameters(period).gov.ssa.ssi.amount.medical_facility
         return max_(pna - federal_reduced, 0)
diff --git a/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.py b/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.py
index 9e8ef04d513..dbd74169175 100644
--- a/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.py
+++ b/policyengine_us/variables/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.py
@@ -43,7 +43,7 @@ def formula(person, period, parameters):
             - person("ssi_income_deemed_from_ineligible_spouse", period),
             0,
         )
-        within_reduced_rate = own_countable_income <= p.amount.institutional.individual
+        within_reduced_rate = own_countable_income <= p.amount.medical_facility
         eligible_for_ssi = (
             person("is_ssi_eligible", period)
             & person("takes_up_ssi_if_eligible", period.this_year)

From 72792f7ff259ec6e82204507f75b01605bf73a95 Mon Sep 17 00:00:00 2001
From: Max Ghenis <max@policyengine.org>
Date: Mon, 26 Oct 2026 14:14:53 -0700
Subject: [PATCH 5/5] Test the pre-July-1988 $25 rate; cite 1382(e)(1)(B) for
 the $30 rate

Review r1 found that eligibility Cases 12-13 (1989) repeated Cases 6-7: both
the old and new parameter are $30 then, so they pass before and after this
PR. The one behaviour change is before July 1988, where the eligibility test
now applies the $25 rate instead of raising ParameterNotFoundError. Move
Cases 12-13 to 1987 ($300/year eligible, $312/year not). They fail on the
parent commit (ParameterNotFoundError on the retired parameter), when the
1975-01-01 entry is dropped, and (Case 13) when that entry is set to $30.

Also fix ssi_amount_if_eligible's comment: the medical treatment facility
rate is 42 USC 1382(e)(1)(B); (e)(1)(A) is the public-institution bar.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../tx_ssi_state_supplement_eligible.yaml     | 19 ++++++++++---------
 .../gov/ssa/ssi/ssi_amount_if_eligible.py     |  2 +-
 2 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.yaml b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.yaml
index bc580932635..28b478081da 100644
--- a/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.yaml
+++ b/policyengine_us/tests/policy/baseline/gov/states/tx/hhsc/ssi_state_supplement/tx_ssi_state_supplement_eligible.yaml
@@ -139,13 +139,14 @@
   output:
     tx_ssi_state_supplement_eligible: false
 
-- name: Case 12, countable income equal to the $30 reduced standard in its first full year.
-  # 42 USC 1382(e)(1)(B) has paid $30/month since July 1, 1988 (Pub. L.
-  # 100-203 section 9119). $360/year = $30/month.
-  period: 1989
+- name: Case 12, countable income equal to the $25 reduced standard before July 1988.
+  # 42 USC 1382(e)(1)(B)(i) said "$300 per year" until Pub. L. 100-203
+  # section 9119(a) substituted "$360 per year", effective July 1, 1988
+  # (section 9119(c)). $300/year = $25/month.
+  period: 1987
   input:
     is_ssi_eligible: true
-    ssi_countable_income: 360
+    ssi_countable_income: 300
     is_in_medicaid_facility: true
     ssi_lives_in_medical_treatment_facility: true
     ssi_medicaid_pays_majority_of_care: true
@@ -153,12 +154,12 @@
   output:
     tx_ssi_state_supplement_eligible: true
 
-- name: Case 13, countable income above the $30 reduced standard in its first full year.
-  # $372/year = $31/month.
-  period: 1989
+- name: Case 13, countable income above the $25 reduced standard before July 1988.
+  # $312/year = $26/month.
+  period: 1987
   input:
     is_ssi_eligible: true
-    ssi_countable_income: 372
+    ssi_countable_income: 312
     is_in_medicaid_facility: true
     ssi_lives_in_medical_treatment_facility: true
     ssi_medicaid_pays_majority_of_care: true
diff --git a/policyengine_us/variables/gov/ssa/ssi/ssi_amount_if_eligible.py b/policyengine_us/variables/gov/ssa/ssi/ssi_amount_if_eligible.py
index bfe5cdf394a..480f7e72483 100644
--- a/policyengine_us/variables/gov/ssa/ssi/ssi_amount_if_eligible.py
+++ b/policyengine_us/variables/gov/ssa/ssi/ssi_amount_if_eligible.py
@@ -65,6 +65,6 @@ def formula(person, period, parameters):
             base_amount,
         )
 
-        # 42 USC § 1382(e)(1)(A), 20 CFR § 416.414: Medical treatment
+        # 42 USC § 1382(e)(1)(B), 20 CFR § 416.414: Medical treatment
         # facility, $30/month per person.
         return where(is_medical_facility, p.medical_facility, base_amount)