@markcolabs/mcp 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +9 -35
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +52 -285
- package/dist/index.js.map +1 -1
- package/package.json +7 -12
- package/LICENSE-API.md +0 -111
- package/dist/disclaimers/ymyl.d.ts +0 -16
- package/dist/disclaimers/ymyl.d.ts.map +0 -1
- package/dist/disclaimers/ymyl.js +0 -20
- package/dist/disclaimers/ymyl.js.map +0 -1
- package/dist/engines/compoundInterest.d.ts +0 -75
- package/dist/engines/compoundInterest.d.ts.map +0 -1
- package/dist/engines/compoundInterest.js +0 -74
- package/dist/engines/compoundInterest.js.map +0 -1
- package/dist/engines/data/federalTax.d.ts +0 -47
- package/dist/engines/data/federalTax.d.ts.map +0 -1
- package/dist/engines/data/federalTax.js +0 -111
- package/dist/engines/data/federalTax.js.map +0 -1
- package/dist/engines/data/irs2026.d.ts +0 -137
- package/dist/engines/data/irs2026.d.ts.map +0 -1
- package/dist/engines/data/irs2026.js +0 -113
- package/dist/engines/data/irs2026.js.map +0 -1
- package/dist/engines/data/rmd2026.d.ts +0 -59
- package/dist/engines/data/rmd2026.d.ts.map +0 -1
- package/dist/engines/data/rmd2026.js +0 -75
- package/dist/engines/data/rmd2026.js.map +0 -1
- package/dist/engines/data/ssa.d.ts +0 -39
- package/dist/engines/data/ssa.d.ts.map +0 -1
- package/dist/engines/data/ssa.js +0 -55
- package/dist/engines/data/ssa.js.map +0 -1
- package/dist/engines/data/stateTax2026.d.ts +0 -114
- package/dist/engines/data/stateTax2026.d.ts.map +0 -1
- package/dist/engines/data/stateTax2026.js +0 -348
- package/dist/engines/data/stateTax2026.js.map +0 -1
- package/dist/engines/hsa.d.ts +0 -110
- package/dist/engines/hsa.d.ts.map +0 -1
- package/dist/engines/hsa.js +0 -83
- package/dist/engines/hsa.js.map +0 -1
- package/dist/engines/ira.d.ts +0 -115
- package/dist/engines/ira.d.ts.map +0 -1
- package/dist/engines/ira.js +0 -127
- package/dist/engines/ira.js.map +0 -1
- package/dist/engines/mortgage.d.ts +0 -70
- package/dist/engines/mortgage.d.ts.map +0 -1
- package/dist/engines/mortgage.js +0 -60
- package/dist/engines/mortgage.js.map +0 -1
- package/dist/engines/paycheck.d.ts +0 -128
- package/dist/engines/paycheck.d.ts.map +0 -1
- package/dist/engines/paycheck.js +0 -142
- package/dist/engines/paycheck.js.map +0 -1
- package/dist/engines/retirement401k.d.ts +0 -109
- package/dist/engines/retirement401k.d.ts.map +0 -1
- package/dist/engines/retirement401k.js +0 -130
- package/dist/engines/retirement401k.js.map +0 -1
- package/dist/engines/rmd.d.ts +0 -107
- package/dist/engines/rmd.d.ts.map +0 -1
- package/dist/engines/rmd.js +0 -109
- package/dist/engines/rmd.js.map +0 -1
- package/dist/engines/rothConversion.d.ts +0 -124
- package/dist/engines/rothConversion.d.ts.map +0 -1
- package/dist/engines/rothConversion.js +0 -145
- package/dist/engines/rothConversion.js.map +0 -1
- package/dist/engines/socialSecurity.d.ts +0 -63
- package/dist/engines/socialSecurity.d.ts.map +0 -1
- package/dist/engines/socialSecurity.js +0 -139
- package/dist/engines/socialSecurity.js.map +0 -1
- package/dist/envelope.d.ts +0 -76
- package/dist/envelope.d.ts.map +0 -1
- package/dist/envelope.js +0 -34
- package/dist/envelope.js.map +0 -1
- package/dist/shared/bounds.d.ts +0 -133
- package/dist/shared/bounds.d.ts.map +0 -1
- package/dist/shared/bounds.js +0 -206
- package/dist/shared/bounds.js.map +0 -1
- package/dist/tools/compoundInterest.d.ts +0 -48
- package/dist/tools/compoundInterest.d.ts.map +0 -1
- package/dist/tools/compoundInterest.js +0 -107
- package/dist/tools/compoundInterest.js.map +0 -1
- package/dist/tools/hsa.d.ts +0 -58
- package/dist/tools/hsa.d.ts.map +0 -1
- package/dist/tools/hsa.js +0 -129
- package/dist/tools/hsa.js.map +0 -1
- package/dist/tools/ira.d.ts +0 -55
- package/dist/tools/ira.d.ts.map +0 -1
- package/dist/tools/ira.js +0 -117
- package/dist/tools/ira.js.map +0 -1
- package/dist/tools/mortgage.d.ts +0 -51
- package/dist/tools/mortgage.d.ts.map +0 -1
- package/dist/tools/mortgage.js +0 -112
- package/dist/tools/mortgage.js.map +0 -1
- package/dist/tools/paycheck.d.ts +0 -61
- package/dist/tools/paycheck.d.ts.map +0 -1
- package/dist/tools/paycheck.js +0 -135
- package/dist/tools/paycheck.js.map +0 -1
- package/dist/tools/retirement401k.d.ts +0 -85
- package/dist/tools/retirement401k.d.ts.map +0 -1
- package/dist/tools/retirement401k.js +0 -141
- package/dist/tools/retirement401k.js.map +0 -1
- package/dist/tools/rmd.d.ts +0 -60
- package/dist/tools/rmd.d.ts.map +0 -1
- package/dist/tools/rmd.js +0 -130
- package/dist/tools/rmd.js.map +0 -1
- package/dist/tools/rothConversion.d.ts +0 -66
- package/dist/tools/rothConversion.d.ts.map +0 -1
- package/dist/tools/rothConversion.js +0 -141
- package/dist/tools/rothConversion.js.map +0 -1
- package/dist/tools/socialSecurity.d.ts +0 -51
- package/dist/tools/socialSecurity.d.ts.map +0 -1
- package/dist/tools/socialSecurity.js +0 -117
- package/dist/tools/socialSecurity.js.map +0 -1
- package/dist/util/zod-to-json-schema.d.ts +0 -28
- package/dist/util/zod-to-json-schema.d.ts.map +0 -1
- package/dist/util/zod-to-json-schema.js +0 -98
- package/dist/util/zod-to-json-schema.js.map +0 -1
package/dist/engines/rmd.js
DELETED
|
@@ -1,109 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* RMD (Required Minimum Distribution) engine — lifted from
|
|
3
|
-
* site/src/utils/rmd-engine.js (functions `calculateRMD`,
|
|
4
|
-
* `getDistributionPeriod`, `getRMDStartAge`).
|
|
5
|
-
*
|
|
6
|
-
* Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
|
|
7
|
-
* parity test against the site source as the gate.
|
|
8
|
-
*
|
|
9
|
-
* Scope (S141 Wave 1B Item #3): SINGLE-YEAR RMD distribution-amount
|
|
10
|
-
* calculation only. The site calculator's multi-year projection
|
|
11
|
-
* (`generateRMDProjection`) and pre-RMD age-projection path are OUT of
|
|
12
|
-
* scope for v1 — callers needing year-by-year projections should call the
|
|
13
|
-
* tool repeatedly with the projected balance for each year.
|
|
14
|
-
*
|
|
15
|
-
* Table coverage: ONLY the Uniform Lifetime Table (Pub. 590-B Table III,
|
|
16
|
-
* post-2022 version) is implemented, mirroring the site source which uses
|
|
17
|
-
* `UNIFORM_LIFETIME_TABLE` exclusively. The Joint Life Expectancy Table
|
|
18
|
-
* (Table II, applied when spouse is sole beneficiary AND 10+ years younger)
|
|
19
|
-
* is NOT in the site engine and is therefore NOT in this tool — adding it
|
|
20
|
-
* here would create a parity gap with the site calculator. The `tableUsed`
|
|
21
|
-
* field is always `"uniform-lifetime"` for v1; the union type leaves room
|
|
22
|
-
* for `"joint-life-expectancy"` in a future minor bump when the site adds it.
|
|
23
|
-
*
|
|
24
|
-
* Math reference (per IRC §401(a)(9) + Pub. 590-B):
|
|
25
|
-
* distributionPeriod = UNIFORM_LIFETIME_TABLE[ownerAge]
|
|
26
|
-
* rmdAmount = accountBalance / distributionPeriod
|
|
27
|
-
*
|
|
28
|
-
* Missed-RMD penalty (SECURE 2.0 §302, effective 2023+):
|
|
29
|
-
* penaltyIfMissed = rmdAmount × 0.25 (default 25% excise tax)
|
|
30
|
-
* reduced to 10% if corrected within IRS correction window (typically 2 years)
|
|
31
|
-
* (down from 50% pre-SECURE-2.0)
|
|
32
|
-
*
|
|
33
|
-
* Source: IRS Publication 590-B (Uniform Lifetime Table III, post-2022) +
|
|
34
|
-
* SECURE 2.0 Act §107 (RMD age tiers) + §302 (25% excise tax).
|
|
35
|
-
* Last verified: 2026-05-27.
|
|
36
|
-
*/
|
|
37
|
-
import { UNIFORM_LIFETIME_TABLE_2026, UNIFORM_LIFETIME_MIN_AGE, UNIFORM_LIFETIME_MAX_AGE, RMD_MISSED_EXCISE_RATE, RMD_TABLE_SOURCE, } from "./data/rmd2026.js";
|
|
38
|
-
/**
|
|
39
|
-
* SemVer of the RMD engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041
|
|
40
|
-
* Position #4a): major bump = math change; minor = additive output; patch =
|
|
41
|
-
* numerical correction. NOT bumped for cosmetic refactors.
|
|
42
|
-
* - 1.0.0: initial v1 lift from rmd-engine.js (S141 Wave 1B).
|
|
43
|
-
*/
|
|
44
|
-
export const ENGINE_VERSION = "1.0.0";
|
|
45
|
-
/**
|
|
46
|
-
* Compute the required minimum distribution for the given inputs.
|
|
47
|
-
*
|
|
48
|
-
* 1-to-1 logic port of site/src/utils/rmd-engine.js `calculateRMD` +
|
|
49
|
-
* `getDistributionPeriod` (single-year path; multi-year projection out of
|
|
50
|
-
* scope). The site engine clamps lookups to [72, 120]; we additionally
|
|
51
|
-
* require ownerAge ≥ 73 (SECURE 2.0 floor for the 1951-1959 cohort, the
|
|
52
|
-
* common case in 2026) at the tool boundary via RMD_BOUNDS.
|
|
53
|
-
*
|
|
54
|
-
* Throws on undefined-period lookup — should be unreachable because bounds
|
|
55
|
-
* validation in the tool wrapper rejects out-of-range ages first.
|
|
56
|
-
*/
|
|
57
|
-
export function distributionAmount(input) {
|
|
58
|
-
const { accountBalance, ownerAge } = input;
|
|
59
|
-
// Edge: zero balance → zero RMD. Mirror the site's balance ≤ 0 short-circuit
|
|
60
|
-
// but still report the (clamped) distribution period for caller transparency.
|
|
61
|
-
if (accountBalance <= 0) {
|
|
62
|
-
const factor = lookupDistributionPeriod(ownerAge);
|
|
63
|
-
return {
|
|
64
|
-
rmdAmount: 0,
|
|
65
|
-
distributionPeriod: factor,
|
|
66
|
-
lifeExpectancyFactor: factor,
|
|
67
|
-
tableUsed: "uniform-lifetime",
|
|
68
|
-
penaltyIfMissed: 0,
|
|
69
|
-
meta: {
|
|
70
|
-
tableYear: 2026,
|
|
71
|
-
source: RMD_TABLE_SOURCE,
|
|
72
|
-
},
|
|
73
|
-
};
|
|
74
|
-
}
|
|
75
|
-
const distributionPeriod = lookupDistributionPeriod(ownerAge);
|
|
76
|
-
// Site rounds to cents (Math.round * 100 / 100). Keep the same rounding for
|
|
77
|
-
// parity correctness in the test file.
|
|
78
|
-
const rmdRaw = accountBalance / distributionPeriod;
|
|
79
|
-
const rmdAmount = Math.round(rmdRaw * 100) / 100;
|
|
80
|
-
const penaltyIfMissed = Math.round(rmdAmount * RMD_MISSED_EXCISE_RATE * 100) / 100;
|
|
81
|
-
return {
|
|
82
|
-
rmdAmount,
|
|
83
|
-
distributionPeriod,
|
|
84
|
-
lifeExpectancyFactor: distributionPeriod,
|
|
85
|
-
tableUsed: "uniform-lifetime",
|
|
86
|
-
penaltyIfMissed,
|
|
87
|
-
meta: {
|
|
88
|
-
tableYear: 2026,
|
|
89
|
-
source: RMD_TABLE_SOURCE,
|
|
90
|
-
},
|
|
91
|
-
};
|
|
92
|
-
}
|
|
93
|
-
/**
|
|
94
|
-
* Look up the distribution period from the Uniform Lifetime Table.
|
|
95
|
-
* Mirrors site `getDistributionPeriod`: clamps to [72, 120] and floors
|
|
96
|
-
* fractional ages.
|
|
97
|
-
*/
|
|
98
|
-
function lookupDistributionPeriod(age) {
|
|
99
|
-
const lookupAge = Math.min(Math.max(Math.floor(age), UNIFORM_LIFETIME_MIN_AGE), UNIFORM_LIFETIME_MAX_AGE);
|
|
100
|
-
const factor = UNIFORM_LIFETIME_TABLE_2026[lookupAge];
|
|
101
|
-
if (factor === undefined) {
|
|
102
|
-
// Defensive: bounds validation should prevent this. If we ever hit it,
|
|
103
|
-
// throwing surfaces it as INTERNAL via the tool wrapper rather than
|
|
104
|
-
// silently returning NaN.
|
|
105
|
-
throw new Error(`RMD: no distribution-period factor for age ${age} (lookupAge=${lookupAge})`);
|
|
106
|
-
}
|
|
107
|
-
return factor;
|
|
108
|
-
}
|
|
109
|
-
//# sourceMappingURL=rmd.js.map
|
package/dist/engines/rmd.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"rmd.js","sourceRoot":"","sources":["../../src/engines/rmd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EACL,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAuDtC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAiC;IAEjC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAE3C,6EAA6E;IAC7E,8EAA8E;IAC9E,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;QAClD,OAAO;YACL,SAAS,EAAE,CAAC;YACZ,kBAAkB,EAAE,MAAM;YAC1B,oBAAoB,EAAE,MAAM;YAC5B,SAAS,EAAE,kBAAkB;YAC7B,eAAe,EAAE,CAAC;YAClB,IAAI,EAAE;gBACJ,SAAS,EAAE,IAAI;gBACf,MAAM,EAAE,gBAAgB;aACzB;SACF,CAAC;IACJ,CAAC;IAED,MAAM,kBAAkB,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAE9D,4EAA4E;IAC5E,uCAAuC;IACvC,MAAM,MAAM,GAAG,cAAc,GAAG,kBAAkB,CAAC;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;IAEjD,MAAM,eAAe,GACnB,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,sBAAsB,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;IAE7D,OAAO;QACL,SAAS;QACT,kBAAkB;QAClB,oBAAoB,EAAE,kBAAkB;QACxC,SAAS,EAAE,kBAAkB;QAC7B,eAAe;QACf,IAAI,EAAE;YACJ,SAAS,EAAE,IAAI;YACf,MAAM,EAAE,gBAAgB;SACzB;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,wBAAwB,CAAC,GAAW;IAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CACxB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,wBAAwB,CAAC,EACnD,wBAAwB,CACzB,CAAC;IACF,MAAM,MAAM,GAAG,2BAA2B,CAAC,SAAS,CAAC,CAAC;IACtD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,uEAAuE;QACvE,oEAAoE;QACpE,0BAA0B;QAC1B,MAAM,IAAI,KAAK,CACb,8CAA8C,GAAG,eAAe,SAAS,GAAG,CAC7E,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
|
|
@@ -1,124 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Roth Conversion tax-impact engine — lifted from
|
|
3
|
-
* site/src/pages/roth-conversion-calculator/roth-conversion-calculator.js
|
|
4
|
-
* (functions in tax-brackets.js + calculateBreakEvenYears) and
|
|
5
|
-
* site/src/utils/tax-brackets.js (calculateIncrementalTax, getMarginalRate).
|
|
6
|
-
*
|
|
7
|
-
* Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
|
|
8
|
-
* parity test against the source site engine.
|
|
9
|
-
*
|
|
10
|
-
* Scope (S141 Wave 1A Item #2, per S141 Risk #2): SINGLE-CONVERSION tax
|
|
11
|
-
* impact only. Multi-year scenario simulation / optimization is deferred to a
|
|
12
|
-
* future tool (`dc.calculator.rothConversion.multiYearOptimization`). This
|
|
13
|
-
* tool answers "if I convert $X today, what's my federal tax owed?" and
|
|
14
|
-
* "when do I break even on the upfront tax?"
|
|
15
|
-
*
|
|
16
|
-
* NOT MODELED (intentional scope limits):
|
|
17
|
-
* - State tax on the conversion (caller's responsibility; conversion is
|
|
18
|
-
* typically taxed by state at ordinary-income rates).
|
|
19
|
-
* - IRMAA tier impact (the site calculator surfaces this; out of scope for
|
|
20
|
-
* the MCP v0.3.0 tool).
|
|
21
|
-
* - 5-year rule timing for individual contributions (we report whether the
|
|
22
|
-
* 5-year rule applies based on age < 59.5, but don't model the per-
|
|
23
|
-
* conversion clock).
|
|
24
|
-
*
|
|
25
|
-
* Math reference:
|
|
26
|
-
* For taxable income I and conversion amount C:
|
|
27
|
-
* beforeTax = bracketTax(I, brackets[filingStatus])
|
|
28
|
-
* afterTax = bracketTax(I + C, brackets[filingStatus])
|
|
29
|
-
* taxOwed = afterTax − beforeTax (incremental)
|
|
30
|
-
* marginalRate = top bracket spanned by (I + C)
|
|
31
|
-
* effectiveRate = taxOwed / C
|
|
32
|
-
*
|
|
33
|
-
* Break-even years (when conversion tax savings recoup themselves, given
|
|
34
|
-
* the user's retirement marginal rate is lower than the conversion
|
|
35
|
-
* marginal rate and tax-free Roth growth at real return r):
|
|
36
|
-
* If retirementMarginalRate >= conversionMarginalRate → 0
|
|
37
|
-
* (already break-even because future bracket ≥ today's)
|
|
38
|
-
* Else:
|
|
39
|
-
* savingsPerYear ≈ futureBalance × (conversionMarginalRate −
|
|
40
|
-
* retirementMarginalRate)
|
|
41
|
-
* breakEvenYears = log((1 − totalConvRate) / (1 − totalFutureRate))
|
|
42
|
-
* / log(1 + r)
|
|
43
|
-
* (where totalConvRate ≈ effectiveRateOnConversion,
|
|
44
|
-
* totalFutureRate ≈ retirementMarginalRate)
|
|
45
|
-
*
|
|
46
|
-
* This is the same break-even math the site `calculateBreakEvenYears`
|
|
47
|
-
* function uses (we drop the explicit state-tax term; caller-side).
|
|
48
|
-
*
|
|
49
|
-
* Source: IRS Rev. Proc. 2025-32 (2026 federal tax brackets).
|
|
50
|
-
* Last verified: 2026-05-09.
|
|
51
|
-
*/
|
|
52
|
-
import { type FilingStatus } from "./data/federalTax.js";
|
|
53
|
-
/**
|
|
54
|
-
* SemVer of the Roth conversion engine. Per ADR-0039 § 5 (reaffirmed in
|
|
55
|
-
* ADR-0041 Position #4a): major bump = math change; minor = additive output;
|
|
56
|
-
* patch = numerical correction. NOT bumped for cosmetic refactors.
|
|
57
|
-
* - 1.0.0: initial v1 lift from roth-conversion-calculator.js + tax-brackets.js
|
|
58
|
-
* (S141 Wave 1A).
|
|
59
|
-
*/
|
|
60
|
-
export declare const ENGINE_VERSION = "1.0.0";
|
|
61
|
-
/** Inputs to the Roth conversion tax-impact engine. */
|
|
62
|
-
export interface RothConversionTaxImpactInput {
|
|
63
|
-
/** Conversion amount (USD). Must be > 0 to compute taxes. */
|
|
64
|
-
conversionAmount: number;
|
|
65
|
-
/** User's current age (used for 5-year rule flag). */
|
|
66
|
-
age: number;
|
|
67
|
-
/** Federal filing status. */
|
|
68
|
-
filingStatus: FilingStatus;
|
|
69
|
-
/** Current federal taxable income (before adding the conversion), USD. */
|
|
70
|
-
currentTaxableIncome: number;
|
|
71
|
-
/**
|
|
72
|
-
* Expected retirement marginal federal tax rate, whole-number percent
|
|
73
|
-
* (e.g., 12 for 12%). Optional — when omitted, `breakEvenYears` is `null`.
|
|
74
|
-
*/
|
|
75
|
-
retirementMarginalRatePercent?: number;
|
|
76
|
-
/**
|
|
77
|
-
* Expected real (inflation-adjusted) annual return on the converted Roth
|
|
78
|
-
* balance, whole-number percent. Defaults to 7 (a reasonable real-return
|
|
79
|
-
* assumption for a diversified portfolio). Used only for break-even math.
|
|
80
|
-
*/
|
|
81
|
-
expectedReturnPercent?: number;
|
|
82
|
-
}
|
|
83
|
-
/** Result payload returned by the engine. */
|
|
84
|
-
export interface RothConversionTaxImpactResult {
|
|
85
|
-
/** Incremental federal income tax on the conversion amount, USD. */
|
|
86
|
-
taxOwed: number;
|
|
87
|
-
/**
|
|
88
|
-
* Top marginal federal bracket the conversion pushes the user into,
|
|
89
|
-
* expressed as a decimal (e.g., 0.32 for 32%).
|
|
90
|
-
*/
|
|
91
|
-
marginalRateOnConversion: number;
|
|
92
|
-
/** taxOwed / conversionAmount, as a decimal. 0 if conversionAmount = 0. */
|
|
93
|
-
effectiveRateOnConversion: number;
|
|
94
|
-
/**
|
|
95
|
-
* Whether the Roth 5-year rule clock applies for this conversion:
|
|
96
|
-
* true if user is under age 59.5 at conversion. (Conversions made when
|
|
97
|
-
* the account holder is < 59.5 incur a separate 5-year clock for
|
|
98
|
-
* penalty-free withdrawal of converted principal.)
|
|
99
|
-
*/
|
|
100
|
-
fiveYearRuleApplies: boolean;
|
|
101
|
-
/**
|
|
102
|
-
* Years until tax-free Roth growth offsets the upfront conversion tax,
|
|
103
|
-
* assuming retirementMarginalRate < conversionMarginalRate. `null` if
|
|
104
|
-
* `retirementMarginalRatePercent` was not provided. `0` if retirement
|
|
105
|
-
* rate ≥ conversion rate (already break-even). May be `Infinity` if
|
|
106
|
-
* mathematically unreachable.
|
|
107
|
-
*/
|
|
108
|
-
breakEvenYears: number | null;
|
|
109
|
-
/** Provenance metadata. */
|
|
110
|
-
meta: {
|
|
111
|
-
/** IRS tax year these brackets apply to. */
|
|
112
|
-
tableYear: number;
|
|
113
|
-
/** Source authority. */
|
|
114
|
-
source: string;
|
|
115
|
-
};
|
|
116
|
-
}
|
|
117
|
-
/**
|
|
118
|
-
* Compute Roth conversion tax impact (single conversion).
|
|
119
|
-
*
|
|
120
|
-
* 1-to-1 port of the federal-tax + incremental-tax + marginal-rate +
|
|
121
|
-
* break-even logic the site uses, with state tax / IRMAA omitted per scope.
|
|
122
|
-
*/
|
|
123
|
-
export declare function taxImpact(input: RothConversionTaxImpactInput): RothConversionTaxImpactResult;
|
|
124
|
-
//# sourceMappingURL=rothConversion.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"rothConversion.d.ts","sourceRoot":"","sources":["../../src/engines/rothConversion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,uDAAuD;AACvD,MAAM,WAAW,4BAA4B;IAC3C,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,0EAA0E;IAC1E,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,6CAA6C;AAC7C,MAAM,WAAW,6BAA6B;IAC5C,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,wBAAwB,EAAE,MAAM,CAAC;IACjC,2EAA2E;IAC3E,yBAAyB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAC7B;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2BAA2B;IAC3B,IAAI,EAAE;QACJ,4CAA4C;QAC5C,SAAS,EAAE,MAAM,CAAC;QAClB,wBAAwB;QACxB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AA4BD;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,4BAA4B,GAClC,6BAA6B,CAoE/B"}
|
|
@@ -1,145 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Roth Conversion tax-impact engine — lifted from
|
|
3
|
-
* site/src/pages/roth-conversion-calculator/roth-conversion-calculator.js
|
|
4
|
-
* (functions in tax-brackets.js + calculateBreakEvenYears) and
|
|
5
|
-
* site/src/utils/tax-brackets.js (calculateIncrementalTax, getMarginalRate).
|
|
6
|
-
*
|
|
7
|
-
* Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
|
|
8
|
-
* parity test against the source site engine.
|
|
9
|
-
*
|
|
10
|
-
* Scope (S141 Wave 1A Item #2, per S141 Risk #2): SINGLE-CONVERSION tax
|
|
11
|
-
* impact only. Multi-year scenario simulation / optimization is deferred to a
|
|
12
|
-
* future tool (`dc.calculator.rothConversion.multiYearOptimization`). This
|
|
13
|
-
* tool answers "if I convert $X today, what's my federal tax owed?" and
|
|
14
|
-
* "when do I break even on the upfront tax?"
|
|
15
|
-
*
|
|
16
|
-
* NOT MODELED (intentional scope limits):
|
|
17
|
-
* - State tax on the conversion (caller's responsibility; conversion is
|
|
18
|
-
* typically taxed by state at ordinary-income rates).
|
|
19
|
-
* - IRMAA tier impact (the site calculator surfaces this; out of scope for
|
|
20
|
-
* the MCP v0.3.0 tool).
|
|
21
|
-
* - 5-year rule timing for individual contributions (we report whether the
|
|
22
|
-
* 5-year rule applies based on age < 59.5, but don't model the per-
|
|
23
|
-
* conversion clock).
|
|
24
|
-
*
|
|
25
|
-
* Math reference:
|
|
26
|
-
* For taxable income I and conversion amount C:
|
|
27
|
-
* beforeTax = bracketTax(I, brackets[filingStatus])
|
|
28
|
-
* afterTax = bracketTax(I + C, brackets[filingStatus])
|
|
29
|
-
* taxOwed = afterTax − beforeTax (incremental)
|
|
30
|
-
* marginalRate = top bracket spanned by (I + C)
|
|
31
|
-
* effectiveRate = taxOwed / C
|
|
32
|
-
*
|
|
33
|
-
* Break-even years (when conversion tax savings recoup themselves, given
|
|
34
|
-
* the user's retirement marginal rate is lower than the conversion
|
|
35
|
-
* marginal rate and tax-free Roth growth at real return r):
|
|
36
|
-
* If retirementMarginalRate >= conversionMarginalRate → 0
|
|
37
|
-
* (already break-even because future bracket ≥ today's)
|
|
38
|
-
* Else:
|
|
39
|
-
* savingsPerYear ≈ futureBalance × (conversionMarginalRate −
|
|
40
|
-
* retirementMarginalRate)
|
|
41
|
-
* breakEvenYears = log((1 − totalConvRate) / (1 − totalFutureRate))
|
|
42
|
-
* / log(1 + r)
|
|
43
|
-
* (where totalConvRate ≈ effectiveRateOnConversion,
|
|
44
|
-
* totalFutureRate ≈ retirementMarginalRate)
|
|
45
|
-
*
|
|
46
|
-
* This is the same break-even math the site `calculateBreakEvenYears`
|
|
47
|
-
* function uses (we drop the explicit state-tax term; caller-side).
|
|
48
|
-
*
|
|
49
|
-
* Source: IRS Rev. Proc. 2025-32 (2026 federal tax brackets).
|
|
50
|
-
* Last verified: 2026-05-09.
|
|
51
|
-
*/
|
|
52
|
-
import { FEDERAL_TAX_BRACKETS_2026, } from "./data/federalTax.js";
|
|
53
|
-
/**
|
|
54
|
-
* SemVer of the Roth conversion engine. Per ADR-0039 § 5 (reaffirmed in
|
|
55
|
-
* ADR-0041 Position #4a): major bump = math change; minor = additive output;
|
|
56
|
-
* patch = numerical correction. NOT bumped for cosmetic refactors.
|
|
57
|
-
* - 1.0.0: initial v1 lift from roth-conversion-calculator.js + tax-brackets.js
|
|
58
|
-
* (S141 Wave 1A).
|
|
59
|
-
*/
|
|
60
|
-
export const ENGINE_VERSION = "1.0.0";
|
|
61
|
-
/**
|
|
62
|
-
* Progressive bracket lookup — verbatim port of site `calculateBracketTax`.
|
|
63
|
-
*/
|
|
64
|
-
function bracketTax(taxable, brackets) {
|
|
65
|
-
if (!brackets.length || taxable <= 0)
|
|
66
|
-
return 0;
|
|
67
|
-
for (let i = brackets.length - 1; i >= 0; i--) {
|
|
68
|
-
const b = brackets[i];
|
|
69
|
-
if (taxable > b.min) {
|
|
70
|
-
return b.baseTax + (taxable - b.min) * b.rate;
|
|
71
|
-
}
|
|
72
|
-
}
|
|
73
|
-
return 0;
|
|
74
|
-
}
|
|
75
|
-
/**
|
|
76
|
-
* Get the marginal (top) bracket rate for a given taxable income —
|
|
77
|
-
* verbatim port of site `getMarginalRate` (returns as decimal).
|
|
78
|
-
*/
|
|
79
|
-
function marginalRateFor(taxable, brackets) {
|
|
80
|
-
if (taxable <= 0)
|
|
81
|
-
return brackets[0]?.rate ?? 0;
|
|
82
|
-
for (let i = brackets.length - 1; i >= 0; i--) {
|
|
83
|
-
if (taxable > brackets[i].min)
|
|
84
|
-
return brackets[i].rate;
|
|
85
|
-
}
|
|
86
|
-
return brackets[0]?.rate ?? 0;
|
|
87
|
-
}
|
|
88
|
-
/**
|
|
89
|
-
* Compute Roth conversion tax impact (single conversion).
|
|
90
|
-
*
|
|
91
|
-
* 1-to-1 port of the federal-tax + incremental-tax + marginal-rate +
|
|
92
|
-
* break-even logic the site uses, with state tax / IRMAA omitted per scope.
|
|
93
|
-
*/
|
|
94
|
-
export function taxImpact(input) {
|
|
95
|
-
const { conversionAmount, age, filingStatus, currentTaxableIncome, retirementMarginalRatePercent, expectedReturnPercent = 7, } = input;
|
|
96
|
-
const brackets = FEDERAL_TAX_BRACKETS_2026[filingStatus];
|
|
97
|
-
// Incremental federal tax — bracket walk before + after the conversion.
|
|
98
|
-
const beforeTax = bracketTax(currentTaxableIncome, brackets);
|
|
99
|
-
const afterTax = bracketTax(currentTaxableIncome + conversionAmount, brackets);
|
|
100
|
-
const taxOwed = Math.max(0, afterTax - beforeTax);
|
|
101
|
-
// Marginal rate the conversion pushes us into (top spanned bracket).
|
|
102
|
-
const marginalRateOnConversion = marginalRateFor(currentTaxableIncome + conversionAmount, brackets);
|
|
103
|
-
// Effective rate (averaged across the brackets the conversion spans).
|
|
104
|
-
const effectiveRateOnConversion = conversionAmount > 0 ? taxOwed / conversionAmount : 0;
|
|
105
|
-
// 5-year rule applies for under-59.5 conversions.
|
|
106
|
-
const fiveYearRuleApplies = age < 59.5;
|
|
107
|
-
// Break-even years — only when retirementMarginalRatePercent is provided.
|
|
108
|
-
// We use the same log-ratio form as the site calculator's
|
|
109
|
-
// calculateBreakEvenYears (state tax omitted here per scope).
|
|
110
|
-
let breakEvenYears = null;
|
|
111
|
-
if (typeof retirementMarginalRatePercent === "number") {
|
|
112
|
-
const futureRate = retirementMarginalRatePercent / 100;
|
|
113
|
-
const conversionRate = effectiveRateOnConversion;
|
|
114
|
-
const r = expectedReturnPercent / 100;
|
|
115
|
-
if (futureRate >= conversionRate) {
|
|
116
|
-
// Future tax rate ≥ today's conversion rate → already break-even.
|
|
117
|
-
breakEvenYears = 0;
|
|
118
|
-
}
|
|
119
|
-
else if (conversionRate >= 1) {
|
|
120
|
-
breakEvenYears = Infinity;
|
|
121
|
-
}
|
|
122
|
-
else if (r <= 0) {
|
|
123
|
-
breakEvenYears = Infinity;
|
|
124
|
-
}
|
|
125
|
-
else {
|
|
126
|
-
// log((1 - futureRate) / (1 - conversionRate)) / log(1 + r)
|
|
127
|
-
const numerator = Math.log((1 - futureRate) / (1 - conversionRate));
|
|
128
|
-
const denominator = Math.log(1 + r);
|
|
129
|
-
const raw = numerator / denominator;
|
|
130
|
-
breakEvenYears = raw < 0 ? 0 : raw;
|
|
131
|
-
}
|
|
132
|
-
}
|
|
133
|
-
return {
|
|
134
|
-
taxOwed,
|
|
135
|
-
marginalRateOnConversion,
|
|
136
|
-
effectiveRateOnConversion,
|
|
137
|
-
fiveYearRuleApplies,
|
|
138
|
-
breakEvenYears,
|
|
139
|
-
meta: {
|
|
140
|
-
tableYear: 2026,
|
|
141
|
-
source: "IRS Rev. Proc. 2025-32",
|
|
142
|
-
},
|
|
143
|
-
};
|
|
144
|
-
}
|
|
145
|
-
//# sourceMappingURL=rothConversion.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"rothConversion.js","sourceRoot":"","sources":["../../src/engines/rothConversion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EACL,yBAAyB,GAG1B,MAAM,sBAAsB,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AA4DtC;;GAEG;AACH,SAAS,UAAU,CAAC,OAAe,EAAE,QAAsB;IACzD,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,OAAO,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC/C,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,OAAO,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YACpB,OAAO,CAAC,CAAC,OAAO,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;QAChD,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,OAAe,EAAE,QAAsB;IAC9D,IAAI,OAAO,IAAI,CAAC;QAAE,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;IAChD,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,IAAI,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG;YAAE,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzD,CAAC;IACD,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC;AAChC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CACvB,KAAmC;IAEnC,MAAM,EACJ,gBAAgB,EAChB,GAAG,EACH,YAAY,EACZ,oBAAoB,EACpB,6BAA6B,EAC7B,qBAAqB,GAAG,CAAC,GAC1B,GAAG,KAAK,CAAC;IAEV,MAAM,QAAQ,GAAG,yBAAyB,CAAC,YAAY,CAAC,CAAC;IAEzD,wEAAwE;IACxE,MAAM,SAAS,GAAG,UAAU,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,UAAU,CAAC,oBAAoB,GAAG,gBAAgB,EAAE,QAAQ,CAAC,CAAC;IAC/E,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;IAElD,qEAAqE;IACrE,MAAM,wBAAwB,GAAG,eAAe,CAC9C,oBAAoB,GAAG,gBAAgB,EACvC,QAAQ,CACT,CAAC;IAEF,sEAAsE;IACtE,MAAM,yBAAyB,GAC7B,gBAAgB,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IAExD,kDAAkD;IAClD,MAAM,mBAAmB,GAAG,GAAG,GAAG,IAAI,CAAC;IAEvC,0EAA0E;IAC1E,0DAA0D;IAC1D,8DAA8D;IAC9D,IAAI,cAAc,GAAkB,IAAI,CAAC;IACzC,IAAI,OAAO,6BAA6B,KAAK,QAAQ,EAAE,CAAC;QACtD,MAAM,UAAU,GAAG,6BAA6B,GAAG,GAAG,CAAC;QACvD,MAAM,cAAc,GAAG,yBAAyB,CAAC;QACjD,MAAM,CAAC,GAAG,qBAAqB,GAAG,GAAG,CAAC;QAEtC,IAAI,UAAU,IAAI,cAAc,EAAE,CAAC;YACjC,kEAAkE;YAClE,cAAc,GAAG,CAAC,CAAC;QACrB,CAAC;aAAM,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;YAC/B,cAAc,GAAG,QAAQ,CAAC;QAC5B,CAAC;aAAM,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAClB,cAAc,GAAG,QAAQ,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,4DAA4D;YAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CACxB,CAAC,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,cAAc,CAAC,CACxC,CAAC;YACF,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACpC,MAAM,GAAG,GAAG,SAAS,GAAG,WAAW,CAAC;YACpC,cAAc,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;QACrC,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO;QACP,wBAAwB;QACxB,yBAAyB;QACzB,mBAAmB;QACnB,cAAc;QACd,IAAI,EAAE;YACJ,SAAS,EAAE,IAAI;YACf,MAAM,EAAE,wBAAwB;SACjC;KACF,CAAC;AACJ,CAAC"}
|
|
@@ -1,63 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Social Security estimate engine — lifted from
|
|
3
|
-
* site/src/utils/social-security-engine.js (functions `estimateAIME`,
|
|
4
|
-
* `calculatePIA`, `calculateFRA`, `calculateAdjustedBenefit`,
|
|
5
|
-
* `calculateEarlyReduction`, `calculateDelayedCredit`,
|
|
6
|
-
* `calculateLifetimeBenefits`).
|
|
7
|
-
*
|
|
8
|
-
* Per ADR-0039 § 5: pure synchronous functions, ENGINE_VERSION constant,
|
|
9
|
-
* parity test against the site source as the gate.
|
|
10
|
-
*
|
|
11
|
-
* Math reference (mirrors SSA Publication 05-10035):
|
|
12
|
-
* AIME = (min(salary, ssWageBase) * 0.65 * min(yearsWorked, 35)) / 420
|
|
13
|
-
* (simplified site approximation; exact AIME requires 35-year history)
|
|
14
|
-
* PIA = 0.90 * min(AIME, BP1)
|
|
15
|
-
* + 0.32 * (min(AIME, BP2) - BP1) if AIME > BP1
|
|
16
|
-
* + 0.15 * (AIME - BP2) if AIME > BP2
|
|
17
|
-
* (rounded down to nearest $0.10)
|
|
18
|
-
* benefit_at_claim = PIA * adjustment_factor(claimAge, FRA)
|
|
19
|
-
*
|
|
20
|
-
* Output values are USD monthly benefits (or USD lifetime totals).
|
|
21
|
-
*/
|
|
22
|
-
/**
|
|
23
|
-
* SemVer of the SS engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041 Position #4a):
|
|
24
|
-
* major bump = math change; minor = additive output; patch = numerical correction.
|
|
25
|
-
* NOT bumped for cosmetic refactors.
|
|
26
|
-
* - 0.2.0 (v0.1.0 publish): initial port (S136), shipped under out-of-policy package-surface version.
|
|
27
|
-
* - 1.0.0 (v0.2.0 publish): one-time reset to align with ADR-0039 § 5 per ADR-0041 D4a.
|
|
28
|
-
* Math unchanged.
|
|
29
|
-
*/
|
|
30
|
-
export declare const ENGINE_VERSION = "1.0.0";
|
|
31
|
-
/** Inputs to the SS estimate engine. */
|
|
32
|
-
export interface SocialSecurityEstimateInput {
|
|
33
|
-
/** Birth year (1943-2004 supported). */
|
|
34
|
-
birthYear: number;
|
|
35
|
-
/** Current/final annual earnings, USD. */
|
|
36
|
-
currentEarnings: number;
|
|
37
|
-
/** Claiming age (62..70). */
|
|
38
|
-
claimAge: number;
|
|
39
|
-
/**
|
|
40
|
-
* Years of work earning SS credits. Used in the simplified AIME estimate.
|
|
41
|
-
* Defaults to 35 (the SSA averaging window).
|
|
42
|
-
*/
|
|
43
|
-
yearsWorked?: number;
|
|
44
|
-
/** Life-expectancy assumption for lifetime projection. Default 85. */
|
|
45
|
-
lifeExpectancy?: number;
|
|
46
|
-
}
|
|
47
|
-
/** Result payload returned by the engine. */
|
|
48
|
-
export interface SocialSecurityEstimateResult {
|
|
49
|
-
/** Monthly benefit at Full Retirement Age (PIA), USD. */
|
|
50
|
-
monthlyBenefitAtFRA: number;
|
|
51
|
-
/** Monthly benefit at the user's chosen claim age, USD. */
|
|
52
|
-
adjustedMonthlyBenefit: number;
|
|
53
|
-
/** Total benefit collected from claimAge through lifeExpectancy, USD. */
|
|
54
|
-
lifetimeBenefitProjection: number;
|
|
55
|
-
/** Full Retirement Age in decimal (e.g., 67.0 or 66.5). */
|
|
56
|
-
fraAge: number;
|
|
57
|
-
/** Eligibility year used for bend-point lookup (birthYear + 62). */
|
|
58
|
-
eligibilityYear: number;
|
|
59
|
-
/** Whether bend points are estimated (eligibility year beyond published table). */
|
|
60
|
-
bendPointsEstimated: boolean;
|
|
61
|
-
}
|
|
62
|
-
export declare function estimate(input: SocialSecurityEstimateInput): SocialSecurityEstimateResult;
|
|
63
|
-
//# sourceMappingURL=socialSecurity.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"socialSecurity.d.ts","sourceRoot":"","sources":["../../src/engines/socialSecurity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAQH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,wCAAwC;AACxC,MAAM,WAAW,2BAA2B;IAC1C,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,4BAA4B;IAC3C,yDAAyD;IACzD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,sBAAsB,EAAE,MAAM,CAAC;IAC/B,yEAAyE;IACzE,yBAAyB,EAAE,MAAM,CAAC;IAClC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAsGD,wBAAgB,QAAQ,CACtB,KAAK,EAAE,2BAA2B,GACjC,4BAA4B,CAiC9B"}
|
|
@@ -1,139 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Social Security estimate engine — lifted from
|
|
3
|
-
* site/src/utils/social-security-engine.js (functions `estimateAIME`,
|
|
4
|
-
* `calculatePIA`, `calculateFRA`, `calculateAdjustedBenefit`,
|
|
5
|
-
* `calculateEarlyReduction`, `calculateDelayedCredit`,
|
|
6
|
-
* `calculateLifetimeBenefits`).
|
|
7
|
-
*
|
|
8
|
-
* Per ADR-0039 § 5: pure synchronous functions, ENGINE_VERSION constant,
|
|
9
|
-
* parity test against the site source as the gate.
|
|
10
|
-
*
|
|
11
|
-
* Math reference (mirrors SSA Publication 05-10035):
|
|
12
|
-
* AIME = (min(salary, ssWageBase) * 0.65 * min(yearsWorked, 35)) / 420
|
|
13
|
-
* (simplified site approximation; exact AIME requires 35-year history)
|
|
14
|
-
* PIA = 0.90 * min(AIME, BP1)
|
|
15
|
-
* + 0.32 * (min(AIME, BP2) - BP1) if AIME > BP1
|
|
16
|
-
* + 0.15 * (AIME - BP2) if AIME > BP2
|
|
17
|
-
* (rounded down to nearest $0.10)
|
|
18
|
-
* benefit_at_claim = PIA * adjustment_factor(claimAge, FRA)
|
|
19
|
-
*
|
|
20
|
-
* Output values are USD monthly benefits (or USD lifetime totals).
|
|
21
|
-
*/
|
|
22
|
-
import { SSA_BEND_POINTS, SS_WAGE_BASE, DEFAULT_LIFE_EXPECTANCY, } from "./data/ssa.js";
|
|
23
|
-
/**
|
|
24
|
-
* SemVer of the SS engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041 Position #4a):
|
|
25
|
-
* major bump = math change; minor = additive output; patch = numerical correction.
|
|
26
|
-
* NOT bumped for cosmetic refactors.
|
|
27
|
-
* - 0.2.0 (v0.1.0 publish): initial port (S136), shipped under out-of-policy package-surface version.
|
|
28
|
-
* - 1.0.0 (v0.2.0 publish): one-time reset to align with ADR-0039 § 5 per ADR-0041 D4a.
|
|
29
|
-
* Math unchanged.
|
|
30
|
-
*/
|
|
31
|
-
export const ENGINE_VERSION = "1.0.0";
|
|
32
|
-
// ---------------------------------------------------------------------------
|
|
33
|
-
// FRA lookup (mirrors site engine FRA_TABLE)
|
|
34
|
-
// ---------------------------------------------------------------------------
|
|
35
|
-
/** FRA in years.months for a given birth year. Returns total months for math use. */
|
|
36
|
-
function fraTotalMonths(birthYear) {
|
|
37
|
-
if (birthYear <= 1954)
|
|
38
|
-
return 792; // 66.0
|
|
39
|
-
if (birthYear >= 1960)
|
|
40
|
-
return 804; // 67.0
|
|
41
|
-
// 1955-1959 transition: +2 months per year.
|
|
42
|
-
const map = {
|
|
43
|
-
1955: 794,
|
|
44
|
-
1956: 796,
|
|
45
|
-
1957: 798,
|
|
46
|
-
1958: 800,
|
|
47
|
-
1959: 802,
|
|
48
|
-
};
|
|
49
|
-
return map[birthYear] ?? 804;
|
|
50
|
-
}
|
|
51
|
-
function fraDecimal(birthYear) {
|
|
52
|
-
return fraTotalMonths(birthYear) / 12;
|
|
53
|
-
}
|
|
54
|
-
// ---------------------------------------------------------------------------
|
|
55
|
-
// Bend points
|
|
56
|
-
// ---------------------------------------------------------------------------
|
|
57
|
-
function getBendPoints(eligibilityYear) {
|
|
58
|
-
if (SSA_BEND_POINTS[eligibilityYear]) {
|
|
59
|
-
return { ...SSA_BEND_POINTS[eligibilityYear], estimated: false };
|
|
60
|
-
}
|
|
61
|
-
const years = Object.keys(SSA_BEND_POINTS)
|
|
62
|
-
.map(Number)
|
|
63
|
-
.sort((a, b) => b - a);
|
|
64
|
-
const latest = years[0];
|
|
65
|
-
return { ...SSA_BEND_POINTS[latest], estimated: true };
|
|
66
|
-
}
|
|
67
|
-
// ---------------------------------------------------------------------------
|
|
68
|
-
// AIME / PIA / claim-age adjustment (verbatim port of site math)
|
|
69
|
-
// ---------------------------------------------------------------------------
|
|
70
|
-
function estimateAIME(currentSalary, yearsWorked, taxYear) {
|
|
71
|
-
const wageBase = SS_WAGE_BASE[taxYear] ?? SS_WAGE_BASE[2026];
|
|
72
|
-
const cappedSalary = Math.min(currentSalary, wageBase);
|
|
73
|
-
const careerAverageFactor = 0.65;
|
|
74
|
-
const avgAnnualEarnings = cappedSalary * careerAverageFactor;
|
|
75
|
-
const effectiveYears = Math.min(yearsWorked, 35);
|
|
76
|
-
const totalEarnings = avgAnnualEarnings * effectiveYears;
|
|
77
|
-
return Math.floor(totalEarnings / 420);
|
|
78
|
-
}
|
|
79
|
-
function calculatePIA(aime, bp) {
|
|
80
|
-
let pia = 0.9 * Math.min(aime, bp.first);
|
|
81
|
-
if (aime > bp.first) {
|
|
82
|
-
pia += 0.32 * (Math.min(aime, bp.second) - bp.first);
|
|
83
|
-
}
|
|
84
|
-
if (aime > bp.second) {
|
|
85
|
-
pia += 0.15 * (aime - bp.second);
|
|
86
|
-
}
|
|
87
|
-
// PIA rounded down to nearest $0.10 per SSA convention.
|
|
88
|
-
return Math.floor(pia * 10) / 10;
|
|
89
|
-
}
|
|
90
|
-
/**
|
|
91
|
-
* Adjustment factor for claim age vs. FRA. < 1 is early reduction, > 1 is delayed credit.
|
|
92
|
-
* Mirrors site `calculateEarlyReduction` + `calculateDelayedCredit`.
|
|
93
|
-
*/
|
|
94
|
-
function adjustmentFactor(claimAgeMonths, fraMonths) {
|
|
95
|
-
if (claimAgeMonths === fraMonths)
|
|
96
|
-
return 1.0;
|
|
97
|
-
if (claimAgeMonths < fraMonths) {
|
|
98
|
-
const monthsEarly = fraMonths - claimAgeMonths;
|
|
99
|
-
let reduction = 0;
|
|
100
|
-
const first36 = Math.min(monthsEarly, 36);
|
|
101
|
-
reduction += first36 * (5 / 9) / 100;
|
|
102
|
-
if (monthsEarly > 36) {
|
|
103
|
-
reduction += (monthsEarly - 36) * (5 / 12) / 100;
|
|
104
|
-
}
|
|
105
|
-
return Math.max(0, 1 - reduction);
|
|
106
|
-
}
|
|
107
|
-
// Delayed credit: 2/3 of 1% per month (8%/yr), capped at 70 (= 840 months).
|
|
108
|
-
const cappedMonths = Math.min(claimAgeMonths, 840);
|
|
109
|
-
if (cappedMonths <= fraMonths)
|
|
110
|
-
return 1.0;
|
|
111
|
-
const monthsDelayed = cappedMonths - fraMonths;
|
|
112
|
-
return 1 + monthsDelayed * (2 / 3) / 100;
|
|
113
|
-
}
|
|
114
|
-
// ---------------------------------------------------------------------------
|
|
115
|
-
// Public API
|
|
116
|
-
// ---------------------------------------------------------------------------
|
|
117
|
-
export function estimate(input) {
|
|
118
|
-
const { birthYear, currentEarnings, claimAge, yearsWorked = 35, lifeExpectancy = DEFAULT_LIFE_EXPECTANCY, } = input;
|
|
119
|
-
const eligibilityYear = birthYear + 62;
|
|
120
|
-
const bp = getBendPoints(eligibilityYear);
|
|
121
|
-
const aime = estimateAIME(currentEarnings, yearsWorked, eligibilityYear);
|
|
122
|
-
const pia = calculatePIA(aime, bp);
|
|
123
|
-
const fraMonths = fraTotalMonths(birthYear);
|
|
124
|
-
const claimAgeMonths = claimAge * 12;
|
|
125
|
-
const adj = adjustmentFactor(claimAgeMonths, fraMonths);
|
|
126
|
-
const adjustedMonthly = Math.round(pia * adj * 100) / 100;
|
|
127
|
-
// Lifetime: monthly * 12 months * (lifeExpectancy − claimAge) years.
|
|
128
|
-
const yearsReceiving = Math.max(0, lifeExpectancy - claimAge);
|
|
129
|
-
const lifetime = Math.round(adjustedMonthly * 12 * yearsReceiving);
|
|
130
|
-
return {
|
|
131
|
-
monthlyBenefitAtFRA: pia,
|
|
132
|
-
adjustedMonthlyBenefit: adjustedMonthly,
|
|
133
|
-
lifetimeBenefitProjection: lifetime,
|
|
134
|
-
fraAge: fraDecimal(birthYear),
|
|
135
|
-
eligibilityYear,
|
|
136
|
-
bendPointsEstimated: bp.estimated,
|
|
137
|
-
};
|
|
138
|
-
}
|
|
139
|
-
//# sourceMappingURL=socialSecurity.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"socialSecurity.js","sourceRoot":"","sources":["../../src/engines/socialSecurity.ts"],"names":[],"mappings":"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"}
|