Multi-State Tax Optimization Pack

Why this Data Set exists

Multi-state tax used to be solvable with a residency calendar and an apportionment formula. Three things changed that. First, remote work made dual-state employment normal — a worker living in NJ but employed by an NY-headquartered firm now triggers NY's convenience-of-employer rule, which most planning tools don't handle. Second, MA's millionaires tax surcharge created a state-specific bracket structure that interacts non-trivially with relocation timing. Third, digital nomads — workers without a fixed-domicile state at all — created a planning category that simply didn't exist five years ago.

For planning tools, this means state tax logic that used to be 'pick the residency state, apply that state's rates' now needs to handle: residency-change events with prorated multi-state filings; source-state income allocation that separates W-2 wages from RSU vesting from K-1 distributions from real-estate-located income; convenience-of-employer rules that override the location-of-work analysis for specific state pairs; and state-specific surtax brackets. None of this fits the generic 'apply state rate' approach most tools use.

This Data Set provides 320 households where this complexity is structurally expressed: residency-change event histories, source-state allocation per income type, properties-by-state real estate inventories, and state-specific flags for the surtax structures (MA, CA, NY-convenience-of-employer) that drive most state-level planning value.

Use Cases

Who uses this Data Set

What's inside

The 320 households span twelve archetypes intentionally chosen for state-tax complexity: tech workers in HCOL states, dual-income professionals across state lines, peak earners with concentrated equity tied to their employment state, HNW retirees considering relocation, FIRE achievers who moved to no-income-tax states, real estate investors with multi-state property, digital nomads, and pre-IPO founders timing relocations against liquidity events.

Every household has structured tax-residency data: primary state, residency history (with each change event timestamped and reasoned), and where applicable, dual residency status. Source-state income allocation breaks down income by type and source state — W-2 wages allocated to the location-of-work state (with convenience-of-employer overrides flagged), stock-option exercise income tied to the state-where-vested, K-1 distributions allocated to the entity's state, real estate income located to the property state. Properties-by-state real estate inventories are structured with current valuations and rental-income status. State-specific surtax flags pre-populate for households whose income or wealth places them above the relevant thresholds (MA $1M, CA $1M for mental health services tax, NY high-earner surcharge). Digital-nomad households carry a `domicile_state: null` flag with the 12-month state-presence history.

The Data Set ships as JSON, CSV, and Parquet. The WealthSynth Methodology PDF documents the residency-change event taxonomy, the source-state allocation methodology (with citations to the FTA's apportionment-rule database), the convenience-of-employer rule states (currently NY, NE, PA, AR, DE — though this list changes), and the surtax structures by state.

Preview a sample household

A redacted summary of one household from this Data Set — names, employers, exact balances, and metro area are stripped. Ages are bucketed, income and net worth are reported as bands. The full record (and all 320 like it) ships in the ZIP.

Technical Highlights

Sample Schema Fields

{
  "tax_residency.primary_state": <value>,
  "tax_residency.history[]": <value>,
  "income.source_state_allocation": <value>,
  "real_estate.properties_by_state": <value>,
  "events.relocation_events": <value>
}

Sample queries

households.filter(h =>
  ['CA', 'NY', 'NJ'].includes(h.tax_residency.primary_state) &&
  h.equity_comp.grants?.some(g =>
    g.vesting_schedule.some(v =>
      monthsBetween(today(), v.vest_date) <= 12)) &&
  !h.events.relocation_events?.some(e =>
    daysSinceEvent(e) < 180)
)

households.filter(h => {
  const hqState = h.income.employer_hq_state;
  const homeState = h.tax_residency.primary_state;
  const convenienceStates = ['NY', 'NE', 'PA', 'AR', 'DE'];
  return convenienceStates.includes(hqState) && hqState !== homeState;
})

households.flatMap(h =>
  h.tax_residency.history.filter(c =>
    c.change_date.startsWith(currentTaxYear)
  ).map(c => ({
    household: h.id,
    from_state: c.from_state,
    to_state: c.to_state,
    change_date: c.change_date,
    days_in_from_state: daysInYearBefore(c.change_date),
    days_in_to_state: daysInYearAfter(c.change_date)
  }))
)

households.filter(h =>
  h.tax_residency.primary_state === null &&
  Math.max(...Object.values(h.tax_residency.days_by_state)) < 183
)

Methodology

Each household's state-tax profile is generated against archetype-specific patterns. Tech workers and dual-income professionals are sampled with realistic distributions of HCOL state residency (CA, NY, MA, WA dominant) plus the realistic relocation-rate distribution (about 6% of high-income tech workers relocate per year, weighted toward FL, TX, NV destinations). Source-state income allocation uses the FTA's apportionment-rule database for each state pair. Convenience-of-employer rule states (NY, NE, PA, AR, DE) are correctly flagged where the household's home state differs from the employer HQ state. State-specific surtax thresholds (MA $1M, CA $1M, NY high-earner) are applied based on actual household income. Digital-nomad households (about 8% of the corpus) carry the 12-month state-presence history needed for the planning question. The corpus passes the WealthSynth consistency validator (state tax math reconciles, residency-change events have valid date sequencing, source-state allocation sums correctly across income types) and the LLM-as-judge gate. Annual refresh tracks state-level tax changes (rate increases, surtax brackets, conformity changes).

Included Archetypes (12)

Frequently asked questions