From baa2d439b6010b1c750aac795085fc6799d29515 Mon Sep 17 00:00:00 2001 From: PavelMakarchuk Date: Tue, 23 Jun 2026 13:34:27 -0400 Subject: [PATCH] Dashboard docs: document MFJ spousal income allocation + TAXSIM caveats Add a 'Spousal income allocation' section to the Variable Mappings (input) tab explaining how the emulator splits single-column household income between spouses: 50/50 for interest/dividends/capital gains/S-corp; age-aware for pensions and Social Security (same-side -> 50/50, mixed-age -> older spouse). Documents the two known TAXSIM-alignment caveats (age-independent per-person exclusions in mixed-age couples; higher-threshold states straddling age 55). Co-Authored-By: Claude Opus 4.8 (1M context) --- changelog.d/doc-spousal-allocation.changed.md | 1 + .../src/components/DocumentationContent.jsx | 46 +++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 changelog.d/doc-spousal-allocation.changed.md diff --git a/changelog.d/doc-spousal-allocation.changed.md b/changelog.d/doc-spousal-allocation.changed.md new file mode 100644 index 00000000..28a0f6b5 --- /dev/null +++ b/changelog.d/doc-spousal-allocation.changed.md @@ -0,0 +1 @@ +Document the MFJ spousal income allocation rule (50/50 for interest/dividends/capital gains/S-corp; age-aware for pensions and Social Security) and its TAXSIM-alignment caveats on the dashboard Variable Mappings (input) page. diff --git a/dashboard/src/components/DocumentationContent.jsx b/dashboard/src/components/DocumentationContent.jsx index 13261f42..41f942f2 100644 --- a/dashboard/src/components/DocumentationContent.jsx +++ b/dashboard/src/components/DocumentationContent.jsx @@ -943,6 +943,52 @@ policyengine-taxsim policyengine input.csv --disable-salt --assume-w2-wages --lo * Adjusted to match TAXSIM methodology: perturbs employment income (wages) only, splits perturbation proportionally between spouses, and uses a $100 delta for numerical stability with PolicyEngine's float32 internals.

)} + + {activeTab === 'input' && ( +
+

+ Spousal income allocation (married filing jointly) +

+

+ TAXSIM provides several income types as a single household total with no + per-spouse split. For joint filers, the emulator allocates them between + spouses before PolicyEngine computes per-person state provisions: +

+
    +
  • + Interest, dividends, capital gains, S-corp income → + always split 50/50. +
    • +
  • + Pensions & Social Security → age-aware: + when both spouses are on the same side of the + elderly-eligibility line (both qualify, or both do not) → + 50/50; in mixed-age couples the whole + amount goes to the older spouse, so age-based state + exclusions (CO 55, DE 60, GA 62, MD 65) reach the + qualifying filer. +
    • +
+
+ Known alignment caveats. The + pension/Social Security split uses a single age-55 threshold, while TAXSIM + keys off each state's actual exclusion structure. Two cases can + therefore differ from the NBER binary: +
    +
  • + Age-independent per-person exclusions (e.g. KY $31,110, + OK $10,000) in mixed-age couples — TAXSIM effectively splits + 50/50, while the convention assigns the income to the older spouse. +
    • +
  • + Higher-threshold states (DE/GA/MD) where both spouses are + 55+ but straddle the state's line — the convention splits 50/50, + while TAXSIM assigns it to the older spouse. +
    • +
+
+
+ )} } )}