Source: https://guthlabs.ai/docs/instruments/payroll-deduction-paystub-breakdown-simulator/
instrument / verified-clean
# Payroll Deduction / Paystub Breakdown Simulator
The current ledger marks this instrument verified clean within the source-bound verification corpus.
Status: **VERIFIED_CLEAN**Lifecycle: **verified-clean**
## Inspectable records
[01**Overview**Purpose and lifecycle]()[02**Mechanism**Method and assumptions]()[03**Implementation**Binding and validation]()[04**Qualification**Evidence and errata]()
## Ledger state
The current ledger marks this instrument verified clean within the source-bound verification corpus.
**Area**: Finance, Economics & Business (educational only — never individualized investment, tax, or legal advice)
**Tranche**: tranche-7
**Evidence ID**: t7-129
**Ledger rows**: 1
No ledger note is attached.
## Review findings
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.
### Formula and scope findings
- 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.
### Unit assumptions
- 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.
## Boundary hardening
**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.
## Errata and corrections
No applied erratum is attached to this unique-name record.
## Inspectable example
4 review vectors are recorded. One source-bound sample is shown below.
````
{
"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%."
}
````
## Related workflows
No source-defined multi-instrument workflow membership is recorded.
## Sources and evidence
These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.
- `VERIFIED_LEDGER.json · VERIFIED_CLEAN`
- `evidence-tranche7/tranche7-results.json`
- `BOUNDARY_HAZARD_CATALOG.json`