Add configurable Social Security COLA means test

changelog.d/ss-cola-means-test-e3.added.md

@@ -0,0 +1 @@
+Add an opt-in Social Security COLA means test using prior-year MAGI excluding Social Security, configurable indexed thresholds and filing groups, cohort or all-beneficiary scope, statutory or chained CPI-U COLAs, income-history sensitivities, and an A9 preset. Apply each withholding decision jointly with other COLA changes in reported benefits and the household calculator, with current-law defaults unchanged.

docs/social-security-benefit-levers.md

@@ -115,8 +115,10 @@ For each exposed payment event, statutory baseline rate c and configured
 addition delta give adjusted rate max(0,c+delta), without a second rounding of
 the policy addition. The joint multiplier is `(1+adjusted)/(1+c)` unless that
 event is withheld, in which case it is `1/(1+c)`. Each component's
-`_cola_withheld` term defaults false; a subsequent means-test implementation
-supplies the rules. Switching a policy off later preserves its earlier effect
+`_cola_withheld` term defaults false; the optional
+[COLA means test](social-security-cola-means-test.md) supplies prior-year income
+decisions when enabled. Explicit decisions remain available. Switching a policy
+off later preserves its earlier effect
 on the benefit level. Public reported-route benefits multiply this joint factor,
 the PIA ratio factor, the across-the-board factor, and the payable factor once.
 

docs/social-security-cola-means-test.md

@@ -0,0 +1,254 @@
+# Social Security COLA means test
+
+The contributed COLA means test is disabled under current law. It can withhold
+an annual COLA based on the beneficiary's tax unit, while retaining the benefit
+level reached before that event. It supports both reported benefit components
+and the supplied-record household calculator. Scenario thresholds and dates
+come from the scoring settings; PE-US does not choose package values.
+
+## Policy basis and choices
+
+The income test follows [OACT provision A9 on the 2026 Trustees Report
+basis](https://www.ssa.gov/OACT/solvency/provisions/cola.html). Its instruction
+is: “Use prior tax year income data for this determination.” The live page
+was available when this implementation was prepared.
+
+A9 uses a chained CPI-U COLA below the income line and no COLA above it, for
+all beneficiaries beginning with the December 2028 COLA. Its single,
+head-of-household and separate filers share a line; joint filers have twice
+that line. It also specifies chained CPI-U before benefit receipt. Its example
+lines are $85,000 and $170,000 in 2018 dollars, indexed by CPI-U. The preset
+below implements these mechanics. OACT's displayed December 2028 dollar
+estimates use its projections; this model calculates indexed lines from its
+own pinned CPI-U path.
+
+The default enabled scenario differs from A9 in two parameterized ways: it
+retains the statutory COLA below the line and restricts the policy to people
+first eligible from 2026. The effective date, first-eligible year, filing-group
+mapping, dollar lines, base year, index lag and rounding increment are also
+parameters. A surviving spouse maps to the joint line by default; this is a
+modeling choice because A9 does not name that status. Only income strictly
+above the line withholds a COLA. Equality receives the COLA, an explicit
+convention for A9's otherwise unspecified equality case.
+
+## Parameters and activation
+
+All paths in this table are relative to
+`gov.contrib.ssa.benefit_levers.cola.means_test`.
+Choice parameters use numeric codes because the parameter engine does not
+accept string-valued choices. The semantic names below label those codes;
+reforms must supply the numbers.
+
+| Parameter | Current-law/default value | Scenario meaning |
+| --- | --- | --- |
+| `enabled` | `false` | Opt into the means test. |
+| `scope` | `0` = `first_eligible_cohorts` | Alternatively, `1` = `all_beneficiaries`. |
+| `first_eligible_year` | `2026` | Inclusive first-eligibility boundary in cohort mode. |
+| `effective_year`, `effective_month` | `2026`, `12` | First affected effective COLA; ordinarily first paid January 2027. |
+| `below_threshold_cola_index` | `0` = `statutory` | Alternatively, `1` = `chained_cpi_u`. |
+| `pre_receipt_cola_index` | `-1` = `follow_below_threshold` | Follow the below-line choice, or explicitly select `0` = `statutory` or `1` = `chained_cpi_u`. |
+| `income_sensitivity` | `0` = `prior_year` | Alternatively, `1` = `never_withheld` or `2` = `always_withheld`. |
+| `thresholds.base_year` | `2026` | Dollar year of the supplied lines. |
+| `thresholds.single`, `thresholds.joint` | `0`, `0` | Neutral placeholders; evaluated `prior_year` income decisions require positive scenario lines. |
+| `thresholds.index_lag` | `1` | Years before the payment year for the December CPI-U observation. |
+| `thresholds.rounding` | `100` | Dollar increment, rounded half up. |
+| `filing_groups.SINGLE` | `0` = `single` | Select the single line; `1` selects joint. |
+| `filing_groups.HEAD_OF_HOUSEHOLD` | `0` = `single` | Select the single line; `1` selects joint. |
+| `filing_groups.SEPARATE` | `0` = `single` | Select the single line; `1` selects joint. |
+| `filing_groups.JOINT` | `1` = `joint` | Select the joint line; `0` selects single. |
+| `filing_groups.SURVIVING_SPOUSE` | `1` = `joint` | Modeling choice; `0` selects single. |
+
+`means_test.enabled` activates both the income decision and the selected index
+without requiring another switch. The enclosing `cola.withholding_enabled`
+remains the A5 switch for externally resolved withholding decisions when the
+means test is disabled. With either channel enabled, explicit component
+withholding values and `ss_calculator_withhold_cola` are deliberate decision
+overrides. The automatic timing, cohort and receipt restrictions apply to
+calculated decisions; supplied decisions retain normal override precedence.
+When the automatic policy is inactive, manual component inputs retain their
+legacy carry-forward behavior. Calculator-specific decisions apply only in
+their explicitly supplied year.
+
+Positive single and joint lines are required when a `prior_year` income
+decision is evaluated. The `never_withheld` and `always_withheld` sensitivities
+and pre-receipt index-only events do not read those lines.
+
+The `a9` preset in `policyengine_us.reforms.ssa.cola_means_test` enables the
+policy and selects:
+
+```yaml
+scope: 1  # all_beneficiaries
+effective_year: 2028
+effective_month: 12
+below_threshold_cola_index: 1  # chained_cpi_u
+pre_receipt_cola_index: 1  # chained_cpi_u
+income_sensitivity: 0  # prior_year
+thresholds:
+  base_year: 2018
+  single: 85000
+  joint: 170000
+  index_lag: 1
+  rounding: 100
+```
+
+Apply it as a reform, for example:
+
+```python
+from policyengine_us import Simulation
+from policyengine_us.reforms.ssa.cola_means_test import a9
+
+simulation = Simulation(situation=situation, reform=a9)
+```
+
+These are public A9 example settings, not a scenario's package values. The
+first affected checks are in January 2029. The ordinary contributed scenario
+instead supplies its own positive 2026-dollar lines and retains the default
+statutory/cohort choices unless its policy specifies otherwise.
+
+## Prior-year income and filing status
+
+`social_security_cola_means_test_magi` is a dedicated annual TaxUnit variable.
+Its definition is AGI less taxable Social Security, plus tax-exempt interest
+and the IRMAA-style exclusions under Internal Revenue Code sections 135, 911,
+931 and 933. AGI retains its applicable deductions. This implements the
+required MAGI excluding Social Security, replacing the earlier gross-source
+income proposal. The [A9-linked actuarial memorandum, provision 5 on page
+8](https://www.ssa.gov/OACT/solvency/SJohnson_20161208.pdf) connects the lines
+to Medicare IRMAA; [H.R. 6489 section
+103(d)](https://www.congress.gov/bill/114th-congress/house-bill/6489/text)
+supplies the corresponding IRMAA definition reference. Excluding Social
+Security and using the prior year are requirements of this contributed lever.
+
+For COLAs first paid in year `y`, the decision reads this MAGI and filing
+status for tax year `y - 1`. It never substitutes current-year AGI. A supplied
+MAGI history can directly set the dedicated variable for the relevant tax
+years; supplied histories of its income sources and filing status also take
+precedence over projected records. A tax unit's decision maps to each
+beneficiary, subject to that component's exposure and cohort scope.
+Core stores complete input arrays for each variable and period; an income
+history column must supply a value for every tax unit in that array.
+
+Although prior-year AGI can depend on prior-year Social Security, every
+benefit-related lookback moves to an earlier year. The dependency chain stops
+before the policy's first affected event. It cannot return to the same
+benefit/year pair. Multi-year dependency-graph tests exercise this decreasing
+year chain, including deductions whose MAGI depends on taxable benefits.
+The household engine resolves decisions only through the requested check
+year for payment outputs. It does not eagerly read the income for the next
+January COLA while computing this year's checks. December entitlement and
+annual entitlement can require that next event; their prior-income dependency
+uses the separate public payment route.
+
+Population scoring uses a **static-cross-section prior-income proxy**.
+Dataset extension starts each year from the same original record and uprates
+its monetary sources separately. The `y - 1` record is that same record's
+extended prior-year copy, not an observed longitudinal income history. Ages,
+cohorts and household composition are not carried forward as a person's
+history. Supplied histories override this proxy. Compare
+`income_sensitivity = 1` (`never_withheld`) and `2` (`always_withheld`) to
+report the missing-income-history sensitivity envelope; both retain policy
+timing and cohort scope.
+
+## Threshold indexing and COLA construction
+
+For filing group `g`, base year `b`, payment year `y`, index lag `L` and
+rounding increment `R`, the income line is:
+
+```text
+line(g, y) = round_half_up_to_R(
+    base_line(g) * CPI_U(December, y - L) / CPI_U(December, b)
+)
+withheld(y) = prior_year_MAGI > line(g, y)
+```
+
+The CPI-U series is `gov.bls.cpi.cpi_u`. The default observes the December
+before the check year, including December 2028 for January 2029 checks.
+Parameter snapshots are held until the next authored observation, including
+in projections. The December snapshot, one-year payment lag and nearest-$100
+half-up rounding are documented modeling conventions: A9 specifies CPI-U
+indexing without prescribing these details. Pin both the index path and
+these settings for a score.
+
+The chained option uses Q3 averages of July, August and September levels from
+`gov.bls.cpi.c_cpi_u`. As with the statutory CPI-W schedule, positive growth
+is rounded half up to 0.1 percentage point; nonpositive or rounded-zero growth
+gives no COLA. The comparison base is the Q3 associated with the last positive
+index-derived COLA. A withheld year still advances that index schedule's
+comparison base when its rounded rate is positive: income withholding must
+not create a catch-up COLA later. Neither withholding nor a downward rate
+adjustment reduces the nominal benefit level. Historical benefit-rounding
+rules remain attached to their individual events.
+
+Before receipt, `pre_receipt_cola_index` controls COLAs accrued since initial
+eligibility. Its default follows `below_threshold_cola_index`; the A9 preset
+therefore uses chained CPI-U for these events. From the policy's effective
+start, these pre-receipt events use the chosen index without an income test.
+Supply entitlement and worker eligibility dates when known. Missing-date
+cohort and exposure approximations remain those described in the
+[benefit-lever guide](social-security-benefit-levers.md), including
+adjacent-cohort sensitivities for integer-age uncertainty.
+
+An active A5 `cola.alternative_rate` overrides the index selected here. The
+applicable `cola.pp_change` is then added to that rate, and the final rate is
+floored at zero. Withholding overrides the entire resulting increase.
+
+## One joint COLA adjustment
+
+Each annual Person variable `social_security_X_cola_withheld`, for `X` equal
+to `retirement`, `disability`, `survivors` or `dependents`, has a formula that
+resolves its tax unit's decision. Explicit values override that formula.
+For a reported benefit, the population adjustment accumulates one ratio for
+each exposed event:
+
+```text
+event numerator = 1                         if withheld
+                  1 + adjusted_COLA        otherwise
+event ratio     = event numerator / (1 + statutory_COLA)
+joint factor    = product of the exposed event ratios
+```
+
+The adjusted rate includes the selected index and applicable percentage-point
+change, with a floor of zero. For example, statutory rates of 2% and 3% plus a
+CPI-E-style addition of 0.15 percentage points give numerators `1.0215` and
+`1.0315` if paid. If the second year is withheld, the two-year factor is
+`(1.0215 / 1.02) * (1 / 1.03)`, approximately `0.97230`. The reformed level
+from a pre-event amount of $1,000 is $1,021.50, compared with the statutory
+$1,050.60. The withheld event receives no CPI-E increase. An independently
+multiplied withholding factor would give the wrong result.
+
+The household calculator applies the same per-year decisions inside its COLA
+schedule. It rounds the resulting PIA under the applicable event rule and
+applies claiming and payment calculations once. Its explicit annual
+`ss_calculator_withhold_cola` value takes precedence over the shared decision.
+
+For a public retirement component, select `social_security_retirement_source`
+as `supplied_aime` or `supplied_pia`, and supply the matching
+`ss_calculator_source` of `aime` or `pia`. For a restricted survivor record,
+select `social_security_survivors_source = supplied_ratio_survivor` and
+`ss_calculator_source = survivor`. These routes retain the calculator's input
+and scope requirements in the [calculator
+guide](usage/social-security-calculator.md).
+
+Calculated public routes bypass all population benefit factors: the engine
+already applies the COLA, across-the-board and payable policies to its ledger.
+Reported sources use the population factors. This avoids applying any of
+these policies twice. Switching a policy off later does not restore an
+earlier withheld increase.
+
+## Validation contract
+
+Validation covers all statutory/chained and cohort/all-beneficiary
+combinations, both sides of the first-eligibility boundary, the A9 preset,
+all filing statuses, equality, supplied histories, and both income
+sensitivities. Boundary cases include a zero statutory COLA, negative rate
+adjustments, high-water years and combined CPI-E changes and withholding.
+Multi-year graph checks establish that the prior-year income read has no
+cycle. Calculated-source cases check that the COLA policy is applied once.
+
+Property checks require disabled-policy equality to the stacked base,
+nonincreasing benefits when a year is withheld, monotone withholding as income
+rises at a fixed line, and equality of the joint factor to the product of its
+per-year ratios. Differential checks cover reported situations, downstream
+outputs and household calculator examples with this means test disabled.
+Population impact requires a separately pinned scoring run; these mechanics
+do not substitute OACT's solvency estimates for a PE-US result.

docs/usage/social-security-calculator.md

@@ -220,23 +220,23 @@ Withholding sets that event's COLA to zero, jointly with any rate change; no
 second COLA factor is applied. Payable shares must lie in [0,1], and rates must
 not imply a negative benefit. A depletion-year midyear blend is supplied in the
 annual payable-share path. E2 and E3 income/threshold computation belong to
-their respective modules; their policies and jointly calculated tax-unit
-outputs can consume this route once public wiring exists.
+their respective modules. The [COLA means test](../social-security-cola-means-test.md)
+now supplies these decisions from prior-tax-year MAGI and filing status.
 
 ## Public source-selector wiring
 
-Source-selector PR #10400 was open when this route was built. Its canonical
-COLA history and common lever parameter files are reused here. Historical bend
+The source selectors reuse the canonical COLA history and common lever
+parameter files. Historical bend
 points remain in a separate table because copying its legacy scale backfill
-would change existing pre-2015 `ss_pia` outputs with this route disabled. This change adds
-no `_reported` twins and changes no public benefit formula. Once it merges,
-map its supplied-AIME/PIA retirement modes to `ss_calculated_retirement` and its
-restricted survivor mode to `ss_calculated_survivors`. Bypass population
-PIA/COLA factors and any across/payable factors already applied in this ledger;
-perform the earnings test once. Preserve explicit public final overrides.
-For joint household tax calculations before that wiring, explicitly supply the
-calculated annual checks to the existing public components in a separate
-calculation; never write them into `_reported` as if they were original data.
+would change existing pre-2015 `ss_pia` outputs with this route disabled.
+Select `social_security_retirement_source` as `supplied_aime` or `supplied_pia`
+with matching `ss_calculator_source` of `aime` or `pia`. For the restricted
+survivor route, select `social_security_survivors_source` as
+`supplied_ratio_survivor` with calculator source `survivor`. The public benefit
+then reads the calculated checks, bypassing population PIA, COLA, across-the-board
+and payable factors already applied in this ledger. The earnings test runs
+once. Explicit public final overrides retain their precedence. Calculated
+checks are never written into `_reported` as original data.
 
 ## Sources and validation
 

policyengine_us/parameters/gov/contrib/ssa/benefit_levers/cola/means_test/below_threshold_cola_index.yaml

@@ -0,0 +1,9 @@
+description: "COLA index for income at or below the means-test threshold: 0 = statutory pays the full statutory COLA; 1 = chained_cpi_u uses gov.bls.cpi.c_cpi_u with statutory rounding, high-water and no-decrease rules. The A9 preset uses 1. Numeric codes provide compatibility with the parameter engine."
+values:
+  0000-01-01: 0
+metadata:
+  label: Social Security below-threshold COLA index
+  economy: false
+  reference:
+    - title: OACT provision A9, 2026 Trustees Report basis
+      href: https://www.ssa.gov/OACT/solvency/provisions/cola.html

policyengine_us/parameters/gov/contrib/ssa/benefit_levers/cola/means_test/effective_month.yaml

@@ -0,0 +1,10 @@
+description: First effective COLA calendar month for the contributed means test. The default December COLA first changes January payments in the following calendar year.
+values:
+  0000-01-01: 12
+metadata:
+  unit: month
+  label: Social Security COLA means-test effective month
+  economy: false
+  reference:
+    - title: OACT provision A9, 2026 Trustees Report basis
+      href: https://www.ssa.gov/OACT/solvency/provisions/cola.html

policyengine_us/parameters/gov/contrib/ssa/benefit_levers/cola/means_test/effective_year.yaml

@@ -0,0 +1,10 @@
+description: First effective COLA calendar year for the contributed means test. A December COLA first changes January payments in the following year. The A9 preset uses December 2028.
+values:
+  0000-01-01: 2026
+metadata:
+  unit: year
+  label: Social Security COLA means-test effective year
+  economy: false
+  reference:
+    - title: OACT provision A9, 2026 Trustees Report basis
+      href: https://www.ssa.gov/OACT/solvency/provisions/cola.html

policyengine_us/parameters/gov/contrib/ssa/benefit_levers/cola/means_test/enabled.yaml

@@ -0,0 +1,10 @@
+description: Enable the contributed Social Security COLA means test. Positive single and joint income thresholds supplied by the scenario are required when a prior_year income decision is evaluated. The never_withheld and always_withheld sensitivities and pre-receipt index-only events do not read the thresholds.
+values:
+  0000-01-01: false
+metadata:
+  unit: bool
+  label: Social Security COLA means test enabled
+  economy: false
+  reference:
+    - title: OACT provision A9, 2026 Trustees Report basis
+      href: https://www.ssa.gov/OACT/solvency/provisions/cola.html