{"capability_version":"2026-07-12.2","product":"Tax MCP","summary":"Coverage-bounded, §6694-disciplined tax compute. Computes inside the documented supported envelope (per jurisdiction below); returns a deterministic unsupported/needs_review decline outside it. No LLM in the loop.","supported_envelope":{"routes":[{"id":"capabilities","method":"GET","path":"/api/mcp/tax-capabilities"},{"id":"federal_compute","method":"POST","path":"/api/mcp/tax-compute/federal"},{"id":"state_compute","method":"POST","path":"/api/mcp/tax-compute/state"},{"id":"reconcile","method":"POST","path":"/api/mcp/tax-compute/reconcile"},{"id":"what_if","method":"POST","path":"/api/mcp/tax-compute/what-if"},{"id":"review_packet","method":"POST","path":"/api/mcp/tax-compute/review-packet"}],"jurisdictions":{"federal":{"years":[2020,2021,2022,2023,2024,2025,2026],"filing_statuses":["single","married_filing_jointly","married_filing_separately","head_of_household"],"income_fields_modeled":["year","filingStatus","wages","medicareWages","federalWithholding","priorYearTax","priorYearAGI","priorYearWasFull12MonthReturn","priorYearCitizenOrResidentAllYear","taxableInterest","ordinaryDividends","qualifiedDividends","netShortTermCapGain","netLongTermCapGain","priorYearCapLossCarryoverST","priorYearCapLossCarryoverLT","capGainAggregates","section1256NetGain","section1256CleanBrokerReportedAffirmed","section1256LossCurrentlyDeductibleAffirmed","mortgageInterest","mortgageAvgBalance","stateLocalIncomeTax","realEstateTax","foreignTaxPaid","foreignIncomeAllPassive1099","foreignSourceGrossIncome","foreignQualifiedDividendsAndCapGains","foreignTaxNoCarryoverAffirmed","reit199ADividends","pensionDistributionTaxable","socialSecurityBenefits","taxExemptInterest","scheduleEIncome","scheduleCIncome"],"deduction":"greater_of_standard_or_itemized_salt_and_mortgage","itemized_scope_note":"Itemized = SALT (OBBBA-2025 cap, MAGI-phased) + home mortgage interest (§163(h)(3) $750k limit — supply mortgageAvgBalance). Single/MFJ/HoH; MFS itemized declines (§63(c)(6)(A)). Medical, charitable, and other itemized categories are out of scope.","modeled_surfaces":["ordinary tax","NIIT (Form 8960)","Additional Medicare (Form 8959)","preferential LTCG/QDIV bands","QBI §199A — REIT dividends only (1099-DIV box 5): 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 (≤$300 / $600 MFJ, all-passive-1099 affirmed) PLUS a narrow Form 1116 Part I ratable-apportionment SAFE HARBOR above that ceiling (the common broker-1099-DIV-box-7 case — ADRs / foreign ETFs / international funds, §904(d) passive category). The safe harbor COMPUTES the actual limitation (never a caller-asserted numerator — foreignSourceGrossIncome is the raw Form 1116 line-3d input; the engine derives the line-18 numerator via Part I lines 3a-3g) when ALL hold: standard-deduction-only (no itemized input — declines otherwise), the §1(h) QDI/capital-gain rate-differential ADJUSTMENT EXCEPTION applies (foreignQualifiedDividendsAndCapGains strictly < $20,000 AND ordinary taxable income — taxable income less net capital gain/qualified dividends — at/below the year's 32%-ordinary-bracket-start threshold), no prior-year carryover (foreignTaxNoCarryoverAffirmed:true), no §199A REIT/PTP dividends present (reit199ADividends — the safe-harbor's limitation base is pre-QBI, and a present QBI deduction would lower the correct post-QBI limitation, an under-tax risk if let through), no positive Schedule C or Schedule E final net present (scheduleCIncome/scheduleEIncome — Form 1116 line 3e is gross receipts/gross rents before any deductions, which this engine cannot reconstruct from either schedule's FINAL NET; a Schedule C loss always declines separately via its own unconditional gate, but an affirmed Schedule E rental LOSS still computes over-tax-safe via the §469(i)/§469(g) path — same line-3e imprecision, not independently fenced, a documented residual, not a live under-tax vector), and all-passive-1099. Modeled for TY2020-2025 only (TY2026 declines — no Form 1116 (2026) instructions published yet to verify the $20,000 threshold against). AMT-binding + any foreign tax present still declines (Reg. §1.904(b)-1(b)(3) AMT-FTC special rules are not modeled, same gate for both paths). Any gap in the above (itemized present, adjustment-exception condition 1 or 2 failing, no-carryover unaffirmed, an unverified year, reit199ADividends present, a positive Schedule C/E net present) → foreign_tax_credit_needs_review decline; full Form 1116 (interest-expense apportionment, the QDI/cap-gain adjustment WORKSHEET itself, multi-category, AMT-FTC) remains a preparer surface","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). Not full Schedule A — medical/charitable/other itemized categories are out of scope.","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). 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 — a POSITIVE net (iteration 46) 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) — 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.","special-rate capital gain — Schedule D Tax Worksheet (iteration 36; year-range extended iteration 47). 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: each is a SUBSET of net LT gain, so sec1250UnrecapturedGain + collectibles28Gain > netLongTermCapGain is contradictory → the return DECLINES (fail-closed, never capped-and-under-taxed); a real portion omitted UNDER-taxes it at 0/15/20, so a preparer must assert it. 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), so a binding-AMT special-rate return computes the correct tentative minimum tax. 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).","simple passive rental (Schedule E) — a POSITIVE 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). 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 + the two positive affirmations, 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, filing status ≠ married_filing_separately, and NOT AMT-binding (a computed check — Form 6251 runs its own separate passive-activity-loss/at-risk worksheet this engine does not model, so a binding-AMT return declines rather than risk misstating AMT). NIIT similarly floors the released loss at max(0,…) for the NII base (over-tax-safe — a VERIFY flag names the Form 8960 same-activity NII-deduction simplification this slice does not model). 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, or AMT-binding) → 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) — 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, 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 (iteration 39) — 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; Codex R251-001), absent either → decline. NY ALSO CONFORMS (iteration 42) — 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 line 5b, 1099-R box 2a) — a POSITIVE pensionDistributionTaxable COMPUTES as ORDINARY income → AGI + ordinary tax ONLY (deliberately NOT the §1411 NIIT base — pension is not net investment income — and NOT the Additional-Medicare base — not wages), REQUIRING pensionDistributionFullyTaxableAffirmed:true. NOT modeled (a caller must NOT affirm → pension_needs_review decline): box-2b 'taxable amount not determined', basis/after-tax contributions, QCD, rollover, Roth conversion, NUA, and the early-distribution 10% additional tax (Form 5329). 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). CA CONFORMS to federal pension taxation (iteration 32) — a CA pension return COMPUTES and TAXES the pension in CA AGI (no exclusion), with a VERIFY flag naming the one CA divergence the engine does not model: Tier-2 railroad retirement (RRB-1099-R), which CA excludes (45 U.S.C. §231m).","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. CA/NY fully EXCLUDE the taxable Social Security on the state return (iteration 29 — Schedule CA (540) line 6 col B / IT-201 line 27; see the ca/ny jurisdiction blocks below).","underpayment-of-estimated-tax penalty — Form 2210 SAFE-HARBOR determination (IRC §6654, iteration 40, slice 1). 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 (iteration 41) — 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 (CA FTB 5805 / NY IT-2105.9 are later slices).","Child Tax Credit + Credit for Other Dependents (Schedule 8812 Part I, NON-refundable). qualifyingChildrenForCtc × $2,200 (2025, OBBBA) + otherDependentsForOdc × $500, 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, ctcActcFilerAndSpouseValidSsnAffirmed / odcFilerAndSpouseValidTinAffirmed (the FILER's, and if MFJ the spouse's, own SSN/TIN status — a 2025+ requirement with no prior-year analog; CTC/ACTC requires the filer to have a valid-for-employment SSN, ODC's filer-level rule is laxer — SSN or ITIN suffices). 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: unused CTC → refund, capped at min(unused CTC, qualifying-children × $1,700, 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.","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 OR SPOUSE 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 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 (fail-closed — the engine never assumes disqualifying); a QUALIFYING ISO disposition is out of scope (see below). ESPP computes for EITHER a qualifying or disqualifying §423 disposition — 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 gate applies to it. An equity-comp lot ALSO REQUIRES (else declines): acquiredDate + soldDate (the holding period must be evidence-backed, not inferred from the box letter — 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). 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); 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 supply the affirmed aggregate via section1256NetGain (a positive net, or a net LOSS under the additional section1256LossCurrentlyDeductibleAffirmed — the no-election default), which the box path can't attest clean of §475(f) mark-to-market / straddles / loss-carryback. 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); 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)."],"decline_codes":["year_not_modeled","special_rate_gain_unmodeled","out_of_scope_income","surtax_additional_medicare","itemized_deduction_needs_review","foreign_tax_credit_needs_review","capital_gain_lots_need_review","equity_comp_basis_adjustment_needs_review","section_1256_needs_review","digital_asset_needs_review","schedule_c_needs_review","schedule_c_loss_needs_review","schedule_c_se_needs_social_security_wages","schedule_e_needs_review","pension_needs_review","social_security_needs_review","child_tax_credit_needs_review","engine_declined"]},"ca":{"years":[2025],"filing_statuses":["single","married_filing_jointly","married_filing_separately","head_of_household"],"modeled_surfaces":["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 — requires stateIncomeConformsToFederal:true","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 — 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 — 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 — 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 — 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 line 5b) — CA CONFORMS and TAXES it (iteration 32). A fully-taxable pension stays in CA AGI and is taxed as ordinary income (Schedule CA 540 line 5a/5b: 'generally no adjustments'); NO CA exclusion. Over-tax-safe by construction (CA has no pension surtax). Requires pensionDistributionFullyTaxableAffirmed. A VERIFY flag (CA-PENSION-TAXED-CONFORMING) fires on every CA pension return naming the ONE CA divergence the engine does NOT model: Tier-2 RAILROAD retirement (RRB-1099-R), which CA EXCLUDES (45 U.S.C. §231m) — a preparer must subtract any Tier-2 portion on Schedule CA 540, else a railroad retiree is over-taxed.","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%). Do NOT also report HSA in-account earnings in taxableInterest/ordinaryDividends."],"non_wage_conformity_note":"CA taxes conforming non-wage income at ordinary brackets (no preferential capital-gains rate). Requires stateIncomeConformsToFederal:true affirming NO tax-exempt/out-of-state-muni interest, NO exempt-interest dividends OTHER THAN the out-of-state portion supplied as caOutOfStateMuniInterestAddition (a CA addition), and NO US-Treasury-obligation interest needing a CA subtraction OTHER THAN the explicitly-supplied caUsObligationInterestSubtraction (direct interest) or caUsObligationRicDividendSubtraction (RIC dividend, §17145), capital-gain basis == federal. (HSA add-backs are orthogonal — a separate over-tax-safe set of caller-asserted additions, see modeled_surfaces.) Without it, non-wage income declines. Schedule C sole-prop income NOW COMPUTES for CA (iteration 39 — CA conforms, taxes it in CA AGI; requires caScheduleCSelfEmployedForCaPurposesAffirmed + caScheduleCNoStateBusinessAdjustmentsAffirmed + the federal sole-prop affirmation). Schedule E, non-2025, part-year/nonresident, other states always decline.","decline_note":"Outside the modeled surface (other-status tax tables, credits, payments, OTHER Schedule CA additions/subtractions beyond the four accepted below, unaffirmed non-wage income) declines deterministically. CA itemized IS accepted as a caller-asserted line-30 total (REQUIRES itemizedDeductionsAreFinalStateAmount:true; MFS declines §63(c)(6)(A)); the DIRECT US-obligation interest subtraction IS accepted (caUsObligationInterestSubtraction, REQUIRES caUsObligationInterestAffirmed:true, capped at taxableInterest, direct-only); the RIC/mutual-fund US-obligation DIVIDEND subtraction IS accepted (caUsObligationRicDividendSubtraction, §17145, REQUIRES the two-part caUsObligationRicDividendAffirmed:true, capped at non-qualified ordinary dividends, 50%-asset cliff); the out-of-state exempt-interest-dividend addition IS accepted (caOutOfStateMuniInterestAddition, REQUIRES caOutOfStateMuniInterestAffirmed:true, over-tax-safe, CA + US-territory munis excluded, CA 50%-asset test surfaced); the HSA add-backs ARE accepted (caHsaEmployerContributionAddition / caHsaInterestAddition / caHsaDividendAddition, REQUIRES caHsaAddbacksAffirmed:true, over-tax-safe, §17215.4 (IRC §223; §17131.4 for §106(d) employer contributions) — but the self-contribution deduction add-back, HSA distributions, and Archer rollover (R&TC §17215 / IRC §220) are NOT modeled). See modeled_surfaces.","decline_codes":["year_not_modeled","unsupported_state","nonresident_or_part_year","non_wage_income_unsupported","ambiguous_supersession_underreport_risk","itemized_needs_final_amount_affirmation","mfs_itemized_needs_review","us_obligation_subtraction_needs_review","out_of_state_muni_addition_needs_review","us_obligation_ric_subtraction_needs_review","hsa_addback_needs_review","state_tax_exempt_interest_unsupported","federal_declined"]},"ny":{"years":[2025],"filing_statuses":["single","married_filing_jointly","married_filing_separately","head_of_household"],"nyc_note":"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.","modeled_surfaces":["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 — requires stateIncomeConformsToFederal:true AND nyWageAdditions","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. 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) — 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), FULL exclusion uncapped (§612(c)(3)), gated by nyPensionIsGovernmentPension:true. 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 59½ before Jan 1 2025 AND the whole 5b is qualifying periodic income). Each affirmation attests the WHOLE single-scalar line 5b 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 pensionDistributionFullyTaxableAffirmed + nyWageAdditions."],"non_wage_conformity_note":"NY taxes conforming non-wage income at ordinary brackets / recapture (no preferential rate). Requires stateIncomeConformsToFederal:true (same attestation as CA) AND nyWageAdditions. Without the affirmation, non-wage income declines. Schedule C CONFORMS (iteration 42) with nyScheduleCNoStateBusinessAdjustmentsAffirmed (else ny_schedule_c_adjustment_needs_review) + a VERIFY flag for the separate MCTMT/NYC-UBT. Schedule E RENTAL CONFORMS (iteration 43, NARROW — positive passive net, NY only) with nyScheduleENoStateBusinessAdjustmentsAffirmed (straight-line real property, no §168(k)/cost-seg/§179; else ny_schedule_e_adjustment_needs_review) — NY conforms to §469 PAL (CA Sch E stays declined: separate §469 track). non-2025, part-year/nonresident always decline.","decline_note":"Fails closed without nyWageAdditions; credits/payments beyond the modeled set and unaffirmed non-wage income decline deterministically. NY itemized IS accepted as a caller-asserted IT-196 line-49 total (see modeled_surfaces) but REQUIRES itemizedDeductionsAreFinalStateAmount:true (else declines), and MFS + itemized declines (§63(c)(6)(A) spouse-itemizes election).","decline_codes":["year_not_modeled","unsupported_state","nonresident_or_part_year","non_wage_income_unsupported","itemized_needs_final_amount_affirmation","mfs_itemized_needs_review","federal_declined","state_tax_exempt_interest_unsupported","pension_exclusion_classification_ambiguous","ny_schedule_c_adjustment_needs_review","ny_schedule_e_adjustment_needs_review","ny_wage_addback_undeterminable"]}},"reconcile":{"jurisdiction":"ca","non_mutating":true,"review_states":["match","mismatch","unsupported","needs_review"],"diff_row":"{ line, engine (engine-computed value or 'DECLINED'), filed, delta, cls, note? }","diff_classes":["MATCH","ENGINE-DECLINED","DIFFERS","NO-FILED"],"note":"Independently computes from source docs and reconciles against a filed return; never fabricates a full return. diff[].cls DIFFERS never assigns blame — a human adjudicates; ENGINE-DECLINED lines are never cross-filled from the filed value."}},"out_of_scope":["full-return preparation or filing","credits beyond the documented Child Tax Credit / Credit for Other Dependents / ACTC slices and the §904(j) de-minimis + Form 1116 safe-harbor 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, casualty, misc.)","broad payments/refund workflows","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 (2025), and an affirmed §1256-contract aggregate (positive net, or C-slice-2b no-election loss with section1256LossCurrentlyDeductibleAffirmed; Form 6781 40/60)","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, and K-1 / partnership / S corporation surfaces decline. RENTAL: a POSITIVE scheduleEIncome COMPUTES only as a bounded simple passive rental with the two affirmations; 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"],"decline_codes":{"federal":["year_not_modeled","special_rate_gain_unmodeled","out_of_scope_income","surtax_additional_medicare","itemized_deduction_needs_review","foreign_tax_credit_needs_review","capital_gain_lots_need_review","equity_comp_basis_adjustment_needs_review","section_1256_needs_review","digital_asset_needs_review","schedule_c_needs_review","schedule_c_loss_needs_review","schedule_c_se_needs_social_security_wages","schedule_e_needs_review","pension_needs_review","social_security_needs_review","child_tax_credit_needs_review","engine_declined"],"state_and_reconcile":"declines outside the modeled surface; reconcile uses review_states"},"preparer_routing":{"disclaimer":"NON-EXHAUSTIVE. For each federal decline code this lists, at minimum, the forms/schedules a human preparer must handle — never the complete set. The authority for any specific case is that response's own `reason` field (per-instance and richer than this static map); a preparer must independently confirm completeness. This map computes nothing and asserts no tax figure.","authoritative_source_note":"For a given decline, read the `reason` field on that 200 response — it names the case-specific forms and thresholds. This map is a coarse per-code index into that, not a substitute for it.","by_decline_code":{"year_not_modeled":{"at_minimum":["a preparer must prepare this return for a tax year the engine does not model."],"authoritative_source":"compute-response.reason","generic":true},"special_rate_gain_unmodeled":{"at_minimum":["a preparer must apply the §1250 unrecaptured-gain and §1202 exclusion special rates via the Schedule D tax worksheet for a year the engine does not model them."],"authoritative_source":"compute-response.reason"},"out_of_scope_income":{"at_minimum":["a preparer must handle caller-asserted income or a §199A deduction the engine does not model."],"authoritative_source":"compute-response.reason","generic":true},"surtax_additional_medicare":{"at_minimum":["a preparer must determine the Additional Medicare Tax when Medicare wages (box 5) are unavailable but the return shows other objective W-2 evidence (a positive box 1 wages, box 2 federal withholding, box 3 Social Security wages, or box 6 Medicare tax withheld)."],"authoritative_source":"compute-response.reason","generic":true},"itemized_deduction_needs_review":{"at_minimum":["a preparer must review the itemized deduction — the §63(c)(6)(A) married-filing-separately rule or the §163(h)(3) mortgage-interest limit."],"authoritative_source":"compute-response.reason","generic":true},"foreign_tax_credit_needs_review":{"at_minimum":["a preparer must complete Form 1116 for the foreign tax credit — confirm the §904(j) de-minimis election, or (above that ceiling) supply foreignSourceGrossIncome / foreignQualifiedDividendsAndCapGains / foreignTaxNoCarryoverAffirmed for the narrow safe-harbor path if it applies (standard-deduction-only, foreign QDI+capital-gain under $20,000, ordinary income at/below the 32%-bracket-start threshold, no carryover) — see compute-response.reason for which condition failed."],"authoritative_source":"compute-response.reason"},"capital_gain_lots_need_review":{"at_minimum":["a preparer must reconcile the Form 8949 lots against the 1099-B basis, including any §1250 unrecaptured gain, §1256 contracts, or §1091 wash-sale adjustments."],"authoritative_source":"compute-response.reason"},"equity_comp_basis_adjustment_needs_review":{"at_minimum":["a preparer must adjust the equity-comp cost basis on Form 8949 against the 1099-B (missing affirmation/comp/dates/source-ref), or — for a QUALIFYING ISO disposition specifically — review the Form 6251 AMT preference (an AMT-side basis this engine does not model)."],"authoritative_source":"compute-response.reason"},"section_1256_needs_review":{"at_minimum":["a preparer must complete Form 6781 for the §1256 contracts (reconciling the 1099-B box 11), or Form 4797 if the §475(f) mark-to-market election applies."],"authoritative_source":"compute-response.reason"},"digital_asset_needs_review":{"at_minimum":["a preparer must review the digital-asset dispositions on Form 8949 / Form 1099-DA, and any ordinary-income treatment on Schedule 1, Schedule C, or Form 4797."],"authoritative_source":"compute-response.reason"},"schedule_c_needs_review":{"at_minimum":["a preparer must review the Schedule C net and its Schedule SE self-employment tax."],"authoritative_source":"compute-response.reason"},"schedule_c_loss_needs_review":{"at_minimum":["a preparer must apply the §465 at-risk, §469 passive-loss, and §183 hobby-loss limits to the Schedule C loss."],"authoritative_source":"compute-response.reason"},"schedule_c_se_needs_social_security_wages":{"at_minimum":["a preparer must compute the Schedule C net's Schedule SE tax with the taxpayer's W-2 Social Security wages (the §164(f) base is capped across W-2 + SE)."],"authoritative_source":"compute-response.reason"},"schedule_e_needs_review":{"at_minimum":["a preparer must handle the Schedule E rental — the §469 passive-loss limit on Form 8582, the §465 at-risk limit on Form 6198, any §199A QBI on Form 8995, and (for a full-disposition passive-loss release) any interaction with Form 6251 AMT."],"authoritative_source":"compute-response.reason"},"pension_needs_review":{"at_minimum":["a preparer must determine the taxable pension amount from the 1099-R (and any Form 5329 early-distribution tax)."],"authoritative_source":"compute-response.reason"},"social_security_needs_review":{"at_minimum":["a preparer must size the taxable Social Security under §86 using the 1099-INT / RRB-1099 and Form 1040 line 2a inputs (and Form 6251 where AMT interacts)."],"authoritative_source":"compute-response.reason"},"child_tax_credit_needs_review":{"at_minimum":["a preparer must confirm the qualifying-child / other-dependent eligibility for the Child Tax Credit."],"authoritative_source":"compute-response.reason","generic":true},"engine_declined":{"at_minimum":["a preparer must prepare this return; read the decline reason for the specific gap."],"authoritative_source":"compute-response.reason","generic":true}}},"review_states":["match","mismatch","unsupported","needs_review"],"response_uniform_fields":["billed","retry_safe","next_action","reason","provenance"],"billing_semantics":{"computed_200_billable":true,"deterministic_decline_200_billable":true,"validation_4xx_billable":false,"server_5xx_billable":false,"idempotency_key_bills_once":true,"monthly_limit_behavior":"hard_429_cap","overage":"none"},"docs":{"supported_envelope":"https://tax-mcp.com/docs#supported-scope","quickstart":"https://tax-mcp.com/docs/quickstart","openapi":"https://tax-mcp.com/api/openapi.json","roadmap":"https://tax-mcp.com/roadmap"},"affirmations":{"terms":"Caller/preparer attestation fields. Each is a §6694 affirmation the preparer supplies where required; it gates a specific bounded modeled path (see modeled_surfaces) and is not a general capability claim — absent it, that path returns a deterministic decline.","required_fields":["section1256CleanBrokerReportedAffirmed","cleanCoveredNoAdjustmentsAffirmed","scheduleERentalIsPassiveFinalNet","scheduleERentalNotSection162Business","stateIncomeConformsToFederal","itemizedDeductionsAreFinalStateAmount"],"additional_fields":["scheduleERentalActiveParticipationAffirmed","scheduleERentalNoPriorSuspendedPALAffirmed","scheduleERentalAtRiskAffirmed","scheduleERentalNotRealEstateProfessionalAffirmed","scheduleERentalEntireInterestDisposedAffirmed","scheduleERentalFullyTaxableCashSaleAffirmed","scheduleERentalUnrelatedPartyAffirmed","scheduleERentalDispositionAtRiskAffirmed","scheduleCIsSingleSolePropFinalNetAffirmed","pensionDistributionFullyTaxableAffirmed","socialSecurityStandardCaseAffirmed","childTaxCreditChildrenQualifyAffirmed","ctcActcFilerAndSpouseValidSsnAffirmed","otherDependentsQualifyForOdcAffirmed","odcFilerAndSpouseValidTinAffirmed","caUsObligationInterestAffirmed","caScheduleCSelfEmployedForCaPurposesAffirmed","nyScheduleCNoStateBusinessAdjustmentsAffirmed","equityCompBasisIsCompAdjustedAffirmed"]},"not_modeled":{"federal_itemized":"Full federal Schedule A itemized deductions (itemizedDeductions) are not modeled — only the SALT + home-mortgage-interest slice computes; medical/charitable/casualty/misc itemized decline.","amt":"Standalone Alternative Minimum Tax (AMT) is not a caller input. The engine refigures Form 6251 Part III ONLY to carry the modeled special-rate gain (any SUPPORTED_TAX_YEARS year with a derivable 24%-bracket ceiling) through a binding-AMT return; AMT preferences/adjustments beyond that (ISO bargain element, private-activity-bond interest, depreciation preferences) are not modeled.","unrecaptured_1250":"The engine does not DERIVE unrecaptured section 1250 gain from depreciation records. Only a caller-asserted portion of net LT gain (sec1250UnrecapturedGain; any SUPPORTED_TAX_YEARS year with a derivable 24%-bracket ceiling — currently all of 2020-2026) is taxed at its 25%-max layer; an omitted portion is taxed at 0/15/20 — a preparer must supply it.","collectibles_28_percent":"The engine does not identify collectibles from a 1099-B. Only a caller-asserted portion of net LT gain (collectibles28Gain; any SUPPORTED_TAX_YEARS year with a derivable 24%-bracket ceiling — currently all of 2020-2026) is taxed at the 28% layer; otherwise not modeled.","wash_sale":"Wash-sale (§1091) compute is NARROWLY modeled (C-slice-1): a covered A/D box/lot's broker-reported NON-NEGATIVE washSaleDisallowed amount (1099-B box 1g / Form 8949 col-g code-W) is ADDED BACK to the gain — ONLY with BOTH wash affirmations: washSaleDisallowedIsCompleteAffirmed (the amount is the ENTIRE §1091 disallowance incl. cross-account/cross-broker/IRA/spouse replacements per Rev. Rul. 2008-5, and the box is otherwise uniformly clean covered — an under-stated amount under-states the gain; that residual is the preparer's, a loud VERIFY flag fires) AND washSaleLotsNotSpecialRateAffirmed (no lot is §1250-unrecaptured or 28%-collectible property — a separate CHARACTER attestation, never folded into completeness). Encoding: transcribe the col-(g) W amount into washSaleDisallowed; adjustmentCode:'W' + adjustmentAmount still DECLINE (the signed multi-code channel stays closed). Still DECLINING: a wash amount with either affirmation missing; a wash box also carrying cleanCoveredNoAdjustmentsAffirmed (a contradiction — that affirmation attests NO wash exists); a wash amount on an equity-comp lot (stacked adjustment dimensions) or a digital-asset box (§1091 does not apply — contradictory evidence); wash coexisting with caller-asserted sec1250UnrecapturedGain/collectibles28Gain (no per-lot attribution — the engine cannot prove the wash lots are excluded); and the §1091 REPLACEMENT side (basis increase + holding-period tack — lotId/replacementForLotId still decline; the preparer owns the replacement-lot basis adjustment, and a same-year unadjusted replacement sale may OVER-state that lot's gain — over-tax-safe, flagged for reconciliation). The add-back is non-negative by type: it can only increase gain / reduce loss (no loss creation, by construction).","noncovered_basis":"Noncovered lots (basis not reported to the IRS, covered=false, box B/E) are not computed — they decline. A broker Stock-Plan-Supplement adjusted basis is broker-attested, not IRS-reported, and is likewise not modeled.","digital_asset_broad":"Broad digital asset / crypto coverage is not modeled. Only a TY2026+ covered, IRS-reported-basis, purchase-acquired, non-collectible, capital (not ordinary) crypto disposition computes; every other crypto case (pre-2026, Form 1099-DA proceeds-only, noncovered, staking/mining/airdrop income, §408(m) collectible, dealer/ordinary) declines (digital_asset_needs_review).","equity_comp":"Equity compensation: a COVERED (A/D) RSU, NSO, ESPP, or ISO (disqualifying disposition only) lot COMPUTES a comp-adjusted-basis gain when the preparer supplies equityCompOrdinaryIncome (the W-2/1099-NEC ordinary income already taxed at vest/exercise/disposition), affirms it (equityCompBasisIsCompAdjustedAffirmed), AND supplies acquiredDate + soldDate + a sourceDocumentRef (lot provenance) + an ordinaryIncomeSourceRef (comp substantiation) — basis = reportedBasis + that amount (preparer-attested, not IRS-reported; a loud VERIFY flag fires), and the comp-adjusted basis must NOT create a loss. An ISO lot ALSO requires equityCompIsoDisqualifyingDispositionAffirmed:true (fail-closed) — ESPP computes for EITHER a qualifying or disqualifying §423 disposition (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. 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); ISO exercise-and-hold (no disposition — this lot shape has no path to express it, `proceeds` is required); and any lot missing the affirmation, equityCompOrdinaryIncome, dates, sourceDocumentRef, or ordinaryIncomeSourceRef, on a noncovered box, or whose comp adjustment would create/increase a loss, declines.","pass_through_k1":"Pass-through income — Schedule K-1, partnership, and S corporation — is not modeled; a supplied K-1/business surface declines. Business/SSTB/wage-limited §199A QBI (Form 8995-A) is out of scope.","part_year_nonresident":"Part-year and nonresident state returns are not modeled — CA/NY are full-year-resident 2025 only; a part-year or nonresident state return declines (nonresident_or_part_year)."},"commercial_and_retry_semantics":{"computed_200_billable":true,"deterministic_decline_200_billable":true,"validation_4xx_billable":false,"server_5xx_billable":false,"idempotency_key_bills_once":true,"retry_safe":"false for a deterministic decline (it is a successful, final answer — re-sending the same inputs re-declines); true only for a transient server failure (5xx / metering).","next_action":"one of fix_request_and_resubmit (4xx validation / 5xx compute_error), review_inputs (deterministic decline / needs_review), check_credentials (401 auth), upgrade_plan_or_wait_next_period (429 hard cap), retry_after_backoff (transient 5xx / rate limit / metering), retry_after_inflight_completes (idempotency in-progress), use_new_idempotency_key (idempotency-key reused with a changed body), or none (successful compute).","idempotency_terms":["Idempotency-Key","idempotency_key_reused","idempotency_key_in_progress"],"rate_limit":"Monthly quota is a hard_429_cap (no overage billing); a 429 rate limit / monthly limit response directs the caller to upgrade_plan_or_wait_next_period. A 429 is NOT billable.","per_scenario_workflows":"/what-if and /review-packet fan ONE request into up to 25 independent federal computes and bill PER SCENARIO — each computed-or-deterministic-decline slot is one billable unit (like a standalone federal compute); per-slot validation/compute errors and quota-cut slots are NOT billed. Idempotency-Key is MANDATORY on these two (absent → 400, unlike the single-compute endpoints where it is optional); the per-minute rate limit counts N (not 1). A same-body replay bills zero extra; a changed scenario-set under the same key → 409 idempotency_key_reused. These are federal-only and present-not-conclude: /what-if returns N INDEPENDENT results with NO comparison/ranking; /review-packet assembles N items with NO cross-scenario total/summary/aggregate."},"legal_notice":{"ref":"https://tax-mcp.com/terms#compute-notice","version":"v1","present_on":"every computed:true compute 200 and every reconcile/workflow 200 (any status: match/mismatch/unsupported/needs_review)","absent_from":"compute 200 declines (computed:false) and all non-200 responses","note":"/terms governs ALL responses including declines and errors; legal_notice is a per-success echo of /terms, and its absence never means the Terms do not apply."},"decline_binding":{"response_uniform_fields":["computed","code","reason","billed","retry_safe","next_action"],"no_tax_value_leak":true,"forbidden_decline_tax_fields":["taxableIncome","stateTaxableIncome","incomeTax","totalTax","owedOrRefund","lines","additionalTaxes"],"semantics":["deterministic decline","successful answer","not retry"]}}