Using the API

What it covers

Tax MCP computes only inside a published supported envelope. Everything on this page is generated from the live capability manifest, so you can decide what to send before you send any taxpayer data.

At a glance

JurisdictionTax yearsFiling statusesEndpoint
Federal (Form 1040)2020–2026single, married filing jointly, married filing separately, head of household/tax-compute/federal
California (Form 540)2025single, married filing jointly, married filing separately, head of household/tax-compute/state
New York (IT-201) and NYC resident tax2025single, married filing jointly, married filing separately, head of household/tax-compute/state
Illinois (IL-1040)2020–2026Same as federal/tax-compute/state
North Carolina (D-400)2020–2026Same as federal/tax-compute/state
Michigan (MI-1040)2020–2026Single (incl. federal head of household), married filing jointly, married filing separately/tax-compute/state

A full-year resident of AK, FL, NV, SD, TX, WY, TN, NH or WA gets $0 state income tax or a decline (see the state guide). Illinois: see the Illinois guide; North Carolina: see the North Carolina guide; Michigan: see the Michigan guide. Any other state is rejected with a 400 before anything is computed or billed. For 2026, a federal return with taxable income above $0 and under $100,000 declines (engine_declined) until the IRS publishes the 2026 Tax Table that range requires. From 2026, a return with a refunded additional child tax credit that answers No on Schedule 3-A line 7 or 8 (federalPublicBenefitAffirmed: false) declines (child_tax_credit_needs_review); omitting the field computes as if Yes, with a VERIFY flag.

How to read coverage

Modeled now

Computes when the request carries the documented facts.

Requires caller/preparer inputs

Computes only with a preparer's affirmation, such as a final-net Schedule C. Without it, the case declines. See Declines & affirmations.

Deterministic decline

Outside the envelope: a 200 with a code and reason, never a guessed number.

needs_review

A reconcile found a difference a person must resolve. Not a verdict that either side is wrong.

Not in v1

Full return preparation, filing, and broad document upload-to-compute. Planned work is on the roadmap; planned is not shipped.

Federal: what computes

Open an item to read the manifest's full description of its boundary.

  • ordinary tax
  • NIIT (Form 8960)
  • Additional Medicare (Form 8959)
  • preferential LTCG/QDIV bands
  • QBI §199A — REIT dividends only (qualified REIT dividends as Form 8995 defines them): 20% deduction, never wage/UBIA-limited, capped by the…

    QBI §199A — REIT dividends only (qualified REIT dividends as Form 8995 defines them): 20% deduction, never wage/UBIA-limited, capped by the 20%-of-(taxable-income−net-cap-gain) overall limit (binds → declines). Business / PTP-K-1 / SSTB QBI out of scope.

  • Foreign Tax Credit — §904(j) de-minimis election only: foreignTaxPaid up to $300 ($600 MFJ), compared as whole dollars, with foreignIncomeAllPassive1099,…

    Foreign Tax Credit — §904(j) de-minimis election only: foreignTaxPaid up to $300 ($600 MFJ), compared as whole dollars, with foreignIncomeAllPassive1099, foreignTaxIsFullyCreditableAffirmed and foreignTaxNoForm1116Line12ReductionAffirmed all true (any absent: decline). Above that ceiling the return declines (foreign_tax_credit_needs_review) and a preparer completes Form 1116. The Form 1116 safe harbor that used to compute above the ceiling is switched off.

  • simple itemized slice…

    simple itemized slice — SALT/property tax (OBBBA-2025 cap) + acquisition-debt mortgage interest (§750k limit), greater-of standard; Single/MFJ/HoH (MFS and incomplete mortgage facts decline); plus attested medical, charitable (cash and two non-cash categories), gambling losses and investment interest; itemizing or not, 2025-2026 qualified disaster losses (Form 4684, §63(b)(8)). Not full Schedule A — other categories are out of scope.

  • capital-loss carryover I/O…

    capital-loss carryover I/O — prior-year ST/LT capital-loss carryover (priorYearCapLossCarryoverST/LT, caller-asserted POSITIVE magnitudes) applied with the §1211(b) −$3,000 (−$1,500 MFS) annual limit + ST/LT netting; the ending carryover is returned (endingCapLossCarryoverST/LT). An AMT-only carryover (none left on the regular side) must be sent as priorYearCapLossCarryoverST/LT 0 and declines. ANY Schedule D input on the return ALSO REQUIRES capLossCarryoverNoAmtDifferenceAffirmed:true — presence of any of netShortTermCapGain/netLongTermCapGain/capGainAggregates/collectibles28Gain/sec1250UnrecapturedGain/priorYearCapLossCarryoverST/LT/section1256NetGain, of any sign, including exactly $0. NOT a positive-carryover test: a caller who nets the carryover into netLongTermCapGain before it arrives and supplies no carryover field keeps regular tax CORRECT while Form 6251 line 2k silently loses its adjustment, an executed $10,600 under-tax. Attest EITHER that no carryover exists at all, for regular tax or AMT (the common case) OR that its entering AMT-side amount equals the regular-tax amount; it covers a carryover however it reached the engine, pre-netted included. Note the scalar contract: netShortTermCapGain/netLongTermCapGain are CURRENT-YEAR nets BEFORE any carryover, never Schedule D line 15/16 — supplying a carryover-netted scalar AND the carryover field applies it twice, an executed $12,120 under-tax the engine cannot detect (Form 6251's own "Lines 13, 14, and 15" instruction names a different AMT-side capital-loss carryover as an independent trigger for the AMT-side Schedule D Tax Worksheet this engine does not model). Supplying the affirmation on a return with NO Schedule D input at all is a contradictory orphan affirmation → decline. Pre-netted SCALAR gains — lot-level / Form 8949 detail and covered-basis remain decline on the scalar path (a broker-reported wash-sale disallowance COMPUTES via the capGainAggregates washSaleDisallowed path under its two affirmations — see the wash_sale surface; it cannot be expressed as a pre-netted scalar); the §1250-unrecaptured (25%) and §1(h) 28%-collectibles special-rate portions ARE modeled (every SUPPORTED_TAX_YEARS year with a derivable 24%-ordinary-bracket ceiling — currently all of 2020-2026, verified; see the special-rate surface below) via sec1250UnrecapturedGain / collectibles28Gain; and a §1256-contract net (Form 6781) is modeled via section1256NetGain — TAX YEAR 2025 ONLY (a certification-evidence boundary, not an arithmetic one; other SUPPORTED_TAX_YEARS years decline) — a POSITIVE net AND, C-slice-2b, a net LOSS as the NO-ELECTION default (Form 6781 box D unchecked → the full loss splits 40/60 into the same §1211(b) −$3,000 cap + carryover + the §1411 NIIT base, which the loss reduces ONLY by the capped amount) — ALL require section1256CleanBrokerReportedAffirmed, section1256AggregateIsFinalNoAdjustmentOrDeferralAffirmed (attesting no Form 6781 line-4 adjustment and no QOF deferral upstream of the supplied aggregate), section1256TaxpayerIsNotOptionsOrCommoditiesDealerAffirmed (a registered options/commodities dealer's §1256 gain stays capital but also owes §1401 self-employment tax under §1402(i), which this engine does not compute), AND section1256NotLimitedPartnerDealerEquityOptionAffirmed (a §1256(f)(4) dealer-equity-option gain/loss allocable to a limited partner must be 100% short-term, not the standard 40/60 split, which this engine does not compute), and the LOSS additionally requires section1256LossCurrentlyDeductibleAffirmed (no §1092 straddle-loss deferral — broker box 11 cannot see an offsetting non-§1256 position, deducting a deferred loss now would UNDER-tax — and no §1212(c) carryback election); a §1256 net of exactly ZERO and a capGainAggregates §1256-flagged box still decline — see the special-rate + §1256 surfaces below. Also declines: any §1256 affirmation supplied WITHOUT section1256NetGain, and a §1256 net alongside a special-rate gain (sec1250UnrecapturedGain / collectibles28Gain — that interaction is not independently certified).

  • special-rate capital gain…

    special-rate capital gain — Schedule D Tax Worksheet. The UNRECAPTURED §1250 gain (25% max, Schedule D line 19, sec1250UnrecapturedGain) and the 28%-rate gain (collectibles §408(m) + §1202 taxable portion, Schedule D line 18, collectibles28Gain) — caller-asserted PORTIONS of netLongTermCapGain — are taxed as their own stacked layers ABOVE the 0/15/20 bands, with the line-47 MAX-RATE FLOOR (a low-income filer's §1250 is taxed at their ordinary rate, not a flat 25%). §6694: a real portion omitted from these fields while still included in netLongTermCapGain UNDER-taxes it at 0/15/20, so a preparer must assert it. NOT required to be ≤ netLongTermCapGain: the IRS's own Unrecaptured §1250 Gain Worksheet / 28% Rate Gain Worksheet reduce these figures only by the 28%-rate group's own net loss, the current-year net short-term loss, and long-term capital-loss carryovers — never by an unrelated current-year long-term capital loss, which can legitimately reduce netLongTermCapGain without reducing these figures (a real-estate-plus-stock-loss pattern). The Schedule D Tax Worksheet's own line 12 (min(line 9, line 11)) safely caps the amount actually taxed at 25/28% regardless of how large these fields are relative to netLongTermCapGain — a prior pre-worksheet decline gate encoding a stricter bound was removed as its premise was refuted by primary source. The AMT is refigured with the same special rates (Form 6251 Part III — §1250 at 25%, 28%-collectibles in the 26/28 ordinary AMT base). A binding-AMT special-rate return computes ONLY when specialRateGainNoAmtScheduleDDifferenceAffirmed:true is ALSO supplied (Form 6251's own "Lines 13, 14, and 15" instruction conditions substituting the regular-tax Schedule D Tax Worksheet values into Part III on three statements not applying, most commonly a different AMT basis from pre-1999 §1250 straight-line ADS depreciation; the engine has no AMT-side Schedule D Tax Worksheet field at all, so it declines rather than guess when this affirmation is absent). Modeled for every SUPPORTED_TAX_YEARS year whose ordinary brackets contain a derivable 24%-rate entry — currently all of 2020-2026, verified (a future year lacking one → special_rate_gain_unmodeled decline, fail-closed rather than guessing); scalar netLongTermCapGain path (not capGainAggregates). The PRESENCE of ANY Schedule D input on the return — any of netShortTermCapGain, netLongTermCapGain, capGainAggregates, collectibles28Gain, sec1250UnrecapturedGain, priorYearCapLossCarryoverST, priorYearCapLossCarryoverLT or section1256NetGain, whatever its sign or magnitude, INCLUDING a supplied value of exactly $0 — REQUIRES collectibles28NoSec1202ExclusionPreferenceAffirmed:true — collectibles28Gain conflates §408(m) ordinary-collectibles gain with the §1202 TAXABLE portion of qualified-small-business-stock gain, and only a PRE-2010-09-28-acquired §1202 stock's EXCLUDED gain carries a Form 6251 Line 2h §57(a)(7) AMT preference (7% of the excluded amount; post-2010-09-27 stock is preference-free because §57(a)(7) reaches only stock acquired ON OR BEFORE 2010-09-27 -- Pub. L. 119-21 (OBBBA) §70431(a)(4) struck §1202(a)(4)(C) and wrote that acquisition limit into §57(a)(7) itself, RETROACTIVE to 2010-09-27 under §70431(a)(6)(B) (captioned 'Continued treatment as not item of tax preference'), so amended §57(a)(7) is the operative authority for EVERY supported year, not a TY2026+ rule. The limits are NOT identical: old §1202(a)(4)(C) reached only stock within (a)(4), while amended §57(a)(7) has no upper bound -- which is why the §1202(a)(5) tiers added for stock acquired after 2025-07-04 (50% at 3 years, 75% at 4, 100% at 5) are preference-free too, though NOT 100%-excluded); the engine hardcodes AMT otherPreferences to 0 and does not model the excluded-gain operand, so the affirmation (no §1202 involved at all, OR every §1202 exclusion is post-2010-09-27 stock) fail-closes the alternative. Supplying the affirmation on a return carrying NO Schedule D input at all is a contradictory orphan affirmation → decline, same contract as the §1256 affirmations above.

  • simple passive rental (Schedule E)…

    simple passive rental (Schedule E) — a NON-NEGATIVE scheduleEIncome (final Schedule E line-26 net) COMPUTES into Schedule 1 line 5 → Schedule 1 line 10 → Form 1040 line 8 → AGI AND the §1411 NIIT base, REQUIRING scheduleERentalIsPassiveFinalNet:true (final passive net — post depreciation/§465 at-risk/absorbed §469 suspended losses, no property disposition/§1250 recapture, rental real estate only, no royalties/K-1) AND scheduleERentalNotSection162Business:true (NOT a §162 trade/business → no §199A QBI) AND scheduleERentalNoAmtDifferenceAffirmed:true (attests the post-1986 depreciation AND passive-activity differences are both identical between AMT and regular tax for this activity — this field is SHARED with, not distinct from, the §469(g) disposition-release trigger described below, one attestation per activity per request). A rental LOSS (negative scheduleEIncome) COMPUTES under EITHER of two mutually-exclusive mechanisms, routed by which affirmations are supplied: (1) the §469(i) up-to-$25,000 active-participation allowance (allowance = $25,000 − 50%×(modified-AGI − $100,000), phased to $0 at MAGI ≥ $150k; MAGI = PRE-LOSS AGI over all income; the allowed portion reduces AGI, the excess SUSPENDS as an advisory Form-8582 carryforward; NIIT floors the passive rental at max(0,…) so the loss never reduces the NII base — over-tax-safe) — ONLY with ALL of scheduleERentalActiveParticipationAffirmed + scheduleERentalNoPriorSuspendedPALAffirmed + scheduleERentalAtRiskAffirmed + scheduleERentalNotRealEstateProfessionalAffirmed + ALL THREE of the non-negative-route affirmations (scheduleERentalIsPassiveFinalNet + scheduleERentalNotSection162Business + scheduleERentalNoAmtDifferenceAffirmed — the AMT-parity attestation is REQUIRED on this route), filing status ≠ married_filing_separately, and NO Social Security benefits (a §469-MAGI add-back); OR (2) the IRC §469(g)(1)(A) FULL-DISPOSITION passive-loss RELEASE, routed by asserting ANY ONE of scheduleERentalEntireInterestDisposedAffirmed / scheduleERentalFullyTaxableCashSaleAffirmed / scheduleERentalUnrelatedPartyAffirmed / scheduleERentalDispositionAtRiskAffirmed true — a taxpayer who disposes of their ENTIRE interest in a passive activity in a FULLY TAXABLE transaction (cash sale) to an UNRELATED PARTY gets the current-year loss PLUS ALL PRIOR-YEAR §469-suspended losses from that SAME activity fully deducted, UNCAPPED (no $25k limit, no MAGI phase-out — the loss is no longer characterized as passive), ONLY with ALL FOUR disposition affirmations above PLUS scheduleERentalNotRealEstateProfessionalAffirmed + scheduleERentalNotSection162Business + scheduleERentalDispositionGainReflectedAffirmed (FIVE things: (a) the property was held MORE THAN ONE YEAR — one year or less is not §1231 property, its entire gain/loss is ordinary; (b) combined with EVERY OTHER §1231 property transaction this same year, the annual §1231 netting is a NET GAIN (a net LOSS makes even this disposition's own gain wholly ordinary under §1231(a)(2)), with NO unrecaptured 5-year §1231(c) lookback recharacterizing any part as ordinary; (c) only the disposition's own FINAL RESIDUAL long-term-capital amount after that determination IS reflected in netLongTermCapGain, not omitted; (d) any unrecaptured §1250 gain in that residual is included WITHIN netLongTermCapGain (a subset) AND SEPARATELY declared via sec1250UnrecapturedGain — declaring it only within netLongTermCapGain without the separate declaration under-taxes it at 0/15/20 instead of 25%; AND (e) NO Form 4797/§1231 ordinary gain or loss of any kind exists (recapture, or lookback-recharacterized gain; the YEAR-LEVEL net §1231 loss case is already excluded by (b)'s net-gain requirement, and a DISPOSITION-level loss within a net-gain year is itself a long-term capital loss, not ordinary, and is not excluded by (e)) — the engine has no §1231-netting algorithm, no 5-year-lookback state, and no field for ordinary Form 4797 amounts, NOT wages) + scheduleERentalNoAmtDifferenceAffirmed (the AMT-side §469/§465 figures and disposition gain/loss are IDENTICAL to the regular-tax figures for this activity — this is the PRIMARY AMT safety mechanism; a computed AMT-binding check runs at the pre-release and post-release configurations as an extra, belt-and-suspenders decline, but cannot by itself rule out a cross-track AMT divergence Form 6251's own PAL/at-risk worksheet would reveal), filing status ≠ married_filing_separately. NIIT: rather than unconditionally floor the released loss for the NII base, the engine proves whether the un-modeled Form 8960 same-activity NII deduction (bounded between $0 and the full released amount) COULD change the §1411 tax owed on this specific return (an exact base-invariance test, not a proxy) — computes when provably immaterial, declines otherwise. Any other loss case (MFS, SS present with the §469(i) route, a missing affirmation, a real-estate-professional loss, an installment sale/like-kind exchange/gift/death, a related-party sale, a partial/grouped disposition, a §469(i) loss missing scheduleERentalNoAmtDifferenceAffirmed; a §469(g) release where the engine's OWN computed AMT binds at the pre- or post-release configuration (a deliberately conservative extra decline — a same-track computed check is NOT a proof of AMT safety, since the un-modeled Form 6251 line-2m amount is itself capable of pushing tentative minimum tax above regular tax on a return where this engine computes no AMT at all), or a materially NIIT-sensitive NII/MAGI shape) → schedule_e_needs_review decline, each with its own named reason. QBI is never granted on rental (affirmed absent). All declines are no-tax-number-leakage.

  • self-employment (Schedule C + Schedule SE)…

    self-employment (Schedule C + Schedule SE) — a POSITIVE scheduleCIncome (Schedule C line-31 sole-proprietor net) COMPUTES self-employment tax (§1401/§1402: net × 0.9235 → 12.4% OASDI up to the $176,100 (2025) Social-Security wage base, COORDINATED with the SE earner's W-2 box-3 wages so the OASDI cap is not double-counted, then 2.9% Medicare uncapped) → Schedule 2, PLUS the §164(f) one-half-SE-tax above-the-line deduction (Schedule 1 line 15 → reduces AGI), and the net flows to Schedule 1 line 3 → 1040 line 8 → AGI as ordinary income (NOT the §1411 NIIT base). Net SE earnings are also pulled into Additional Medicare (Form 8959) so a combined wages+SE base over the threshold is surtaxed. The §199A QBI 20% deduction on this income is an OPT-IN via scheduleCQbiEligible (BELOW-THRESHOLD only): 20% × (net − half-SE), capped by 20% × (taxable income − net capital gain) [Form 8995]; the engine DECLINES the at/above-threshold case ($197,300 single/HoH/MFS, $394,600 MFJ, 2025 — Form 8995-A wage/UBIA/SSTB is a preparer surface). REQUIRES scheduleCIsSingleSolePropFinalNetAffirmed:true AND scheduleCNoAmtAdjustmentAffirmed:true whenever scheduleCIncome is EXPLICITLY supplied, INCLUDING exactly $0 (widened from a positive-only trigger, since a $0 regular-tax net can still embed a genuine AMT preference; the SS-wage-coordination gate below is separately exempted at exactly $0) (attesting the net contains NO Form 6251 AMT preference — depletion line 2d, circulation costs line 2o, long-term contracts line 2p, mining exploration/development costs line 2q, R&E costs line 2r, or IDCs line 2t; absent → schedule_c_needs_review, since this engine's AMT computation otherwise passes otherPreferences:0 unconditionally for a computed Schedule C, which is correct ONLY when none of these differ between regular tax and AMT); and, when the return has W-2 wages, socialSecurityWages (the SE earner's box 3) — absent → schedule_c_se_needs_social_security_wages (box-1/box-5 cannot substitute; assuming $0 over-collects OASDI and, via the half-SE deduction, under-taxes a phase-out). A Schedule C LOSS → schedule_c_loss_needs_review. OUT OF SCOPE → schedule_c_needs_review: depreciation/§179/bonus, multiple Schedule Cs, two-spouse SE allocation (the OASDI cap is per-individual), SE health-insurance (§162(l)), home-office (§280A), farm (Schedule F)/clergy/statutory-employee, the §1402 optional methods, and above-threshold / SSTB / wage-limited QBI (Form 8995-A). STATE: CA CONFORMS — a CA return with a Schedule C net taxes it in CA AGI as ordinary income (no CA SE tax, no CA §199A QBI — QBI is below-AGI and never reaches the CA base), requiring TWO CA attestations: caScheduleCSelfEmployedForCaPurposesAffirmed (AB5/ABC worker classification — CA disallows the half-SE for a reclassified employee) AND caScheduleCNoStateBusinessAdjustmentsAffirmed (zero Schedule CA 540 line-3 business-income adjustment — no CA/federal depreciation-§179 difference, no bonus depreciation, no PPP/grant exclusion difference), absent either → decline. NY ALSO CONFORMS — a NY return with a Schedule C net taxes it in NY AGI as ordinary income, requiring nyScheduleCNoStateBusinessAdjustmentsAffirmed (zero Form IT-225 §168(k)-bonus / 2025-R&E / §179-SUV business addition; NY needs no worker-classification affirmation as it has no AB5/§164(f) disallowance), absent → decline (ny_schedule_c_adjustment_needs_review). A VERIFY flag names the separate NY MCTMT (for an individual, reported on Form IT-201 lines 54a–54e; SE earnings in the MCTD over $50k) + NYC UBT (Form NYC-202), which the engine does not compute.

  • fully-taxable pension / annuity / IRA distribution (1040 lines 4b/5b, 1099-R box 2a)…

    fully-taxable pension / annuity / IRA distribution (1040 lines 4b/5b, 1099-R box 2a) — a POSITIVE pensionDistributionTaxable COMPUTES as ORDINARY income → AGI + ordinary tax ALWAYS (NEVER the Additional-Medicare base — not wages; this field is 1099-R-ONLY — §457(f)/§409A nonqualified deferred compensation and a nongovernmental §457(b) plan are reported on Form W-2 for employee participants and on other information returns for nonemployees and beneficiaries of deceased participants, NEVER this field), REQUIRING pensionDistributionFullyTaxableAffirmed:true AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true. WHENEVER pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true (relying on a §72(t)/(q) exception, not age 59½+ specifically) AND pensionDistributionIsNonqualifiedAnnuityNii is NOT explicitly false, ALSO REQUIRES pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmed:true — §72(q)(2)'s exception list for nonqualified annuities is materially SHORTER than §72(t)(2)'s (no IRS-levy exception, among others), so a nonqualified-annuity distribution could otherwise skip the 10% additional tax on an invalid basis; absent → pension_needs_review decline. WHENEVER pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true (REGARDLESS of which specific basis — the engine cannot distinguish age-59½+ from a substantially-equal-periodic-payments (SEPP) basis or any other exception from that single generic field), ALSO REQUIRES pensionDistributionNoSeppModificationRecaptureAffirmed:true — §72(t)(4) (qualified plans/IRAs) and §72(q)(3) (nonqualified annuities) are PARALLEL rules (IRS Notice 2022-6 §2.07): IF the SEPP basis was ever relied upon, a series later modified (a balance addition, partial transfer, or rollover — not only a payment-amount change) before the later of 5 years or age 59½ triggers a recapture tax plus interest this engine does not compute; if no distribution ever relied on SEPP, this affirmation is trivially true; absent → pension_needs_review decline. WHENEVER pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed:true (REGARDLESS of basis), ALSO REQUIRES pensionDistributionEarlyWithdrawalBasisIsAvailableForThisPlanTypeAffirmed:true — 26 U.S.C. §72(t)(2)/(3)/(10) contains MANY plan-type-restricted exceptions (§72(t)(2) has further plan-type-restricted bases including reservist distributions (§72(t)(2)(G), uncapped), birth/adoption and emergency-personal-expense (§72(t)(2)(H)/(I), excluded from a defined benefit plan), domestic abuse (§72(t)(2)(K), excluded from a DB plan or a §§401(a)(11)/417 QJSA plan), ESOP stock dividends (§404(k)), federal phased-retirement annuities, §408(d)(4) IRA-only withdrawals, §402A(e) pension-linked emergency savings accounts, and §401(a)(39) long-term-care distributions effective for distributions after 2025-12-29) — the caller must independently verify plan-type eligibility for WHATEVER basis is claimed; these plan-type restrictions cut BOTH ways and two of them were published REVERSED until 2026-09-09 (certify-leaf round 6 on fix-simple-ira-early-distribution-prose; direction: UNDER-tax, because a caller who believed an exception applied to an IRA would affirm one they do not have). Corrected against the 2025 Instructions for Form 5329, fetched raw: separation-at-55 (exception 01) and QDRO (exception 06) are QUALIFIED-PLAN bases and each is annotated "doesn't apply to IRAs" -- they are NOT available to an IRA or SIMPLE-IRA holder; whereas unemployed-health-insurance (07), higher-education (08) and first-home (09) ARE IRA-only, each written "IRA distributions made ...". Post-separation SEPP is separately restricted (see the round-12 note below). The qualified-HSA-funding distribution is unavailable from a SEP or SIMPLE IRA — both plan types, per §408(d)(9)(B), which defines the term as a distribution from an IRA 'other than a plan described in subsection (k) or (p)'; IRS Notice 2008-51 and Pub. 969 narrow that bar to an ONGOING such plan, and an unsubstantiated ongoing status should be treated as ongoing. FEDERALLY §408(d)(9)(A) excludes it from gross income, so it is not a fully-taxable 1040 line-5b amount. This text does NOT summarize the rest of §408(d)(9): the §408(d)(9)(C) dollar cap and one-time-transfer rule, and the §408(d)(9)(D) testing-period recapture with its own (ii) death/disability exception. Read §408(d)(9) in full rather than relying on a one-sentence compression of it. CALIFORNIA DOES NOT CONFORM, and carrying the federal treatment across is an UNDER-tax: R&TC §17215.4 conforms IRC §223 out of California entirely, and per the FTB 3805P instructions 'any distribution from an IRA to an HSA must be added to adjusted gross income (AGI) on the taxpayer's California return and would be subject to a 2 1/2% additional tax under the rules for premature distributions under IRC Section 72' — owed even where NO federal §72(t) tax is. This engine models NEITHER the federal exclusion NOR the CA add-back. These few are a non-exhaustive teaching aid, not a checklist; THERE IS NO SHORTCUT: the OUTCOME CONDITION BELOW GOVERNS and is the only thing that discharges this affirmation. Neither a nonqualified annuity NOR an age-59½/death/disability/levy basis discharges it on its own. In particular neither discharges §72(m)(5), which reaches a 5-percent owner's excess-over-plan-formula amounts AT ANY TIME with no age, death, disability or levy exception and is reported on Schedule 2 line 17j, not Form 5329 Part I). IT IS NOT TRIVIALLY TRUE MERELY BECAUSE A DISTRIBUTION IS OUTSIDE §72(t): a §7702A MODIFIED ENDOWMENT CONTRACT is outside §72(t) AND §72(q) and still owes §72(v)(1)'s 10%, whose §72(v)(2) exception list is only age 59½, disability and SEPP — NO death and NO levy exception, per Form 5329 Exception 04. §72(m)(5) is a further such regime. The affirmation is keyed on the OUTCOME: affirm only if no FEDERAL CHAPTER 1 additional tax on this distribution is owed, whichever form reports it (Form 5329 Part I for §72(t)/(q)/(v); Schedule 2 for §72(m)(5)). The §1411 NII tax and state analogues are OUT OF SCOPE here — they are handled by pensionDistributionIsNonqualifiedAnnuityNii and by their own state surfaces. (the generic SEPP basis is NOT trivially true for an employer qualified plan — §72(t)(3)(B) requires the series begin post-separation, no IRA analogue); absent → pension_needs_review decline. NOT modeled (a deliberate over-decline, not a §6694 exposure): a real plan-to-plan transfer/rollover (§72(t)(4)(C)) or §1035 exchange (§72(q)(3)(B)) safe harbor added by SECURE 2.0 — this engine cannot verify either safe harbor's own precondition (combined distributions still satisfying the SEPP schedule), so it declines rather than risk a caller misjudging that test; see the field's own OpenAPI/schema doc-comment for the full citation. §1411 NIIT status is a SEPARATE whole-scalar affirmation, pensionDistributionIsNonqualifiedAnnuityNii: false (or a return whose MAGI/NII shape makes the classification immaterial) keeps it OUT of the §1411 NIIT base (a qualified-plan distribution under §401(a)/403(a)/403(b)/408/408A/457(b), IRC §1411(c)(5)); A §7702A MODIFIED ENDOWMENT CONTRACT HAS NO TRUTHFUL POLE on this field and must be left ABSENT — it is life insurance, so it is neither a nonqualified commercial annuity nor a qualified-plan distribution, and it reaches this engine legitimately as a 1099-R box 7 code D; absent is fail-closed, declining wherever the classification would change the NIIT owed. Whether a MEC distribution belongs in the §1411 NII base is NOT asserted either way. true puts the FULL amount IN the NIIT base (a nonqualified commercial annuity — annuities are explicitly named net investment income under §1411(c)(1)(A)(i)); absent AND material (MAGI over the filing-status NIIT threshold with the classification actually changing the NIIT owed) → pension_needs_review decline (exact base-invariance test, not a MAGI-threshold proxy — a return where other NII already saturates the MAGI excess computes even unaffirmed). SEPARATELY, on the /state (NY) endpoint this field is required UNCONDITIONALLY whenever nyPrivatePensionQualifiesFor20kExclusion:true is claimed on a positive pension — NY's own $20,000 exclusion has its own negative list excluding a nonqualified commercial annuity, independent of federal NIIT materiality (ny_private_pension_exclusion_classification_needed decline). The same NY endpoint ALSO requires nyPrivatePensionIsEntirelyRecipientsOwnNotInheritedAffirmed whenever the line-29 exclusion is claimed — IT-201-I's line-29 'Beneficiaries' rule gives an inherited pension a different, decedent-keyed entitlement this engine does not model; absent → ny_private_pension_beneficiary_classification_needed, affirmed false → ny_private_pension_beneficiary_allocation_unsupported. NOT modeled (a caller must NOT affirm the base pension affirmations → pension_needs_review decline): box-2b 'taxable amount not determined', basis/after-tax contributions, QCD, rollover, Roth conversion, NUA, and the early-distribution additional tax (Form 5329 10%/25%, or its CA analogue FTB 3805P — CA's rate is 2.5% under R&TC §17085(c)(1), raised to 6% where §72(t)(6) applies per §17085(c)(2), and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax). NY EXCLUDES the pension on the state return (iteration 30 — IT-201 line 26 govt full / line 29 private $20k@59½; see the ny jurisdiction block below) — asserting pensionDistributionIsNonqualifiedAnnuityNii:true together with either NY pension-classification affirmation is a flat contradiction → decline (pension_exclusion_classification_ambiguous). CA CONFORMS to federal pension taxation by default — a CA pension return COMPUTES and TAXES the pension in CA AGI. ONE MODELED DIVERGENCE: caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true excludes min($20,000, line 5b) as uniformed-services retirement pay / a DoD Survivor Benefit Plan annuity (R&TC §§17132.9/17132.10), GATED on federal AGI — a HARD CLIFF, not a phase-out — at ≤$250,000 for married_filing_jointly or ≤$125,000 for every other filing status; absent/false → $0 excluded (not a decline). caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true is a flat contradiction with pensionDistributionIsNonqualifiedAnnuityNii:true (a self-funded commercial annuity cannot also be federal uniformed-services retired pay) → decline (ca_pension_exclusion_classification_ambiguous). A VERIFY flag (CA-PENSION-TAXED-CONFORMING) names this and the unmodeled CA divergences enumerated in CA_COMPUTE_CAPABILITY.state_adjustments.pension (served on GET /api/mcp/tax-compute/state), which is the single authoritative list — this text states no count of its own, because a count restated in many places is a claim that must be maintained in many places, and on this surface it was not. Nor does it restate the list: a pointer carrying its own partial copy is how a stale two-item enumeration survived beside a correct three-item one.

  • Social Security benefit taxation (§86 worksheet → 1040 line 6b)…

    Social Security benefit taxation (§86 worksheet → 1040 line 6b) — a POSITIVE socialSecurityBenefits (SSA-1099 box 5 gross) COMPUTES the TAXABLE portion (0/50/85% tiers by provisional income = other AGI + tax-exempt interest + ½ benefits; base $25k single / $32k MFJ / $0 MFS-lived-with-spouse, adjusted $34k / $44k) as ORDINARY income → AGI + ordinary tax ONLY (NOT the §1411 NIIT or Additional-Medicare base). REQUIRES socialSecurityStandardCaseAffirmed:true AND taxExemptInterest supplied — a positive value also requires taxExemptInterestNoPrivateActivityBonds:true (line 2a may include PAB interest, an AMT preference the engine does not model) — AND, for MFS, socialSecurityMfsLivedWithSpouse. NOT modeled (→ social_security_needs_review decline): §86(e) lump-sum election, negative box 5 (repayment/§1341, schema-rejected), foreign/totalization SS, railroad RRB-1099 Tier-1, a §911, §931, §933, §135, §137 or §85(c) exclusion on the return. CA/NY fully EXCLUDE the taxable Social Security on the state return (Schedule CA (540) line 6 col B / IT-201 line 27; see the ca/ny jurisdiction blocks below).

  • underpayment-of-estimated-tax penalty…

    underpayment-of-estimated-tax penalty — Form 2210 SAFE-HARBOR determination (IRC §6654). OPT-IN via priorYearTax: the response carries underpaymentPenalty naming the exemption that zeroes the penalty with certainty — §6654(e)(1) $1,000 de-minimis (current tax − withholding < $1,000), §6654(d)(1)(B) withholding ≥ the required annual payment = min(90% of current tax, safe-harbor% × prior-year tax) where safe-harbor% is 110% if prior AGI > $150k/$75k-MFS else 100% and the prior-year harbor needs a full 12-month prior return, or §6654(e)(2) prior-year tax $0 on a 12-month return AND the taxpayer was a US citizen/resident throughout the prior year (§6654(e)(2)(C)). When none holds → status:needs_preparer (a penalty MAY be owed). In that case the response ALSO carries an advisory penaltyCeiling — a conservative UPPER BOUND on the §6654 penalty computed under the taxpayer-least-favorable assumptions (single maximum quarterly rate, full accrual to the April 15 due date, no estimated payments); it is guaranteed ≥ the true penalty and is explicitly NOT a Form 1040 line-38 filed value (the exact per-installment amount is a preparer task). The ceiling is emitted only for a tax year whose IRS underpayment rates are fully published (fail-closed otherwise). Withholding is treated as paid evenly (§6654(g)); withholding base = federal + Additional-Medicare withholding. It is a SEPARATE line and does not change tax/AGI/refund. Federal only.

  • Child Tax Credit + Credit for Other Dependents (Schedule 8812 Part I, NON-refundable)…

    Child Tax Credit + Credit for Other Dependents (Schedule 8812 Part I, NON-refundable). qualifyingChildrenForCtc × the year's per-child amount ($2,000; $2,200 from 2025) + otherDependentsForOdc × $500 (a 2021 count of either declines), phased out 5% of AGI-over-$400k-MFJ/$200k-others (excess rounded UP to the next $1,000), then limited to tax liability → reduces 1040 line 22. REQUIRES TWO independent affirmations per credit: childTaxCreditChildrenQualifyAffirmed / otherDependentsQualifyForOdcAffirmed (the CHILD/DEPENDENT's own eligibility — valid SSN/TIN by due date, dependency, residency, support, age-under-17 — engine-invisible), AND, separately, the filer-level ID affirmation (the filer's, and if MFJ the spouse's, SSN or ITIN by the due date: odcFilerAndSpouseValidTinAffirmed; from 2025 the CTC/ACTC needs a valid SSN for the filer, or on a joint return one spouse: ctcActcFilerAndSpouseValidSsnAffirmed). Over-claim under-taxes → a positive count missing EITHER affirmation declines child_tax_credit_needs_review. The REFUNDABLE Additional Child Tax Credit (ACTC, Schedule 8812 Part II) is ALSO modeled (from 2026 subject to Schedule 3-A: federalPublicBenefitAffirmed): unused CTC → refund, capped at min(unused CTC, qualifying-children × the year's refundable per-child cap ($1,400 in 2020 to $1,700 from 2024), 15% × (earned income − $2,500)); earned income (Schedule 8812 line 18a, the Earned Income Worksheet) = W-2 wages PLUS net self-employment earnings (Schedule C line 31) MINUS one-half self-employment tax — a retiree/investment-only filer with $0 earned income gets $0 ACTC; it lands in owedOrRefund (line 28, refundable — can make owed negative). For 3+ children where the 15%-earned-income formula is the binding constraint, Schedule 8812 Part II-B (the withheld-Social-Security/Medicare-tax alternate, which may yield MORE) is NOT modeled — rather than return a possibly-too-low refund as final, the WHOLE RETURN declines child_tax_credit_needs_review. Federal only — the CA exemption credit + NY Empire State Child Credit use their own dependent inputs.

  • premium tax credit (Form 8962 Parts I-III, one Form 1095-A), 2020 and 2022-2025 only (2020 repays no excess advance payment, ARPA §9662): form8962Required:true…

    premium tax credit (Form 8962 Parts I-III, one Form 1095-A), 2020 and 2022-2025 only (2020 repays no excess advance payment, ARPA §9662): form8962Required:true with premiumTaxCredit figures line 2a from this return (Worksheet 1-1), adds the excess advance payment repayment to tax before credits (a binding AMT or the nonrefundable credits can absorb it) and subtracts the net credit in owedOrRefund; the response's premiumTaxCredit carries lines 3 and 5, the repayment and the net credit. Other cases decline premium_tax_credit_needs_review, naming the reason.

  • Schedule D / Form 8949 lot/evidence contract v0 (capGainAggregates)…

    Schedule D / Form 8949 lot/evidence contract v0 (capGainAggregates) — per-box 1099-B aggregates or individual lots ({broker, form8949Box A–L (or legacy boxType A/B/D/E), proceeds, reportedBasis}) netted by the engine into ST/LT, across MULTIPLE brokers, feeding the same §1211(b) cap + carryover worksheet. COMPUTES only a COVERED NON-DIGITAL (A/D) box/lot with a positive reportedBasis, NO adjustment code / correctedBasis / lot-linkage (a broker-reported washSaleDisallowed amount NOW computes NARROWLY under its own TWO affirmations — see the wash_sale entry; every other wash shape still declines), an active non-conflicting source with a COMPLETE corrected-version lineage (sourceDocumentRef.correctionWithoutObservedOriginal:true — the doc's dedupe advisory carries correction_without_observed_original, i.e. a CORRECTED form whose original was never observed — declines for mandatory review; ABSENCE of that field is NOT an attestation the original was observed, it means the advisory was not consulted — that consultation is the preparer's §6694 obligation; distinct from correctedConflict, where two corrected versions conflict), dates consistent with the box term, AND — REQUIRED — cleanCoveredNoAdjustmentsAffirmed:true. That affirmation attests the box is uniformly clean covered, correctly classified, AND that NO wash sale is disallowed ACROSS ANY ACCOUNT, SPOUSE OR CORPORATION THE TAXPAYER CONTROLS (Pub 550) for any lot (a per-1099 'no code W' is NOT sufficient — a cross-broker/cross-spouse §1091 wash shows no code W on either 1099-B; the preparer bears that cross-account §6694 obligation). ANY other input (noncovered B/E, no-1099 C/F, digital G–L, an adjustment code, a corrected basis, a same-scope box↔lot mix, a date-vs-term mismatch, a superseded/duplicate source, or a missing affirmation) → WHOLE-RETURN decline, no tax-number leakage. Mutually exclusive with the pre-netted scalars. Lot-level dates/holding-period and equity-comp $0-basis (without the equity-comp affirmation chain) remain out of scope (decline); a broker-reported wash-sale disallowance COMPUTES NARROWLY via washSaleDisallowed + its two affirmations (see the wash_sale surface — every other wash shape still declines). Tag an equity-comp sale with equityCompType (RSU/ESPP/ISO/NSO): a COVERED (A/D) RSU, NSO, ESPP, or ISO (disqualifying disposition only) LOT (granularity:'lot' is REQUIRED — a granularity:'box' aggregate, the default, ALWAYS declines for equity-comp, since a box can aggregate many lots with different acquisition/sale dates and a single date pair can't honestly represent it) COMPUTES a comp-adjusted-basis gain when the preparer supplies equityCompOrdinaryIncome (the W-2/1099-NEC ordinary income already taxed at vest/exercise/disposition) AND affirms equityCompBasisIsCompAdjustedAffirmed:true — the engine adds that comp back to the reported basis (basis = reportedBasis + equityCompOrdinaryIncome; the 1099-B routinely reports a $0/uncorrected basis that would double-tax the comp) and nets it through the same covered-equity path (§1211(b) + §1(h) 0/15/20 + §1411 NIIT), with a loud VERIFY flag that the comp-adjusted basis is preparer-attested, not IRS-reported (the §6694 responsibility is the preparer's; the engine only enforces equityCompOrdinaryIncome ≥ 0 so the correction never LOWERS the reported basis). An ISO lot ALSO REQUIRES equityCompIsoDisqualifyingDispositionAffirmed:true AND acquiredDate/soldDate in the SAME CALENDAR YEAR (fail-closed — the engine never assumes disqualifying, and an affirmed-true CONTRADICTED by cross-year dates still declines): a same-year exercise(acquiredDate)-and-sale(soldDate) is PROVABLY disqualifying under §422(a)(1) regardless of grant date (the max intra-year gap, 365 days, can never satisfy either qualifying leg), so it is the ONLY ISO disqualifying-disposition shape the engine computes — a cross-year exercise/sale needs Form 6251 line-2k remeasurement, which the engine does not model, and a QUALIFYING ISO disposition is out of scope entirely (see below). ESPP computes for EITHER a qualifying or disqualifying §423 disposition WITHOUT the ISO-specific acquiredDate/soldDate same-year constraint (the soldDate-in-tax-year rule above still applies to every equity-comp lot including ESPP; the caller-attested equityCompOrdinaryIncome covers whichever figure applies — the engine does not derive the §423 'lesser-of' itself — and ESPP triggers no AMT preference either way, so no ISO-style same-year gate applies to it; RSU/NSO also have no same-year constraint, since neither has a qualifying/disqualifying classification risk). An equity-comp lot ALSO REQUIRES (else declines): acquiredDate + soldDate as EXACT ISO yyyy-mm-dd calendar dates (not 'VARIOUS' or any other non-lot convention), soldDate strictly AFTER acquiredDate, soldDate in the SAME calendar year as the return's tax year (a lot sold in a different year doesn't belong on this return — acquiredDate MAY be a prior year for RSU/NSO/ESPP, e.g. a normal vest-then-sell-later shape), and holding-period evidence consistent with the box term (a short-term sale asserted long would be under-taxed); a sourceDocumentRef (the broker 1099-B lot provenance); an ordinaryIncomeSourceRef (a TYPED reference — stock_plan_supplement / w2_employer_stock_plan_record / form_1099_nec / taxpayer_record — substantiating the equityCompOrdinaryIncome amount SPECIFICALLY, with an ACTIVE status; superseded/draft = conflicting source support → decline; and a COMPLETE corrected-version lineage — ordinaryIncomeSourceRef.correctionWithoutObservedOriginal:true, the comp record's dedupe advisory carrying correction_without_observed_original, declines the whole return for mandatory review BEFORE any comp-basis compute, because the comp amount RAISES basis and an over-stated comp element under-states the gain; ABSENCE of that field is NOT an attestation the original was observed — it means the advisory was not consulted, the preparer's §6694 obligation); and the comp-adjusted basis MUST NOT create/increase a LOSS (a comp adjustment only reduces a gain toward zero; a comp-created loss — a fabricated-loss / §1091 wash-sale risk — declines to a preparer). NOT modeled and NOT implied by any of the above: broad equity-comp completeness, a caller-free derivation of the §422(c)(2) cap or the §423 'lesser-of' figure, filing, live, deploy, or real-data support — every figure remains preparer-attested and every gap declines rather than guesses. A COMPUTED equity-comp return exposes the ENGINE-DERIVED correction per lot (response field equityCompDerivation): Form 8949 code-B POSTURE — col (e) keeps the broker-reported basis, col (f) = code B, col (g) = basisAdjustmentAmount (NEGATIVE: roundedReportedBasis − derivedCorrectedBasis, i.e. −the comp element after round-once); derivedCorrectedBasis = round(reportedBasis + equityCompOrdinaryIncome) is the engine's INTERNAL basis operand, NOT a col-(e) entry (transcribing it into col (e) AND applying col (g) would double-count); identities: gain = roundedProceeds − derivedCorrectedBasis = roundedProceeds − roundedReportedBasis + basisAdjustmentAmount. The caller must NOT set an adjustmentCode — the engine applies the code-B-equivalent correction internally. A COMPUTED ISO-disqualifying lot ALSO carries an ISO-DISQUALIFYING-DISPOSITION VERIFY flag naming the §422(c)(2) cap: if the disposition is AT A LOSS relative to the exercise-date FMV, ordinary income is capped at the actual gain (amount realized − strike price), never the full bargain element — caller-attested, not engine-verified. NOT modeled (still decline, equity_comp_basis_adjustment_needs_review): a QUALIFYING ISO disposition (no ordinary income for regular tax, but the AMT-side basis can differ from the regular-tax basis — a Form 6251 §56(b)(3) exercise-year-preference adjustment the engine does not model; computing it as a plain capital gain would silently mis-state AMT); a CROSS-YEAR ISO exercise/sale (the engine CANNOT determine from dates alone whether this is qualifying or disqualifying — grant date is unknown to it, so being cross-year is not itself a disqualifying signal, only the complement of the one window the engine CAN prove; either classification declines: a qualifying disposition has no ordinary income but an AMT-side basis divergence the engine does not model, and a DISQUALIFYING cross-year disposition DOES carry real §421(b) ordinary income but requires tracking the exercise-year Form 6251 line-2k AMT preference and its disposition-year reversal, prior-year AMT facts this engine does not carry); ISO exercise-and-hold (no disposition — this lot shape has no path to express it, `proceeds` is a required field); and any lot missing the affirmation/equityCompOrdinaryIncome/dates/sourceDocumentRef/ordinaryIncomeSourceRef, on a noncovered box, creating a loss, or carrying any dirty flag (wash/adjustment/date-mismatch) — all no tax-number leakage. Tag a §1256 contract with sec1256:true → a §1256-specific decline (section_1256_needs_review) FROM THE BOX PATH; to COMPUTE §1256 (tax year 2025 only, not alongside a special-rate gain) supply the affirmed aggregate via section1256NetGain (a positive net, or a net LOSS under the additional section1256LossCurrentlyDeductibleAffirmed — the no-election default) with section1256CleanBrokerReportedAffirmed, section1256AggregateIsFinalNoAdjustmentOrDeferralAffirmed, section1256TaxpayerIsNotOptionsOrCommoditiesDealerAffirmed, AND section1256NotLimitedPartnerDealerEquityOptionAffirmed, which the box path can't attest clean of §475(f) mark-to-market / straddles / loss-carryback / line-4 or QOF adjustment / dealer status / limited-partner dealer-equity-option status. Tag a crypto disposition with digitalAsset:true → a TY2026+ COVERED (box A/D, IRS-reported basis) crypto box whose units were ALL acquired by purchase AND are NOT collectibles AND are CAPITAL-not-ordinary (digitalAssetAllAcquiredByPurchase:true + digitalAssetNoneAreCollectible:true + digitalAssetIsCapitalNotOrdinary:true) COMPUTES proceeds−basis via the same covered-equity netting path (feeds §1211(b) + §1411 NIIT + §1(h) 0/15/20 LT bands); every other crypto box — pre-2026 (2025 1099-DA is proceeds-only, basis not IRS-reported), a noncovered B/E box, a missing affirmation (purchase or non-collectible), or a wash-flagged box — → digital_asset_needs_review decline. §1091 wash-sale does not apply to crypto (property) other than a tokenized security, which is not modeled; staking/mining/airdrop receipt is separately ordinary income at FMV (Rev. Rul. 2023-14), invisible to a disposition compute, which is why the purchase-only affirmation gates it; a §408(m) collectible NFT (Notice 2023-27) is taxed at 28% not 0/15/20, which the non-collectible affirmation gates; dealer/inventory/§988/Box-6 crypto is ORDINARY not capital (§1221, Notice 2014-21), which the capital-not-ordinary affirmation gates. Crypto affirmations require a tagged capGainAggregates digitalAsset box (rejected on scalar cap-gain inputs).

California

  • exact-rate schedule (all statuses)
  • Behavioral Health Services Tax (+1% > $1M)
  • exemption phase-out
  • single-status tax table
  • clean state-conforming non-wage income (taxable interest, ordinary/qualified dividends, net capital gain) taxed at ORDINARY CA brackets…

    clean state-conforming non-wage income (taxable interest, ordinary/qualified dividends, net capital gain) taxed at ORDINARY CA brackets — requires stateIncomeConformsToFederal:true

  • Form 540 line 18 deduction = greater-of(CA standard deduction, caller-asserted caItemizedDeductions)…

    Form 540 line 18 deduction = greater-of(CA standard deduction, caller-asserted caItemizedDeductions). caItemizedDeductions is the FINAL Schedule CA 540 Part II line 30 — AFTER the CA state-income-tax disallowance AND the high-income itemized-reduction worksheet — NOT the federal Schedule A total (over-asserting UNDER-taxes). REQUIRES itemizedDeductionsAreFinalStateAmount:true (a §6694 affirmation; absent → the itemized amount fail-closed declines); MFS + itemized declines (§63(c)(6)(A) spouse-itemizes election). The engine consumes it (like a W-2 box), does not derive it; a VERIFY flag also surfaces the contract.

  • Schedule CA (540) Part I line 2 col B…

    Schedule CA (540) Part I line 2 col B — US-government-obligation interest SUBTRACTION (R&TC §17143; US-Treasury interest is federally taxable but CA-exempt). caUsObligationInterestSubtraction is a caller-asserted amount of the DIRECT US-obligation interest included in federal taxable interest (1040 line 2b), subtracted from CA AGI ONLY (never federal AGI → the exemption phase-out is untouched). REQUIRES caUsObligationInterestAffirmed:true, and is CAPPED at the supplied taxableInterest (exceeds → declines). SCOPE: direct US-obligation interest only — a RIC/§17145 fund distribution (1099-DIV/line 3b) is out of scope for THIS field (use caUsObligationRicDividendSubtraction). A subtraction over-claimed UNDER-taxes, so it fails closed without the attestation.

  • Schedule CA (540) Part I line 2 col B…

    Schedule CA (540) Part I line 2 col B — RIC/mutual-fund US-government-obligation DIVIDEND subtraction (R&TC §17145). caUsObligationRicDividendSubtraction is the caller-asserted US-obligation-interest PORTION of a RIC/mutual-fund ORDINARY dividend (1099-DIV box 1a / 1040 line 3b), for a fund holding ≥50% US-obligation assets AT EACH QUARTER-END, subtracted from CA AGI ONLY (never federal AGI). REQUIRES the TWO-PART caUsObligationRicDividendAffirmed:true (amount per the fund's WRITTEN shareholder statement AND the fund MET the 50%-asset test), and is CAPPED at non-qualified ordinary dividends (ordinaryDividends − qualifiedDividends; US-obligation interest is never a qualified dividend). The 50%-asset test is a CLIFF — below 50%, NONE is CA-exempt (do NOT supply; prorating a sub-50% fund UNDER-taxes by the whole amount). A subtraction over-claimed UNDER-taxes, so it fails closed without the attestation.

  • Schedule CA (540) Part I line 2 col C…

    Schedule CA (540) Part I line 2 col C — out-of-state exempt-interest-dividend ADDITION. caOutOfStateMuniInterestAddition is the caller-asserted CA-taxable portion of box-12 exempt-interest dividends / tax-exempt interest from NON-California municipal obligations (federally tax-exempt, never in federal AGI, but CA-taxable), ADDED to CA AGI ONLY (never federal AGI → the exemption phase-out is untouched). REQUIRES caOutOfStateMuniInterestAffirmed:true (the SOLE guard — exempt-interest dividends have no engine-visible cap). CA munis AND US-territory munis (PR/Guam/USVI) stay CA-exempt and are EXCLUDED, BUT California's 50%-asset test makes the ENTIRE fund dividend CA-taxable (incl. the CA portion) when the fund holds <50% CA/US-territory/US-obligation assets. NOT conformity-gated (a wages-only filer may supply it). An ADDITION is over-tax-safe; absent the affirmation it fails closed.

  • Schedule CA (540) Part I line 6 col B…

    Schedule CA (540) Part I line 6 col B — U.S. Social Security benefits, FULLY EXCLUDED. CA does not tax Social Security; the engine recomputes the federal §86 taxable portion (1040 line 6b) in-process from socialSecurityBenefits and SUBTRACTS exactly that amount from CA AGI ONLY (never federal AGI → the exemption-credit phase-out, defined on federal AGI, correctly stays SS-inclusive). DERIVED not caller-asserted → the cap is built in (subtracts exactly what was federally included; federal 6b=$0 → $0). REQUIRES the SAME §86 gates as the federal endpoint (socialSecurityStandardCaseAffirmed:true; socialSecurityMfsLivedWithSpouse for MFS) — an unaffirmed SS return declines federally → declines CA. Tax-exempt interest (line 2a) is accepted as a §86 operand but any positive amount DECLINES (state_tax_exempt_interest_unsupported — the Schedule CA line 2 col C out-of-state-muni add-back is not sized in this slice).

  • Federal pension/IRA (1040 lines 4b/5b)…

    Federal pension/IRA (1040 lines 4b/5b) — CA CONFORMS and TAXES it by default. A fully-taxable pension stays in CA AGI and is taxed as ordinary income (Schedule CA 540 line 5a/5b: 'generally no adjustments'). Requires BOTH pensionDistributionFullyTaxableAffirmed AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed (this second gate, its conditional pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmed requirement per fed-pension-5b-72q-levy-exception-fix above, and its pensionDistributionNoSeppModificationRecaptureAffirmed requirement per fed-pension-5b-sepp-modification-recapture-gate above, fire on the shared federal recompute this state engine calls — no separate CA-side code). ONE MODELED DIVERGENCE: caPensionIsUniformedServicesRetiredPayOrDodSbpAffirmed:true excludes min($20,000, line 5b), AGI-gated (R&TC §§17132.9/17132.10, tax years 2025-2029 — this engine only computes CA for 2025, so no separate year gate is needed) — a HARD CLIFF at federal AGI ≤$125,000 single/HOH/MFS or ≤$250,000 MFJ, confirmed against the actual R&TC section text (not just the FTB instructions summary); a flat contradiction with pensionDistributionIsNonqualifiedAnnuityNii:true declines (ca_pension_exclusion_classification_ambiguous). A VERIFY flag (CA-PENSION-TAXED-CONFORMING) fires on every CA pension return naming this and the unmodeled CA divergences enumerated in CA_COMPUTE_CAPABILITY.state_adjustments.pension (served on GET /api/mcp/tax-compute/state), which is the single authoritative list — this text states no count of its own, because a count restated in many places is a claim that must be maintained in many places, and on this surface it was not. (1) On the INCOME side: Tier-2 RAILROAD retirement (RRB-1099-R), which CA EXCLUDES (45 U.S.C. §231m) — either omitted income-side case OVER-taxes the retiree, so a preparer must subtract the applicable amount on Schedule CA 540. (2) On the ADDITIONAL tax rather than the income side, which this engine computes for NEITHER jurisdiction: California's early-distribution additional tax is 2.5% (R&TC §17085(c)(1)), raised to 6% where §72(t)(6) applies — a SIMPLE-IRA distribution within the 2-year period beginning when the taxpayer FIRST PARTICIPATED (§17085(c)(2), FTB 3805P line 4) — and per the 2025 FTB 3805P instructions California 'does not conform to all of the federal exceptions to the additional tax on early distributions', so a federally-valid §72(t) exception does NOT guarantee $0 of CA additional tax; a preparer must complete FTB 3805P by hand. Omitting THIS one UNDER-taxes, the severe direction. (3) A THIRD divergence, on the INCOME side and running the OPPOSITE way from (1): an IRA-to-HSA one-time funding distribution under §408(d)(9) is EXCLUDED from federal gross income under §408(d)(9)(A), but CA conforms IRC §223 out (R&TC §17215.4) and the FTB 3805P instructions require it ADDED BACK to CA AGI, and — where the distribution is premature under the §72(t) rules — a 2 1/2% additional tax, which can be owed even where no federal §72(t) tax is. Omitting THAT one UNDER-taxes California too, and this engine does not compute it: a CA return with pensionDistributionTaxable declines unless caNoIraToHsaFundingDistributionAffirmed is true, and with no pension field it is not detected, so such a return must not be filed from this output without adding it back by hand. A CA return with pensionDistributionTaxable also requires caPensionNoEarlyDistributionAdditionalTaxAffirmed (no R&TC §17085 additional tax) and caNoIraToHsaFundingDistributionAffirmed (no IRA-to-HSA funding distribution); either absent declines (ca_early_distribution_additional_tax_unmodeled). Not detected: an IRA-to-HSA funding distribution on a CA return with no pensionDistributionTaxable.

  • Schedule CA (540) Part I HSA add-backs (R&TC §17215.4 (IRC §223 HSA non-conformity; §17131.4 governs the §106(d) employer-contribution piece)…

    Schedule CA (540) Part I HSA add-backs (R&TC §17215.4 (IRC §223 HSA non-conformity; §17131.4 governs the §106(d) employer-contribution piece) — CA does not recognize HSAs). Three caller-asserted ADDITIONS to CA AGI ONLY (never federal AGI), each requiring caHsaAddbacksAffirmed:true (fail-closed): caHsaEmployerContributionAddition (W-2 box 12 code W employer/cafeteria contribution → Section A line 1h col C); caHsaInterestAddition (interest earned inside the HSA → line 2 col C); caHsaDividendAddition (taxable dividends earned inside the HSA → line 3 col C). All over-tax-safe. NOT modeled (declined/omitted): the SELF-contribution HSA deduction add-back (the engine takes no federal Form 8889 deduction → adding it back would double-count/over-tax); HSA distributions (line 8f); Archer-MSA rollover (R&TC §17215 / IRC §220, +12.5%); and the IRA-to-HSA one-time qualified-HSA-funding distribution, which is EXCLUDED federally under §408(d)(9)(A) but which CA requires added back to CA AGI (and, where the distribution is premature under the §72(t) rules, a 2 1/2% additional tax) (R&TC §17215.4; FTB 3805P instructions). That last one is the ONE item in this paragraph whose omission UNDER-taxes rather than over-taxes — the 'all over-tax-safe' statement above governs the three modeled ADDITIONS, not this omission. Do NOT also report HSA in-account earnings in taxableInterest/ordinaryDividends.

New York and New York City

New York City (NYC) resident tax is modeled for a full-year NYC resident (nycResident) within the NY 2025 surface; NYC is not a separate route — supply the NY return with NYC residency. Part-year/nonresident NYC declines.

  • selected NY 2025 compute paths (incl. NYC resident / New York City resident tax)
  • clean state-conforming non-wage income (interest / dividends / net capital gain) taxed at ordinary NY brackets…

    clean state-conforming non-wage income (interest / dividends / net capital gain) taxed at ordinary NY brackets — requires stateIncomeConformsToFederal:true AND nyWageAdditions

  • IT-201 line 34 deduction = greater-of(NY standard deduction, caller-asserted nyItemizedDeductions)…

    IT-201 line 34 deduction = greater-of(NY standard deduction, caller-asserted nyItemizedDeductions). nyItemizedDeductions is the FINAL Form IT-196 line 49 — AFTER the NY state/local income-tax ADDBACK and the NY high-income itemized LIMITATION worksheet (IT-196-I line 47: itemized limited to 50% of line-19 charity for NYAGI $1M–$10M, 25% for NYAGI over $10M; line 48 then adds the college-tuition itemized deduction) — NOT the federal Schedule A total (over-asserting UNDER-taxes). The engine consumes it (like a W-2 box), does not derive it or apply the IT-196 limitation; a VERIFY flag surfaces the contract (enhanced, tier-correct, over $1M AGI). The recapture worksheet correctly handles the resulting low-taxable-income/high-AGI case (IT-201-I worksheets 1-11).

  • IT-201 line 27 — taxable amount of Social Security benefits, FULLY EXCLUDED…

    IT-201 line 27 — taxable amount of Social Security benefits, FULLY EXCLUDED. NY does not tax Social Security; the engine recomputes the federal §86 taxable portion (1040 line 6b) in-process from socialSecurityBenefits and SUBTRACTS exactly that amount from NY AGI (line 33), NY taxable income (line 38), AND the NY recapture base — never from the Empire State Child Credit phase-out base or IT-201 line 19, which use FEDERAL AGI (correctly SS-inclusive). DERIVED not caller-asserted → cap built in (federal 6b=$0 → $0). REQUIRES the SAME §86 gates as the federal endpoint (socialSecurityStandardCaseAffirmed:true; socialSecurityMfsLivedWithSpouse for MFS) + nyWageAdditions — an unaffirmed SS return declines federally → declines NY. Tax-exempt interest (line 2a) is accepted as a §86 operand but any positive amount DECLINES (state_tax_exempt_interest_unsupported — the IT-225 A-101 non-NY-muni add-back is not sized in this slice).

  • IT-201 line 26 (government pension) / line 29 (private pension/annuity)…

    IT-201 line 26 (government pension) / line 29 (private pension/annuity) — NY EXCLUDES pension, DERIVED from the computed federal line 5b and subtracted from NY AGI (line 33) / taxable income / recapture base ONLY (never the ESC phase-out base or IT-201 line 19, which use federal AGI, correctly pension-INCLUSIVE). Line 26 = NYS/local/federal GOVERNMENT-EMPLOYER pension (incl. U.S. military, its territories/possessions or any political subdivision thereof, or DC; also a nonemployee spouse's QDRO/DRO distribution from a government pension plan), FULL exclusion uncapped (§612(c)(3)), gated by nyPensionIsGovernmentPension:true. ORP PORTION LIMIT: an Optional Retirement Program participant may only affirm this for the SUNY/CUNY/NYSED-attributable portion -- a mixed ORP distribution must not affirm the whole scalar, and MUST now ALSO affirm nyGovernmentPensionNotOrpOrEntirelySunyCunyNysedAttributableAffirmed:true (EITHER not-ORP-at-all OR entirely SUNY/CUNY/NYSED-attributable) whenever nyPensionIsGovernmentPension:true is claimed -- absent/false → decline (ny_pension_orp_portion_unsupported), since this engine cannot isolate a partial ORP amount from the single line-5b scalar and will not silently grant the full exclusion to a genuinely mixed distribution. Per IT-201-I, IRC §457 GOVERNMENT deferred-comp is EXPLICITLY NOT line 26 — it goes to line 29 (capped). Line 29 = PRIVATE pension/annuity (incl. IRC §457 govt deferred comp / IRA / §403(b) / Keogh), min($20,000, line 5b) (§612(c)(3-a)), gated by nyPrivatePensionQualifiesFor20kExclusion:true (attests, for the recipient's OWN pension, 59½ before Jan 1 2025 (on a joint return, each spouse who received any of it), all of pensionDistributionTaxable is qualifying pension/annuity income per IT-201-I's PER-SOURCE periodic/lump-sum matrix (for IRA, Keogh and cafeteria/§401(k): none from contributions made after retiring) — NOT a uniform periodic-only rule: an IRA qualifies periodic or lump-sum; a Keogh qualifies periodic or lump-sum only if Form 4972 is NOT used for the lump sum; §457 govt deferred-comp, §403(b), cafeteria/§401(k), AND an ordinary employer pension (IT-201-I's own first line-29 bullet) distributions are all PERIODIC-ONLY with no lump-sum exception — and NONE of it is a nonqualified commercial annuity / QDRO nonemployee-spouse distribution / SECURE 2.0 Roth employer contribution / a government-employer pension including U.S. military retired pay (that belongs on line 26, uncapped — routing it here over-taxes by capping at $20,000) — IT-201-I's own negative list). NQDC (nonqualified deferred compensation, W-2 box 11) is a SEPARATE income source from line 5b entirely -- nyNqdcPensionWagesAmount lets a caller assert the NQDC-attributable portion of wages (bounded: must not exceed wages), REQUIRES nyNqdcPensionQualifiesFor20kExclusionAffirmed:true (attests 59½, PERIODIC payments before retirement, and NONGOVERNMENTAL plan -- absent/false decline, ny_nqdc_pension_exclusion_unsupported; supplied without a positive amount declines as an orphan affirmation), and SHARES the SAME $20,000 cap with any line-29 private pension on the same return (additive independent caps would double the ceiling and under-tax). A NY-PENSION-RAILROAD-TIER2-NOT-MODELED VERIFY flag fires on every NY pension return, naming NY's own unmodeled Tier-2 railroad-retirement exclusion (IT-225 S-122, 45 U.S.C. §231m) — the NY-side mirror of CA's already-disclosed identical divergence. A positive pension ALSO requires pensionDistributionIsNonqualifiedAnnuityNii to be explicitly true or false whenever this line-29 exclusion is claimed, UNCONDITIONALLY — not just when federal §1411 NIIT happens to make the classification material (absent → ny_private_pension_exclusion_classification_needed decline) — AND requires nyPrivatePensionIsEntirelyRecipientsOwnNotInheritedAffirmed to be explicitly true or false: IT-201-I's line-29 'Beneficiaries' rule gives an inherited pension a decedent-keyed entitlement (net of the decedent's own usage, allocated among beneficiaries) this engine does not model, so absent/false → decline (ny_private_pension_beneficiary_classification_needed / ny_private_pension_beneficiary_allocation_unsupported) rather than guess an allocation. Line 26 is unaffected — its own instruction already extends the full exclusion to a beneficiary with no allocation or decedent-age test. Each affirmation attests ALL of pensionDistributionTaxable (IRA distributions included) is of its class — a MIXED govt+private (or qualifying+non-qualifying) 5b affirms NEITHER (pension stays NY-taxable, or a preparer splits). Both affirmed → decline (pension_exclusion_classification_ambiguous). Neither affirmed → pension stays NY-taxable (over-tax-safe). Requires BOTH pensionDistributionFullyTaxableAffirmed AND pensionDistributionNotSubjectToEarlyWithdrawalPenaltyAffirmed (this second gate's own conditional pensionDistributionNonqualifiedAnnuityEarlyWithdrawalBasisIsValidUnder72qAffirmed requirement per fed-pension-5b-72q-levy-exception-fix above, and its pensionDistributionNoSeppModificationRecaptureAffirmed requirement per fed-pension-5b-sepp-modification-recapture-gate above, also fire here, via the shared federal recompute) + nyWageAdditions.

Workflows

  • Reconcile (California): recomputes a return from the facts you assert and diffs it against the filed figures. It never changes the filed return. Status is one of match, mismatch, unsupported, or needs_review.
  • What-if (federal): up to 25 complete scenarios in one call, each computed independently.
  • Review packet (federal): up to 25 profiles recomputed into items a preparer reviews one by one.

Outside the envelope

These decline deterministically. They are not errors and are not retried into a number.

  • full-return preparation or filing
  • credits beyond the documented Child Tax Credit / Credit for Other Dependents / ACTC slices and the §904(j) de-minimis foreign tax credit (see federal.modeled_surfaces)…

    credits beyond the documented Child Tax Credit / Credit for Other Dependents / ACTC slices and the §904(j) de-minimis foreign tax credit (see federal.modeled_surfaces) — full Form 1116 (interest-expense apportionment, the QDI/cap-gain adjustment worksheet itself, multi-category, AMT-FTC, carryover) remains out of scope

  • dependent identity/residency/support derivation beyond caller-affirmed CTC/ODC counts
  • itemized deductions beyond SALT, home mortgage interest, medical, charitable, gambling losses and investment interest (other casualty, theft, misc.)
  • broad payments/refund workflows
  • Schedule D RESIDUAL mechanics…

    Schedule D RESIDUAL mechanics — the §1091 replacement-basis linkage (lotId/replacementForLotId, basis increase + holding-period tack on the replacement lot), non-W Form 8949 adjustment codes, a wash amount missing either of its two affirmations, special-rate (§1250/28%-collectible) wash lots, and noncovered/no-1099 boxes — are out of scope (decline, no tax-number leakage). MODELED (see federal.modeled_surfaces): the covered-clean A/D lot/aggregate path, the NARROW broker-reported code-W wash-sale add-back under its two affirmations (the wash_sale surface), pre-netted scalar ST/LT gains, capital-loss carryover I/O, the §1250-unrecaptured (25%) / 28%-collectibles special-rate portions, and an affirmed §1256-contract aggregate (2025 only, not alongside a special-rate gain; positive net, or C-slice-2b no-election loss with section1256LossCurrentlyDeductibleAffirmed; both require section1256AggregateIsFinalNoAdjustmentOrDeferralAffirmed, section1256TaxpayerIsNotOptionsOrCommoditiesDealerAffirmed, AND section1256NotLimitedPartnerDealerEquityOptionAffirmed; Form 6781 40/60)

  • business residual / pass-through / QBI outside bounded slices…

    business residual / pass-through / QBI outside bounded slices — a POSITIVE scheduleCIncome COMPUTES only as the caller-affirmed final net of one sole proprietor (and below-threshold Schedule C QBI only with scheduleCQbiEligible); Schedule C losses, depreciation/§179/bonus, multiple Schedule Cs, spouse allocation, SE health-insurance, home-office, farm/clergy/statutory, §1402 optional methods, above-threshold/SSTB/wage-limited QBI, supplied qbiDeduction decline, and partnership and S corporation K-1s are not accepted. RENTAL: a POSITIVE (or zero) scheduleEIncome COMPUTES only as a bounded simple passive rental with THREE affirmations — scheduleERentalIsPassiveFinalNet, scheduleERentalNotSection162Business, and scheduleERentalNoAmtDifferenceAffirmed (the Form 6251 line-2m AMT-parity attestation); a rental LOSS computes only inside the six-affirmation active-participation §469(i) envelope. Missing affirmations, MFS/SS/real-estate-professional loss cases, §162/QBI trade-business rental, and CA rental business adjustments decline. All declines are no-tax-number-leakage. BOUNDARY: the engine declines only on a SUPPLIED out-of-scope field — it cannot detect income a caller OMITS (a business/rental filer who sends only wages under-reports; that is a caller/extractor responsibility)

  • state coverage beyond the jurisdiction surfaces above
  • ambiguous or corrected source documents outside the documented envelope

Read it as JSON

The same manifest, with every modeled field, affirmation, decline code, and billing rule, is public. It needs no key and costs nothing. Current version: 2026-10-25.27.

curl https://tax-mcp.com/api/mcp/tax-capabilities -H "Accept: application/json"

In a browser, /api/mcp/tax-capabilities renders a readable view. Field details are in the reference.

Need something that isn't covered?

Tell us what you were trying to compute: Ask for missing coverage.

See also: Declines & affirmations.

Roadmap status for this page

Generated from the roadmap (updated 2026-10-30). Shipped & certified means live and independently checked against primary tax sources; certifying means live, with those checks still in progress. 29 related items are planned and not available yet; see the roadmap.

Federal income tax — core 1040
CapabilityStatus
1040 ordinary tax + standard deduction + preferential LTCG 0%/15% — 2024–2026Computes 2024–2026 Form 1040 ordinary tax, standard deduction, and 0%/15% preferential long-term capital gain rates.✅ shipped & certified
2020–2023 federal ordinary-bracket + standard-deduction + preferential-LTCG 0%/15% certifiedComputes 2020–2023 federal ordinary brackets, standard deduction, and the 0%/15% long-term capital gain bands for all filing statuses.✅ shipped & certified
Preferential LTCG / qualified-dividend bands (0/15/20)Computes the 0%/15%/20% preferential rate bands for long-term capital gains and qualified dividends.✅ shipped & certified
NIIT — Form 8960Computes the net investment income tax (NIIT) on Form 8960.✅ shipped & certified
Additional Medicare — Form 8959Computes the Additional Medicare Tax on Form 8959.✅ shipped & certified
AMT backstop — Form 6251 (modeled facts only)Adds AMT (Form 6251) from the return's modeled facts; declines on certain unmodeled preference items. Has known gaps (see details).Known gap: A trust K-1 AMT adjustment (line 2j) with no K-1 income, on a return with no investment income, isn't detected✅ shipped & certified
AMT mortgage-interest addback — close the non-qualified-dwelling gate (Form 6251 Line 3)Requires an attestation that positive mortgage interest secures an AMT-qualified dwelling (Form 6251 line 3); otherwise declines.✅ shipped & certified
AMT §1202 excluded-gain preference — Form 6251 Line 2h (7% addback or fail-closed gate)Doesn't compute the 7% Form 6251 line 2h §1202 preference; requires the caller to attest none applies, otherwise declines.✅ shipped & certified
AMT mortgage gate — add the §56(e)(1)(A) principal-residence prong (stop over-declining §121 houseboats)AMT mortgage gate accepts either a §121 principal residence or an AMT-qualified dwelling, so a principal-residence houseboat no longer declines.✅ shipped & certified
AMT parity gates — Schedule E ordinary rental net (Form 6251 line 2m for a passive activity) + prior-year capital-loss carryover (Lines 13-15)Before computing AMT, requires the caller to attest no AMT difference for Schedule E rental income or a prior-year capital-loss carryover. Has known gaps.Known gap: A carryover netted into gains and also sent in the carryover field counts twice; the engine can't detect itKnown gap: An AMT-only carryover the caller doesn't send is not seen, so AMT can be overstated✅ shipped & certified
Adjustments, deductions, itemization, SALT
CapabilityStatus
Simple itemized slice: SALT/property tax + acquisition-debt mortgage interest (Single/MFJ/HoH; MFS & incomplete mortgage facts decline)Computes a simple Schedule A: state/local and property taxes plus acquisition-debt mortgage interest, for Single, MFJ, and HoH.✅ shipped & certified
Dependent filer: limited standard deduction (§63(c)(5))Limits the standard deduction for a filer who can be claimed as someone else's dependent. Has known gaps.Known gap: The kiddie tax isn't computed, and isn't caught when the child isn't a dependent✅ shipped & certified
65 or older / blind: additional standard deduction (§63(f))Adds the §63(f) amount to the standard deduction for a filer or spouse who is 65 or older or blind. Has known gaps.Known gap: Absent age or blindness fields are read as falseKnown gap: An MFS spouse's boxes are not applied✅ shipped & certified
Married filing separately: zero standard deduction when the spouse itemizes (§63(c)(6)(A))Applies the rule that a married-filing-separately standard deduction is zero when the other spouse itemizes. Has known gaps.Known gap: CA and NY returns don't apply the ruleKnown gap: With a yes answer the filer's own itemized deductions aren't computed (an over-tax)✅ shipped & certified
2025-2028 senior deduction ($6,000 per person 65+, §151(d)(5)(C))Takes the 2025-2028 senior deduction for a filer, and a joint spouse, who is 65 or older. Has known gaps.Known gap: Not taken for a dependent filer or without the eligibility attestation (an over-tax)Known gap: There is no qualifying-surviving-spouse status; sent as joint it gets joint thresholds (an under-tax)◐ certifying
Itemized: medical and cash charitable (Schedule A lines 1-4, 11)Adds attested medical expenses and cash gifts to public charities to Schedule A. Has known gaps.Known gap: Charitable carryovers and the non-itemizer cash deductions (2020, 2021, 2026) aren't modeled (over-tax)Known gap: From 2026, cash above 30% of AGI is capped unless an attestation lifts it (over-tax)Known gap: State returns don't accept these fieldsKnown gap: From 2026 the limits are rounded down and the 0.5% floor up (over-tax)✅ shipped & certified
Gambling winnings and losses (Schedule 1, Schedule A)Adds gambling winnings to income and gambling losses to Schedule A. Has known gaps.Known gap: Needs per-wager totals, slot play too; can over-tax vs slot sessionsKnown gap: W-2G withholding isn't a payment inputKnown gap: Professional and pass-through gambling are out of scopeKnown gap: State returns don't accept these fields✅ shipped & certified
Investment interest (Form 4952) on interest and dividendsDeducts investment interest on Schedule A through Form 4952 and returns the carryforward. Has known gaps.Known gap: No election to count qualified dividends or gains (over-tax)Known gap: The AMT carryforward is taken as 0 (over-tax)Known gap: The net investment income tax isn't reduced (over-tax)✅ shipped & certified
Non-cash charitable: personal-use property and listed stock (Pub 526 Worksheet 2)Deducts non-cash gifts to public charities with the cash limits coordinated. Has known gaps.Known gap: Other property, private non-operating foundations and carryovers aren't modeled (over-tax)Known gap: Loss investment property, open-end or grantor-trust shares and large blocks can't be attested (over-tax)Known gap: From 2026, gifts above 60% of AGI leave non-cash undeducted (over-tax)Known gap: State returns don't accept these fields✅ shipped & certified
Qualified disaster casualty losses, 2025-2026 (Form 4684, §63(b)(8))Deducts 2025-2026 losses from a FEMA major disaster, itemizing or not. Has known gaps.Known gap: Other casualty and theft losses and 2020-2024 aren't modeled (over-tax)Known gap: One storm over two declared areas takes two $500 floors; NIIT: the loss offsets net gain only (over-tax)Known gap: Declarations newer than the list, gains, married filing separately and losses above taxable income declineKnown gap: State returns don't accept these fields✅ shipped & certified
QBI §199A — qualified REIT dividends onlyComputes the §199A 20% QBI deduction for qualified REIT dividends only.✅ shipped & certified
Capital gains, brokerage, Schedule D / 8949
CapabilityStatus
Clean covered capital-gain factsComputes tax on clean covered capital gains: long-term gains and qualified dividends at preferential rates, short-term at ordinary rates.✅ shipped & certified
Federal capital-loss carryover I/O + ending carryover derive-forward — covered-clean Form 8949 box A/D aggregates (or pre-netted scalars); §1211(b) −$3k (−$1,500 MFS) limit + ST/LT nettingComputes capital-loss carryover and ST/LT netting of covered-clean Form 8949 box A/D aggregates only, with the §1211(b) $3,000 ($1,500 MFS) limit.✅ shipped & certified
Schedule D / Form 8949 — broader netting claims: wash-sale-safe multi-broker, noncovered / basis-adjustment handling, state aggregate support, prior-return-derived carryforward chainsComputes Schedule D netting with a narrow broker-reported (code W) wash-sale add-back and the capital loss carryover worksheet.✅ shipped & certified
§1256 contracts / Form 6781 (60/40 mark-to-market split)Computes a TY2025 aggregate §1256 net gain or loss with the 60/40 long/short split onto Schedule D, gated by caller attestations.✅ shipped & certified
Shared lot/evidence contract (Form 8949 CapGainEntry v0) — the frozen input contract for all capital-gain verticalsDefines the Form 8949 lot input contract for capital gains; computes only clean covered box A/D lots with a wash-sale affirmation and declines the rest.✅ shipped & certified
Wash-sale disallowance bound — decline when it exceeds a single atomic lot's own realized lossFor single-lot 1099-B entries, declines when the reported wash-sale disallowance exceeds that lot's own realized loss.✅ shipped & certified
Wash-sale atomicity is AFFIRMED, never inferred — close the omitted-granularity default gap + un-falsify the atomic-lot decline proseWash-sale lot atomicity must be affirmed, not inferred; an unaffirmed entry whose disallowance exceeds its net declines.✅ shipped & certified
Wash-sale combined-multi-block gate — stop declining a genuinely same-date combined sale (Form 8949 permits, doesn't require, VARIOUS)Accepts a combined wash-sale Form 8949 row that carries a real shared acquisition date instead of VARIOUS, rather than declining it.✅ shipped & certified
Equity-comp basis adjustment — RSU / NSO (1099-B code-B; comp-adjusted basis)Computes the Form 8949 code B basis adjustment for RSU/NSO lots by adding W-2 or 1099-NEC ordinary income to broker-reported basis.✅ shipped & certified
Equity-comp — ISO (disqualifying disposition) + ESPP (qualifying + disqualifying)Computes Form 8949 basis adjustments for ISO disqualifying dispositions and for ESPP qualifying or disqualifying dispositions.✅ shipped & certified
§1250 / collectibles special-rate gainsComputes regular tax on unrecaptured §1250 and 28%-rate gains via the Schedule D Tax Worksheet, and AMT Part III from its lines. Has known gaps.Known gap: A carryover netted into gains and also sent in the carryover field counts twice; the engine can't detect itKnown gap: A trust K-1 AMT adjustment (line 2j) with no K-1 income, on a return with no investment income, isn't detected✅ shipped & certified
AMT parity gates — §1202 excluded-gain preference surviving a $0 taxable 28%-rate residue, and a Schedule C net of exactly $0 embedding a genuine AMT preferenceRequires an AMT §1202 attestation when Schedule D input is present, and an AMT attestation for a Schedule C net of exactly $0.✅ shipped & certified
Fix Form 6251 Part III AMT — use the regular-tax Schedule D Tax Worksheet's line 14 / line 21, not a taxableIncome-minus-preferential shortcutForm 6251 Part III AMT on unrecaptured §1250 and 28% collectibles gain uses the regular-tax Schedule D Tax Worksheet lines 14 and 21.✅ shipped & certified
Form 6251 Part III, literally: line 13 uncapped, each rate line rounded on its ownForm 6251 Part III follows the form: dividends and gains aren't capped at taxable income, and each line is rounded to whole dollars. Has known gaps.Known gap: On a whole-dollar return, keeping cents in these worksheets can change total tax by up to $2 either way✅ shipped & certified
Credits & credit limitations
CapabilityStatus
Foreign Tax Credit — de-minimis §904(j) (≤$300/$600 MFJ, all-passive-1099 affirmed)Computes the foreign tax credit without Form 1116 under the §904(j) de minimis rule: up to $300 ($600 MFJ) of passive foreign tax.✅ shipped & certified
Correct the FTC safe-harbor annuity-inclusion term's design-comment rationale — what survives is Pub 519 sourcing plus an executed safe-direction argumentCorrects why qualified-plan pension stayed out of the Form 1116 safe harbor's passive-income bound (now switched off); no compute change.✅ shipped & certified
Child Tax Credit / ACTC — Schedule 8812Computes the Schedule 8812 child tax credit (2020, 2022-2026), credit for other dependents, and a bounded ACTC (Part II-A; from 2026 see Schedule 3-A).✅ shipped & certified
Schedule 3-A federal public benefit (2026+, refunded ACTC)From 2026, declines a No on Schedule 3-A line 7 or 8 (refunded ACTC); omitted assumes Yes; has known gaps.Known gap: Omitted overstates the refund for a filer who would answer No◐ certifying
Premium tax credit — Form 8962 (2020 and 2022-2025, one Form 1095-A)Computes the premium tax credit (Form 8962) for 2020 and 2022-2025, one Form 1095-A: the excess advance payment repayment or the net credit.◐ certifying
Special federal taxes & safe-decline mechanics
CapabilityStatus
Form 2210 §6654 no-penalty safe harbors + advisory penalty ceilingOpt-in Form 2210 check: reports no underpayment penalty when a §6654 safe harbor is met, and flags the return for a preparer otherwise.✅ shipped & certified
Income modules — business, rental, passthrough
CapabilityStatus
Retirement — fully-taxable pension / annuity / IRA (1040 line 5b)Computes a clean, fully taxable 1099-R distribution into AGI when the caller affirms it; relies on those affirmations. Has known gaps.Known gap: Some NY eligibility limits aren't checked, e.g. a pre-retirement disability pensionKnown gap: A stopped SEPP series on a return with no pension field isn't detected, so §72(t)(4) recapture can be missedKnown gap: A mixed ORP distribution can't take a partial exclusion; leaving it out computes but over-taxes✅ shipped & certified
NY IT-201 line 26 government-pension exclusion has no way to limit an Optional Retirement Program (ORP) affirmation to the SUNY/CUNY/NYSED-attributable portion -- a mixed ORP distribution falsely affirmed in full silently under-taxes, with NO decline path (unlike the beneficiary/decedent-allocation gate this leaf's own line-29 path already has)NY IT-201 line 26 government-pension exclusion requires attesting the payment is not ORP, or is entirely SUNY/CUNY/NYSED-attributable. Has known gaps.Known gap: A mixed ORP distribution can't take a partial exclusion; leaving it out computes but over-taxes✅ shipped & certified
NY IT-201 line 29 private-pension exclusion (§612(c)(3-a)) has no way to reach nonqualified deferred compensation (NQDC) reported in W-2 box 11 -- NY DTF Advisory Opinion TSB-A-10(1)I treats a qualifying employer-sponsored NQDC distribution as pension income eligible for the $20,000 exclusion, but this engine's NY exclusion runs exclusively off federal line 5b (pensionDistributionTaxable, a 1099-R-only field), and the NQDC amount correctly stays in federal wages -- so it is silently taxed in full with no exclusion path at allLets qualifying nonqualified deferred compensation reported in W-2 box 11 use NY's $20,000 IT-201 line 29 pension exclusion.✅ shipped & certified
Close the §72(t)(3)(A)/(2)(D)-(F)/(3)(B) plan-type mismatch gap: the engine had no way to enforce that a claimed §72(t)(2) early-withdrawal exception is actually available for the caller's ACTUAL plan type (IRA vs. employer qualified plan), letting a caller silently skip the 10% additional tax by claiming a basis unavailable to their plan typeDeclines a penalty-free early pension distribution unless the caller attests the §72(t) exception fits the plan type.✅ shipped & certified
Close the §72(t)(4)/§72(q)(3) SEPP-modification-recapture gap in BOTH regimes: the engine had no way to enforce that a modification-year distribution can't be affirmed under the substantially-equal-periodic-payments basis, for either a qualified plan or a nonqualified annuityClaiming an early-withdrawal penalty exception requires affirming no prior SEPP series was modified in the recapture window. Has known gaps.Known gap: A stopped SEPP series on a return with no pension field isn't detected, so §72(t)(4) recapture can be missed✅ shipped & certified
Close the §72(t) early-withdrawal trap: split into two atomic affirmations so an early distribution can never be accidentally affirmed throughRequires an affirmation that no federal additional tax applies (§72(t), §72(m)(5), §72(v) or similar), or the return declines; that tax is not computed.✅ shipped & certified
Gate the §1411 NIIT exclusion to qualified-plan distributions only — nonqualified commercial annuities are net investment incomeIncludes a nonqualified commercial annuity distribution in net investment income for NIIT when the caller classifies it as one.✅ shipped & certified
Require the NII nonqualified-annuity classification whenever NY's private-pension $20,000 exclusion is claimed — not just when federal NIIT makes it materialWhen NY's $20,000 private-pension exclusion is claimed, requires the caller to say whether it's a nonqualified annuity; otherwise declines.✅ shipped & certified
Round the NIIT materiality gate's comparison to whole dollars before comparing — an unrounded-base comparison over-declines at boundaries where both classifications produce the identical whole-dollar NIITThe pension NIIT classification gate compares whole-dollar NIIT, so it no longer declines when both classifications give the same rounded tax.✅ shipped & certified
Require an explicit inherited-pension classification for NY's $20,000 private-pension exclusion — decline rather than guess the IT-201-I 'Beneficiaries' allocationNY's $20,000 private-pension exclusion requires the caller to state the pension is their own; inherited pensions decline instead of guessing.✅ shipped & certified
CA's R&TC §17132.9/§17132.10 military-retirement exclusion — up to $20,000 of uniformed-services retired pay / DoD Survivor Benefit Plan annuities, tax years 2025-2029, AGI-gatedExcludes up to $20,000 of uniformed-services retired pay or DoD SBP annuity from CA AGI when attested and AGI qualifies. Has known gaps.Known gap: Over $20,000 of combined qualifying income (e.g. two retirees) is under-excluded (over-tax)Known gap: A surviving spouse filing single/HOH with AGI $125,001–$250,000 gets no exclusion (over-tax)✅ shipped & certified
Decline a self-contradictory CA pension profile — nonqualified-annuity NII affirmed alongside the military-retirement-pay affirmation, both trueDeclines a CA return that affirms the same pension is both a self-funded nonqualified annuity and military retired pay.✅ shipped & certified
Three prose-only disclosure fixes from round-4 /certify-leaf: NY's after-retirement negative list, NY's disability-income combined cap, CA's MFJ VERIFY-flag overclaimDisclosure corrections for NY pension-exclusion limits and CA's joint-return military-retirement question; no tax computation changed.✅ shipped & certified
Fix a false decline: SIMPLE-IRA first-2-years timing no longer wrongly disqualifies an otherwise 59½+/exception-covered distributionA SIMPLE IRA distribution covered by age 59½ or another §72(t) exception can be affirmed penalty-free regardless of the 2-year window.✅ shipped & certified
CA/NY: footed line entry + non-stale conformity flags for the military-retirement exclusion, the pension exclusion, and the SS subtractionCA and NY returns show the line entry and an accurate disclosure for military, pension and Social Security exclusions.✅ shipped & certified
§72(q) has no IRS-levy exception — a nonqualified annuity affirming the levy exception must not bypass the early-distribution gateOn the federal endpoint, a nonqualified annuity's early-withdrawal exception needs a §72(q)(2) validity attestation. Has known gaps.Known gap: The document-ingest path (no API caller today) does not check early-withdrawal exceptions✅ shipped & certified
Guard against a NY filer misclassifying a government/military pension onto the capped line-29 private-pension exclusion — re-scoped, NO-GO on the originally-proposed contradiction gateNY returns using the capped line-29 private-pension exclusion get a flag warning against placing government or military pensions there.✅ shipped & certified
Mechanical proof that no CA-only and NY-only field can ever coexist in one request — retires the "is this cross-state contradiction reachable" judgment call for every future certification roundCA-only and NY-only input fields can't be combined in one request; each state's schema rejects the other state's fields.✅ shipped & certified
Mechanical footing gate: every state return's lines[] must reconcile to its AGI line — plus the missing nyWageAdditions row that motivated itEach CA and NY return line declares its role in state AGI, and the lines must reconcile to the AGI line; NY wage add-backs now get their own row.✅ shipped & certified
Retirement — Social Security §86 (1040 line 6b) + CA/NY exclusionComputes taxable Social Security (Form 1040 line 6b) with the §86 0/50/85% worksheet, and excludes the benefits for CA and NY. Has known gaps.Known gap: Rounded only at worksheet line 18, so taxable benefits and AGI can be $1 below the worksheet rounded by line◐ certifying
Stop flooring the pre-SS provisional-income operand at $0 — a net capital loss must flow through unfloored per Pub 915 Worksheet 1 line 3Lets a net capital loss reduce provisional income for taxable Social Security, as Pub 915 Worksheet 1 line 3 requires.✅ shipped & certified
Schedule E — simple passive rental (positive affirmed net)Flows a positive 2025 final Schedule E line 26 passive-rental net into AGI and the NIIT base, with required affirmations.✅ shipped & certified
Schedule E §469(i) active-participation rental-loss allowance (TY2025 federal)Computes the TY2025 federal §469(i) rental-loss allowance for active participants: up to $25,000, phased out from $100,000 to $150,000 MAGI.✅ shipped & certified
Schedule E rental LOSS — §469(g)(1)(A) full-disposition PAL RELEASE (UNCAPPED)On a fully taxable sale of an entire passive rental activity to an unrelated party, deducts current and suspended losses in full (§469(g)).✅ shipped & certified
Schedule K-1 (Form 1041) — interest, dividends, capital gainsAccepts estate and trust K-1s (Form 1041) for interest, dividends and net capital gains; anything else on the K-1 declines. Has known gaps.Known gap: State returns don't accept K-1sKnown gap: Partnership and S-corporation K-1s aren't accepted✅ shipped & certified