Make CHIP health benefit value respect enrollment

changelog.d/8673.fixed.md

@@ -0,0 +1 @@
+Fixed CHIP health benefit value counting for CHIP-eligible people who do not enroll.

policyengine_us/tests/policy/baseline/household/healthcare_benefit_value.yaml

@@ -22,3 +22,49 @@
     msp_cost: 2_434.8
   output:
     healthcare_benefit_value: 2_434.8
+
+- name: Case 3, enrolled CHIP value is included in healthcare benefit value.
+  period: 2026
+  absolute_error_margin: 0.01
+  input:
+    state_code: AL
+    is_chip_eligible: true
+    takes_up_chip_if_eligible: true
+    medicaid_cost: 0
+    msp_cost: 0
+    assigned_aca_ptc: 0
+    co_omnisalud: 0
+    or_healthier_oregon_cost: 0
+  output:
+    chip: 2_209.43
+    healthcare_benefit_value: 2_209.43
+
+- name: Case 4, CHIP-eligible non-enroller has no healthcare benefit value.
+  period: 2026
+  input:
+    state_code: AL
+    is_chip_eligible: true
+    takes_up_chip_if_eligible: false
+    medicaid_cost: 0
+    msp_cost: 0
+    assigned_aca_ptc: 0
+    co_omnisalud: 0
+    or_healthier_oregon_cost: 0
+  output:
+    chip: 0
+    healthcare_benefit_value: 0
+
+- name: Case 5, CHIP-ineligible person has no healthcare benefit value.
+  period: 2026
+  input:
+    state_code: AL
+    is_chip_eligible: false
+    takes_up_chip_if_eligible: true
+    medicaid_cost: 0
+    msp_cost: 0
+    assigned_aca_ptc: 0
+    co_omnisalud: 0
+    or_healthier_oregon_cost: 0
+  output:
+    chip: 0
+    healthcare_benefit_value: 0

policyengine_us/variables/gov/hhs/chip/chip.py

@@ -8,5 +8,11 @@ class chip(Variable):
     unit = USD
     definition_period = YEAR
     reference = "https://www.macpac.gov/publication/chip-spending-by-state/"
+    documentation = (
+        "Annual net CHIP benefit value for an enrolled person. This variable "
+        "is gated by `chip_enrolled`, so it respects both eligibility and "
+        "take-up. Use `chip_gross` for the eligibility-gated gross service "
+        "value concept."
+    )
     defined_for = "chip_enrolled"
     adds = ["per_capita_chip"]

policyengine_us/variables/gov/hhs/chip/chip_federal_cost.py

@@ -7,7 +7,8 @@ class chip_federal_cost(Variable):
     label = "CHIP federal cost"
     documentation = (
         "Portion of CHIP expenditures borne by the federal government, "
-        "equal to total CHIP cost multiplied by the enhanced FMAP."
+        "equal to enrolled net CHIP cost multiplied by the enhanced FMAP. "
+        "This budget variable is enrollment-gated through `chip`."
     )
     unit = USD
     definition_period = YEAR

policyengine_us/variables/gov/hhs/chip/chip_gross.py

@@ -14,10 +14,11 @@ class chip_gross(Variable):
     documentation = (
         "Gross CHIP service value for a CHIP-eligible person, equal to the "
         "per-capita net CHIP spending plus the state's household cost-sharing "
-        "offsets. Counterpart to `chip`, which is the net-of-premium value "
-        "reported by MACPAC. Use this for household-side resource accounting "
-        "when premiums paid by the household are tracked separately via "
-        "`chip_premium`."
+        "offsets. This is eligibility-gated rather than enrollment-gated, "
+        "and is the counterpart to `chip`, which is the enrolled "
+        "net-of-premium value reported by MACPAC. Use this only when a gross "
+        "eligible-value concept is needed and enrollment take-up is modeled "
+        "separately."
     )
     defined_for = "is_chip_eligible"
     adds = ["per_capita_chip_gross"]

policyengine_us/variables/gov/hhs/chip/chip_state_cost.py

@@ -6,8 +6,9 @@ class chip_state_cost(Variable):
     entity = Person
     label = "CHIP state cost"
     documentation = (
-        "Portion of CHIP expenditures borne by the state, equal to total "
-        "CHIP cost less the federal share."
+        "Portion of CHIP expenditures borne by the state, equal to enrolled "
+        "net CHIP cost less the federal share. This budget variable is "
+        "enrollment-gated through `chip`."
     )
     unit = USD
     definition_period = YEAR

policyengine_us/variables/gov/hhs/chip/per_capita_chip.py

@@ -6,7 +6,11 @@ class per_capita_chip(Variable):
     entity = Person
     label = "Average CHIP payment"
     unit = USD
-    documentation = "Per-capita CHIP payment for this person's State."
+    documentation = (
+        "Per-capita net CHIP payment for this person's state. This variable "
+        "is eligibility-gated and does not model enrollment or take-up; use "
+        "`chip` for enrolled household resource accounting."
+    )
     definition_period = YEAR
     reference = "https://www.macpac.gov/publication/chip-spending-by-state/"
     defined_for = "is_chip_eligible"

policyengine_us/variables/gov/hhs/chip/per_capita_chip_gross.py

@@ -10,10 +10,10 @@ class per_capita_chip_gross(Variable):
         "Per-capita gross CHIP service value for this person's state, equal "
         "to the net federal-plus-state CHIP expenditure plus the household "
         "cost-sharing collections that offset it on CMS-21. This represents "
-        "the gross benefit value a CHIP enrollee receives (the service), "
-        "before netting their household-paid premium. For 2024 simulations, "
-        "net spending, enrollment, and cost-sharing offsets all use FY2024 "
-        "calibration data."
+        "an eligibility-gated gross value before netting household-paid "
+        "premiums; it is not enrollment- or take-up-gated. For 2024 "
+        "simulations, net spending, enrollment, and cost-sharing offsets all "
+        "use FY2024 calibration data."
     )
     definition_period = YEAR
     reference = (

policyengine_us/variables/household/healthcare_benefit_value.py

@@ -7,10 +7,14 @@ class healthcare_benefit_value(Variable):
     entity = Household
     definition_period = YEAR
     unit = USD
+    documentation = (
+        "Annual household health coverage value. CHIP is counted through "
+        "`chip`, which is gated on eligibility, take-up, and enrollment."
+    )
     adds = [
         "medicaid_cost",
         "msp_cost",
-        "per_capita_chip",
+        "chip",
         "assigned_aca_ptc",
         "co_omnisalud",
         "or_healthier_oregon_cost",