Relocation state tax driver savings

For a candidate state, tax with a feature neutralized minus tax as modeled: Social Security treatment, retirement-income exclusion, public-pension exclusion, capital-gains treatment.

Field: State tax driver savings Unit: US dollars Basis: nominal dollars Computed by: Engine Status: Complete chain

Appears in: relocation-page (Drivers panel rows)

Calculation records

• Relocation state tax driver savings Composition record, justified by derivation

  Purpose: Attribute lifetime state-tax savings to one neutralized state feature at a time.

  Statement: projection/relocation.ts#computeDrivers publishes each destination-state driver saving in nominal lifetime dollars as the sum of state-plus-local tax with that one feature neutralized minus the sum actually modeled, with public-pension savings fixed at zero when the state uses one shared retirement rule.

  Formula: savings_d = sum over years y of (tax_neutralized(d, y) - tax_actual(y))

  • tax_neutralized(d, y): Year y tax re-priced with feature d neutralized (unit: nominal USD) (domain: nonnegative)
  • tax_actual(y): Year y tax the ledger actually charged (unit: nominal USD) (domain: nonnegative)

  Timing: every recorded tax year, one feature at a time

  Rounding: none stated; capital-gains savings may be negative

  Limits:

  • Changing one feature at a time makes this an attribution, not an additive decomposition: the four savings are not guaranteed to sum to total tax, and capital-gains savings are explicitly allowed to be negative. Reversing the counterfactual subtraction flips every sign. No result is claimed for unmodeled or flat-override rows, whose drivers are null. The pin is a non-exported function, so the evidence asserts it through the exported compareRelocationCandidates, with the worksheet's actual and neutralized year tables supplied by a calculator injected at the createStateTaxCalculator seam; any probe outside those tables is refused rather than guessed.

  Provenance: derived by codex, implemented by claude.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: relocation-state-tax-driver-savings.md Mutation receipt: relocation-state-tax-driver-savings.mutation.md

  Evidence tests: relocation.evidence.test.ts

  Implemented in: relocation.ts

  Is the number of: relocation-state-tax-driver-savings

Engine source: engine/src/projection/relocation.ts (RelocationDrivers.ssTreatmentSavings / retirementExclusionSavings / publicPensionExclusionSavings / capitalGainsTreatmentSavings)