Supplied-record Social Security calculator

The opt-in calculator implements design v3 D0, 4a-1 and the shared 4d core, including amendments M1–M4, the top-factor structure in M6 and M8. It returns gross benefits before Medicare deductions, from an identified worker record. Existing public benefit inputs continue to work independently.

Inputs and outputs

Set ss_calculator_source to aime, pia or survivor; its default is off. The selector determines the route even when the selected amount is zero. Omitting the selected amount fails; it is distinct from supplying zero. Identity/source fields are eternal inputs. Supply exact recipient birth date, worker ID, entitlement month, insured status and source valuation basis. The only supported basis is unreformed_eligibility; externally reformed sources fail rather than applying a mechanism twice. Each member of a retired couple supplies their own record. Disability, spouse, child, minimum and dual-entitlement computations are outside this route.

For own retirement, also supply ss_calculator_eligibility_year and either ss_calculator_supplied_aime (whole monthly dollars) or ss_calculator_supplied_pia (monthly dimes at initial eligibility). Optional ss_calculator_claiming_factor is an exact decimal string; otherwise exact claiming months, birth-cohort FRA, early reduction and delayed credits determine it. Delayed credits earned in a midyear claiming year enter the benefit the following January, or upon reaching 70. A January 1 birth belongs to the previous attainment cohort. Retirement commencement must satisfy SSA’s full-month age-62 rule.

For example:

from policyengine_us import Simulation

simulation = Simulation(
    situation={
        "people": {
            "worker": {
                "ss_calculator_source": "aime",
                "ss_calculator_worker_id": "worker-record-1",
                "ss_calculator_birth_date": "1961-01-02",
                "ss_calculator_eligibility_year": 2023,
                "ss_calculator_entitlement_month": "2023-01",
                "ss_calculator_supplied_aime": 3000,
                "ss_calculator_insured": True,
                "ss_calculator_no_special_monthly_test": True,
                "ss_calculator_no_prior_withholding_adjustment": True,
                "ss_calculator_earnings_test_no_trigger": True,
            }
        },
    }
)
# SSA's 2023 example: $1,606.70 PIA, claim at 62/FRA 67 => $1,124.
monthly = simulation.calculate("ss_calculated_benefit", "2023-01")
checks = simulation.calculate("ss_calculated_annual_payment", 2023)

ss_calculated_benefit is the payable amount for an entitlement month; ss_calculated_payment is cash paid in the requested month, including any supplied earnings-test settlement. Ordinary checks follow entitlement by one month, subject to whole-month earnings-test withholding. ss_calculated_annual_entitlement sums January–December entitlement, whereas ss_calculated_annual_payment sums checks actually paid January–December. ss_calculated_retirement and ss_calculated_survivors expose the latter by selected component. A first entitlement in July normally yields five checks in that calendar year. COLAs effective December first affect January checks. S.770 section 2(c)(1) first affects January 2026 benefit entitlement, normally paid in February. Dated custom payment-year paths use the check year.

The pure calculate_year service returns both totals and a monthly ledger: eligibility PIA, PIA after each COLA, exact claiming factor, unrounded benefit, rounded gross benefit, capped earnings-test reduction and payable amount. The engine also exposes monthly ss_calculated_eligibility_pia, annual ss_calculated_earnings_test_reduction, and inferred PIA/AIME interval endpoints. An absent inference interval is exposed as zero; the source selector identifies which diagnostic applies.

Earnings test and scope assertions

Supply annual ss_calculator_annual_earnings. In the FRA year supply ss_calculator_pre_fra_earnings: only earnings before the retirement FRA month count. No earnings test applies from FRA onward. Annual excess-earnings deductions are truncated to whole dollars, allocated to the earliest affected benefit months and capped at their benefits. Calculating January’s check may also require the previous year’s earnings. A -1 earnings input means missing, not zero. Each annual earnings record must be supplied for its exact year; an earlier record never carries forward. Alternatively assert ss_calculator_earnings_test_no_trigger; supplied excess earnings contradicting it fail.

The default cash schedule withholds whole months, including the month whose deduction leaves a partial entitlement. That remainder is deferred until closed-year earnings reporting. SSA Handbook §1806.2 says, “The partial payment is paid only at the close of the taxable year”, “unless otherwise requested”. POMS RS 02501.110 says, “Once we receive the closed-year earnings, pay a partial monthly benefit, if due.”

ss_calculated_deferred_earnings_test_payment reports the remainder deferred from this entitlement year. Supply ss_calculator_earnings_test_settlement_month for the original earnings year, with its actual later YYYY-MM payment month, to include settlement in that month’s and year’s cash totals. A date in or before the earnings year fails. Without a supplied date, the settlement remains pending; the calculator does not assume when earnings are reported. Settlement never changes the original entitlement or earnings-test deduction.

Set ss_calculator_immediate_earnings_test_payment to true only when immediate partial payment was requested; it defaults false. The pure calculate_year API exposes the same choice as immediate_earnings_test_payment and accepts an earnings-year-to-month earnings_test_settlement_months mapping. Ledger rows retain payable_benefit as entitlement and expose payment_amount after deferral; dated settlement payments appear separately in AnnualBenefit.settlements. For January 2026 commencement, \(800 monthly benefits and \)33,400 earnings, the deduction is \(4,460 and annual entitlement \)5,140. Default 2026 checks total \(4,000 with \)340 deferred; requested immediate partial payment gives $4,340.

This route requires ss_calculator_no_special_monthly_test and ss_calculator_no_prior_withholding_adjustment. These assert that special first-year monthly/service rules and actuarial adjustments for prior withheld months do not affect the supplied case. Such cases need a separate computation or a supplied authoritative claiming factor and a valid scope assertion; this calculator does not silently approximate those rules. All entitlement before commencement, or on an uninsured record, is zero.

The earnings-test implementation covers entitlement years from 2000 onward. Earlier years require the explicit no-trigger assertion because historical age limits and deduction rates differ. Positive benefits below one dollar before December 2006 fail explicitly: their manual year-end payment timing is outside the recurring monthly ledger. Later sub-dollar benefits retain their dimes under SSA’s payment-rounding exception.

Restricted survivor

Select survivor and supply monthly gross paid amount, source valuation check month, positive decimal-string composite ratio and a description of everything that ratio includes. The ratio includes the case’s survivor reduction and any worker delayed credits, so no further claiming factor may be supplied. Assert nonbinding RIB-LIM/family maximum, no dual entitlement, no earnings-test withholding in the source valuation, and ordinary non-WINDEX scope.

The ss_calculator_worker_birth_year, death_year, optional exact worker birth and death dates, optional authoritative_year, and basis_provenance identify the computation benchmark. Every survivor record must explicitly supply ss_calculator_prior_disability_eligibility: 1 means the worker initially became eligible through disability before death; 0 means no prior eligibility. The default -1 means unspecified and raises ValueError, as does any other value. The pure SurvivorBasis input is prior_disability_eligibility, with True/False for the same answers and None meaning unspecified. Prior eligibility requires an authoritative computation basis. With no prior eligibility, derive E as the earlier of death and age-62 attainment unless an authoritative basis is supplied. January 1 attainment uses the preceding year. A year-only fallback requires year_only_not_january_1; death and age-62 attainment in the same year require exact dates or same_year_death_before_62 (1/0; -1 means unspecified).

COLAs begin with December of the accepted computation benchmark, paid the following January. For a pre-62 death without prior eligibility, this is the death benchmark. Recovery propagates the supplied final-payment interval backward through the composite ratio and every rounded COLA, retaining a half-open eligibility-PIA interval. The lower admissible dime is the point convention; baseline forward computation must reproduce the supplied payment. When reform needs AIME, invert the fixed unreformed PIA scale at that lower endpoint and expose the corresponding AIME interval. Zero stays zero.

The default-false parameter gov.contrib.congress.s770.section_2.recompute_pre2026_death_before_eligibility controls only the 18% first-bend-point increase for pre-2026 deaths before any initial eligibility. This requires both death before age 62 and the explicit answer ss_calculator_prior_disability_eligibility=0. The 95% first factor still applies when false. An accepted authoritative prior-disability benchmark receives both changes regardless of the switch, as do deaths in 2026 or later. S.770 section 2(c)(2)(B) includes initial disability eligibility before 2026. See the recorded modeling ruling and the bill text.

Shared PIA paths and policies

tools.social_security.pia.compute_pia is the common pure monthly service for supplied AIME, recovered AIME and future history callers. Its inputs explicitly separate initial eligibility, formula path, scoring/payment year and cohort vs retroactive applicability. All computations and inverses require E >= 1983. Historical bends back to 1979 are separate parameters, preserving legacy scale values. Future bends use the model’s existing wage-indexed projections.

gov.contrib.ssa.pia contains neutral bend-point multipliers, factors and cohort start, an in_effect opt-in gate, and explicit recompute_existing. No top-factor package schedule is selected. S.770 is separately enabled with gov.contrib.congress.s770.section_2.in_effect and uses original eligibility bend points for older beneficiaries.

Full price indexing requires a frozen cohort real_wage_scale path: cumulative price growth divided by cumulative wage growth from the declared anchor. This scales all formula factors. Progressive indexing requires a frozen maximum-career AIME and PIA target, plus either bend_point_fraction or optional threshold dollar path under gov.contrib.ssa.pia.progressive_price_indexing. The dollar path overrides the fraction. Otherwise the protected threshold is BP1(E) + f * (BP2(E) - BP1(E)). There is no default fraction. Enabling a path without its required frozen inputs fails. Frozen scales, dollar thresholds, maximum AIMEs and targets require explicit January observations for each eligibility cohort; they never silently carry a prior cohort’s data forward. The policy fraction and ordinary factor schedules retain normal dated-policy semantics. Both indexing paths also require their own in_effect switch and start cohort; setting a fraction alone does not activate progressive indexing. Ordinary settings read the eligibility-year snapshot. Explicit older-cohort recomputation reads payment-year settings while retaining original-cohort bend points and frozen indexing inputs. No population percentile or solvency estimate supplies missing values. Scoring must pin price/wage bases, lags, anchor, maximum-taxable career, source hashes and combined-policy order. Composition order is custom bends/factors, S.770, full indexing, progressive protected/maximum-target construction, and final eligibility dime truncation.

gov.contrib.ssa.benefit_levers.cola.pp_change, across_the_board.rate/start_year and payable.share are the shared neutral payment-year parameters reused from #10400. COLA settings also accept an effective year/month, payment start/end year and a supplied alternative rate. The annual person input ss_calculator_withhold_cola accepts an externally resolved E3 decision when cola.withholding_enabled is true. Each withholding decision applies only in its supplied year; an absent year’s decision is false. 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. The COLA means test now supplies these decisions from prior-tax-year MAGI and filing status.

Public source-selector wiring

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. 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

Published fixtures cite SSA Supplement 2023 Appendix D, COLA application, and 2026 earnings-test examples. Historical parameters cite bend points and COLAs. December 1999 retains its original 2.4% as-paid rate until the 2001 correction, then the corrected 2.5% path; special one-time arrears are excluded from recurring gross benefits. Earlier COLA rules are recorded, but E < 1983 routes fail explicitly.