Payroll Deduction / Paystub Breakdown Simulator mechanism

Model scope

The subtraction identity is directionally correct only after each line item has been defined on the correct tax base. Because the specification lacks pay frequency, tax year, W-4 details, state-tax treatment, FICA wage-base handling, rounding policy, and zero-gross behavior, it cannot yet be verified as a standard paycheck-withholding algorithm. The educational-only and rough-estimate labels are appropriate, but the interface should prominently show the tax year, jurisdiction assumptions, annual-versus-pay-period basis, and whether values are illustrative annual tax calculations or official withholding estimates.

• The stated formula is incomplete and underspecified: federal and state withholding cannot be computed from gross pay, filing status, and state alone. Pay frequency, pay-period versus annual basis, W-4 inputs, dependents, additional withholding, and the applicable tax-year tables are required.
• FICA must be itemized into Social Security and Medicare. Social Security requires an annual wage-base cap, while Medicare has an additional-tax threshold for some employees.
• Pre-tax benefits and retirement contributions do not have identical tax treatment. A traditional 401(k) contribution generally reduces federal income-tax wages but not Social Security or Medicare wages; cafeteria-plan benefits may reduce all three, depending on the benefit and plan.
• The formula does not specify whether state tax is based on gross wages, federal taxable wages, state taxable wages, or a state-specific withholding table. State treatment of retirement and benefit deductions varies.
• The formula omits possible local income tax, state disability insurance, paid-leave deductions, garnishments, employer-paid items, credits, and additional Medicare tax.
• The output percent of gross retained requires an explicit zero-gross rule because retained_percent = net/gross is undefined when gross is zero.

Units and conventions

• These test vectors use annual dollars, not a single paycheck period. A production paycheck simulator must explicitly support pay frequency and annualization.
• Gross pay, benefits, retirement contributions, taxes, and net pay are in nominal U.S. dollars.
• Retirement contributions are assumed to be traditional pre-tax contributions for federal income-tax purposes, but they remain subject to Social Security and Medicare tax.
• Pre-tax benefits are assumed to reduce federal taxable wages, Social Security wages, and Medicare wages in these vectors. This is an explicit simplifying assumption, not universal tax law.
• Federal examples use 2024 U.S. federal income-tax brackets and standard deductions, calculated as annual tax rather than official per-pay-period withholding.
• Texas is modeled as having no state individual income tax. Pennsylvania is modeled using its 3.07% personal income-tax rate, with the simplified state tax base stated in the vector.

Inspectable vector

One of 4 source-bound review vectors:

{
  "inputs": {
    "gross_annual": 50000,
    "filing_status": "single",
    "state": "TX",
    "pre_tax_benefits_annual": 1200,
    "retirement_percent": 0.06
  },
  "expected_outputs": {
    "federal_tax_annual": 3512,
    "state_tax_annual": 0,
    "social_security_annual": 3025.6,
    "medicare_annual": 707.6,
    "benefits_annual": 1200,
    "retirement_contribution_annual": 3000,
    "net_annual": 38554.8,
    "percent_of_gross_retained": 77.1096
  },
  "reference_data": {
    "federal_2024_single_standard_deduction": 14600,
    "federal_2024_single_brackets": [
      {
        "up_to": 11600,
        "rate": 0.1
      },
      {
        "up_to": 47150,
        "rate": 0.12
      }
    ],
    "social_security_rate": 0.062,
    "medicare_rate": 0.0145,
    "social_security_2024_wage_base": 168600,
    "texas_individual_income_tax_rate": 0,
    "source_convention": "IRS 2024 tax-year brackets and standard deduction; IRS/SSA 2024 FICA rates and wage base; Texas Comptroller widely tabulated no-individual-income-tax convention"
  },
  "working": "Retirement = 50,000 x 0.06 = 3,000. Federal taxable income = 50,000 - 1,200 - 3,000 - 14,600 = 31,200. Federal tax = (11,600 x 0.10) + ((31,200 - 11,600) x 0.12) = 1,160 + 2,352 = 3,512. FICA wage base = 50,000 - 1,200 = 48,800. Social Security = 48,800 x 0.062 = 3,025.60. Medicare = 48,800 x 0.0145 = 707.60. Texas tax = 50,000 x 0 = 0. Net = 50,000 - 3,512 - 0 - 3,025.60 - 707.60 - 1,200 - 3,000 = 38,554.80. Retained percentage = 38,554.80 / 50,000 x 100 = 77.1096%."
}

Failure boundary

BREAK_CLAIMED · SELF_FLAGGED

The zero-gross boundary produces an undefined retained-percentage calculation, and an invalid state code produces an undefined lookup and therefore undefined net pay. The branch fixture also exposes a discontinuity at its lookup-table switch, while retirement-sign interpretation materially changes the result.

Other records

Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

• VERIFIED_LEDGER.json
• evidence-tranche7/tranche7-results.json
• BOUNDARY_HAZARD_CATALOG.json