Implement South Carolina SSI State Supplement

[MaxGhenis]

Summary

Implements the South Carolina SSI State Supplement (Optional State Supplementation / OSS) program.

Closes #7343

Program overview

South Carolina's OSS program supplements the income of eligible individuals residing in licensed Community Residential Care Facilities (CRCFs). Unlike many states' SSI supplements, SC's program:

• Is available only to individuals in CRCFs (not community residents or nursing home residents)
• Covers both SSI recipients and non-SSI individuals who meet SSA criteria for aged/blind/disabled
• Provides substantial facility payment support (up to $1,719/month to the facility as of 2026)
• Is state-administered by SCDHHS (not federally administered by SSA)

Regulatory authority

• S.C. Code Regs. 126-910 -- Program Definitions (OSS Program, CRCF, Net Income Limitation, Countable Income, PNA)
• S.C. Code Regs. 126-920 -- Eligibility (all seven criteria, couple treatment, recertification)
• S.C. Code Regs. 126-930 -- Termination, Suspension or Reduction of Benefits
• S.C. Code Regs. 126-940 -- Program Administration (funding, waiting lists, COLA rules)
• SCDHHS MB# 26-001 (Jan 8, 2026) -- Current payment amounts
• 42 USC 1382e -- Federal optional state supplementation authority

Eligibility criteria

Per S.C. Code Regs. 126-920, an individual must:

1. Be a resident of South Carolina
2. Be aged (65+), blind, or disabled per SSA criteria
3. Reside in a licensed CRCF with a Facility Participation Agreement
4. Have countable income (including SSI) below the Net Income Limit
5. Have resources within federal SSI resource limits

Implementation checks: is_ssi_aged_blind_disabled AND is_in_residential_care_facility AND (ssi_countable_income + ssi) < NIL, scoped to SC via defined_for = StateCode.SC.

Benefit calculation

OSS = max(0, NIL - ssi_countable_income - ssi)

Per S.C. Code Regs. 126-910: the state supplement equals the Net Income Limit minus the individual's total countable income (non-SSI countable income plus SSI payment).

Example 1: SSI-only recipient (2026)

ssi_countable_income = $0 (no non-SSI income)
SSI = $994/month = $11,928/year
NIL = $1,804/month = $21,648/year
OSS = $21,648 - $0 - $11,928 = $9,720/year ($810/month)
PNA = $85/month (SSI-only tier)

Example 2: SSI + Social Security recipient (2026)

ssi_countable_income = $200/month = $2,400/year (Social Security after SSI exclusions)
SSI = $994/month = $11,928/year
NIL = $1,804/month = $21,648/year
OSS = $21,648 - $2,400 - $11,928 = $7,320/year ($610/month)
PNA = $105/month (other income tier)

Personal needs allowance

Per S.C. Code Regs. 126-910(G), the PNA has two tiers:

Tier	2026 amount	Condition
SSI-only	$85/month	No non-SSI countable income
Other income	$105/month	Has income beyond SSI

Payment standards (2026)

Component	Monthly	Annual
Net Income Limit	$1,804	$21,648
Maximum Facility Payment	$1,719	$20,628
PNA (SSI-only)	$85	$1,020
PNA (other income)	$105	$1,260

Structural relationship: NIL = Maximum Facility Payment + PNA (SSI-only), verified for all years.

Files added

Variables (3 files)

policyengine_us/variables/gov/states/sc/scdhhs/ssi_state_supplement/
  sc_ssi_state_supplement.py           # Main benefit: max(0, NIL - countable_income - ssi)
  sc_ssi_state_supplement_eligible.py  # Eligibility: aged/blind/disabled + CRCF + income < NIL
  sc_ssi_state_supplement_pna.py       # Personal needs allowance: $85 or $105/month

Parameters (4 files)

policyengine_us/parameters/gov/states/sc/scdhhs/ssi_state_supplement/
  net_income_limit.yaml                    # $1,804/month (2026), history back to Jul 2022
  maximum_facility_payment.yaml            # $1,719/month (2026), history back to Jul 2022
  personal_needs_allowance/
    ssi_only.yaml                          # $85/month (2026)
    other_income.yaml                      # $105/month (2026)

Tests (4 files, 31 test cases)

policyengine_us/tests/policy/baseline/gov/states/sc/scdhhs/ssi_state_supplement/
  integration.yaml                     # 7 end-to-end scenarios
  sc_ssi_state_supplement.yaml         # 8 unit tests (benefit calculation)
  sc_ssi_state_supplement_eligible.yaml # 11 unit tests (eligibility logic)
  sc_ssi_state_supplement_pna.yaml     # 5 unit tests (PNA determination)

Other modified files

policyengine_us/variables/household/demographic/person/is_in_residential_care_facility.py  # New input variable
policyengine_us/variables/household/income/spm_unit/spm_unit_benefits.py                   # Added sc_ssi_state_supplement
policyengine_us/parameters/gov/household/household_state_benefits.yaml                     # Added sc_ssi_state_supplement
changelog_entry.yaml

Test coverage

File	Cases	Coverage
integration.yaml	7	End-to-end: eligible aged/disabled/blind, ineligible (no CRCF, not aged/blind/disabled, over-income, wrong state)
sc_ssi_state_supplement.yaml	8	Benefit calc: SSI-only, SSI+SS, over-income, ineligible, non-SSI, boundary, zero income, small income
sc_ssi_state_supplement_eligible.yaml	11	Eligibility: aged/disabled/blind in CRCF, not in CRCF, not aged/blind/disabled, wrong state, over-income, boundary (exact NIL, $1 below NIL), age boundaries (64 vs 65)
sc_ssi_state_supplement_pna.yaml	5	PNA: SSI-only tier, other income tier, ineligible, zero income edge, $1 income edge

All tests include step-by-step manual calculation comments.

References

• S.C. Code Regs. 126-910 -- Program Definitions
• S.C. Code Regs. 126-920 -- Eligibility
• SCDHHS MB# 26-001 (2026 COLA)
• SCDHHS 2025 COLA Bulletin
• SCDHHS 2024 COLA Bulletin
• SCDHHS MB# 23-009 (Jul 2023)
• SCDHHS MB# 22-013 (Jul 2022)

Known limitations

• Resource test not implemented: The federal SSI resource limit check ($2,000/$3,000) is not explicitly enforced in the OSS eligibility formula. It is handled implicitly for SSI recipients (who must pass the resource test for SSI), but non-SSI OSS applicants could bypass this in the simulation.
• Facility participation agreement: Cannot verify whether a specific CRCF has an active participation agreement with SCDHHS.
• Waiting list / slot availability: The program is funding-limited; slot availability cannot be modeled.
• Applied-for-all-benefits requirement: Cannot verify whether the individual has applied for all entitled benefits.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.92%. Comparing base (a46b5a8) to head (6c34c4a).
⚠️ Report is 29 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #7344       +/-   ##
===========================================
+ Coverage   86.56%   96.92%   +10.35%     
===========================================
  Files          12        5        -7     
  Lines         134       65       -69     
  Branches        0        2        +2     
===========================================
- Hits          116       63       -53     
+ Misses         18        1       -17     
- Partials        0        1        +1     

Flag	Coverage Δ
unittests	96.92% <100.00%> (+10.35%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.