@markcolabs/mcp 0.2.0 → 0.3.0

package/dist/engines/ira.d.ts

@@ -0,0 +1,115 @@
+/**
+ * IRA contribution-limit engine — lifted from
+ * site/src/utils/ira-limits.js (functions `getContributionLimit`,
+ * `isCatchUpEligible`, `getRothContributionLimit`).
+ *
+ * Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
+ * parity test against the site source as the gate.
+ *
+ * Scope (S141 Wave 1A Item #2): MAGI + age + filing status → eligible Roth /
+ * Traditional contribution + phase-out reduction. Catch-up eligibility for
+ * age ≥ 50. Does NOT compute future-value projection or tax-deduction
+ * reinvestment side-account math — those stay in the calculator UI / a future
+ * tool. This is a contribution-LIMIT tool, not a projection tool.
+ *
+ * Math reference (Roth, per IRC §408A(c)(3)):
+ *   baseCap     = age ≥ 50 ? standard + catchUp : standard
+ *   if MAGI ≤ phaseOut.start  → eligible = baseCap
+ *   if MAGI ≥ phaseOut.end    → eligible = 0
+ *   else:
+ *     reductionRatio = (MAGI − phaseOut.start) / (phaseOut.end − phaseOut.start)
+ *     reduced       = baseCap × (1 − reductionRatio)
+ *     eligible      = max(round_to_$10(reduced), reduced > 0 ? $200 : 0)
+ *
+ * Math reference (Traditional, per IRC §219(b) + §219(g)):
+ *   eligible    = baseCap   (Traditional CONTRIBUTION is not MAGI-limited;
+ *                            only the DEDUCTION is, via §219(g) phase-out.
+ *                            The contributionLimit tool reports the
+ *                            contribution; the deduction phase-out is
+ *                            surfaced as a separate field for clients that
+ *                            need it.)
+ *
+ * Source: IRS Notice 2025-67 (2026 retirement plan limits) +
+ *         SECURE 2.0 Act §107 (catch-up indexing).
+ */
+/**
+ * SemVer of the IRA engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041 Position #4a):
+ * major bump = math change; minor = additive output; patch = numerical correction.
+ * NOT bumped for cosmetic refactors.
+ * - 1.0.0: initial v1 lift from ira-limits.js (S141 Wave 1A).
+ */
+export declare const ENGINE_VERSION = "1.0.0";
+/** Filing status (camelCase, matches the MCP package's federalTax convention). */
+export type IraFilingStatus = "single" | "marriedFilingJointly" | "marriedFilingSeparately" | "headOfHousehold";
+/** IRA type — drives Roth vs Traditional phase-out semantics. */
+export type IraType = "traditional" | "roth";
+/** Inputs to the IRA contribution-limit engine. */
+export interface IraContributionLimitInput {
+    /** Current age (used for catch-up eligibility). */
+    age: number;
+    /** Federal filing status. */
+    filingStatus: IraFilingStatus;
+    /**
+     * Modified Adjusted Gross Income (MAGI), USD. Drives Roth phase-out and
+     * is reported alongside the Traditional deduction-phase-out signal.
+     */
+    magi: number;
+    /** Whether to compute the limit for Traditional or Roth. */
+    type: IraType;
+}
+/** Result payload returned by the engine. */
+export interface IraContributionLimitResult {
+    /** User's max eligible contribution after phase-out, USD. */
+    eligibleContribution: number;
+    /** Base IRA limit (before catch-up), USD. Same for Traditional and Roth. */
+    traditionalCap: number;
+    /** Base Roth IRA limit (before catch-up), USD. Same number as traditionalCap. */
+    rothCap: number;
+    /** Catch-up contribution if age ≥ 50, else 0, USD. */
+    catchUp: number;
+    /**
+     * Reduction applied due to MAGI phase-out (Roth only, USD).
+     * For Traditional this is always 0 because contributionLimit is not
+     * MAGI-gated (the DEDUCTION is, surfaced separately).
+     */
+    phaseOutReduction: number;
+    /**
+     * Whether the user is in the catch-up window (age ≥ catchUpAge).
+     * Set independent of `type` so clients can advertise the catch-up regardless
+     * of which IRA type they're querying.
+     */
+    catchUpEligible: boolean;
+    /**
+     * Traditional IRA deduction phase-out signal (informational; does not
+     * affect `eligibleContribution`). Useful for clients that want to advise
+     * users their Traditional contribution may be non-deductible at high MAGI.
+     *   - "fullyDeductible"   — MAGI ≤ traditionalPhaseOut.start
+     *   - "partiallyDeductible" — MAGI within phase-out range
+     *   - "notDeductible"     — MAGI ≥ traditionalPhaseOut.end
+     *
+     * Assumes the contributor (or spouse) IS covered by a workplace plan; if
+     * neither is covered, full deduction applies regardless of MAGI.
+     */
+    traditionalDeductionStatus: "fullyDeductible" | "partiallyDeductible" | "notDeductible";
+    /** Provenance metadata. */
+    meta: {
+        /** IRS tax year these limits apply to. */
+        tableYear: number;
+        /** Source authority (IRS notice / IRC citation). */
+        source: string;
+    };
+}
+/**
+ * Compute IRA contribution limit + phase-out reduction for the given inputs.
+ *
+ * 1-to-1 logic port of site/src/utils/ira-limits.js `getContributionLimit` +
+ * `isCatchUpEligible` + `getRothContributionLimit` (the contribution-limit
+ * portion; future-value projection is out of scope per S141 Wave 1A).
+ *
+ * Filing-status key mapping vs. site (which uses 'single' / 'mfj' / 'mfs'):
+ * the MCP camelCase keys ('single' / 'marriedFilingJointly' /
+ * 'marriedFilingSeparately' / 'headOfHousehold') resolve to the same numeric
+ * phase-out thresholds — see ROTH_PHASE_OUT_2026 in data/irs2026.ts.
+ */
+export declare function contributionLimit(input: IraContributionLimitInput): IraContributionLimitResult;
+//# sourceMappingURL=ira.d.ts.map

package/dist/engines/ira.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ira.d.ts","sourceRoot":"","sources":["../../src/engines/ira.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAQH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,kFAAkF;AAClF,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,sBAAsB,GACtB,yBAAyB,GACzB,iBAAiB,CAAC;AAEtB,iEAAiE;AACjE,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,MAAM,CAAC;AAE7C,mDAAmD;AACnD,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,YAAY,EAAE,eAAe,CAAC;IAC9B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,OAAO,CAAC;CACf;AAED,6CAA6C;AAC7C,MAAM,WAAW,0BAA0B;IACzC,6DAA6D;IAC7D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;OAUG;IACH,0BAA0B,EACtB,iBAAiB,GACjB,qBAAqB,GACrB,eAAe,CAAC;IACpB,2BAA2B;IAC3B,IAAI,EAAE;QACJ,0CAA0C;QAC1C,SAAS,EAAE,MAAM,CAAC;QAClB,oDAAoD;QACpD,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,yBAAyB,GAC/B,0BAA0B,CAgE5B"}

package/dist/engines/ira.js

@@ -0,0 +1,127 @@
+/**
+ * IRA contribution-limit engine — lifted from
+ * site/src/utils/ira-limits.js (functions `getContributionLimit`,
+ * `isCatchUpEligible`, `getRothContributionLimit`).
+ *
+ * Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
+ * parity test against the site source as the gate.
+ *
+ * Scope (S141 Wave 1A Item #2): MAGI + age + filing status → eligible Roth /
+ * Traditional contribution + phase-out reduction. Catch-up eligibility for
+ * age ≥ 50. Does NOT compute future-value projection or tax-deduction
+ * reinvestment side-account math — those stay in the calculator UI / a future
+ * tool. This is a contribution-LIMIT tool, not a projection tool.
+ *
+ * Math reference (Roth, per IRC §408A(c)(3)):
+ *   baseCap     = age ≥ 50 ? standard + catchUp : standard
+ *   if MAGI ≤ phaseOut.start  → eligible = baseCap
+ *   if MAGI ≥ phaseOut.end    → eligible = 0
+ *   else:
+ *     reductionRatio = (MAGI − phaseOut.start) / (phaseOut.end − phaseOut.start)
+ *     reduced       = baseCap × (1 − reductionRatio)
+ *     eligible      = max(round_to_$10(reduced), reduced > 0 ? $200 : 0)
+ *
+ * Math reference (Traditional, per IRC §219(b) + §219(g)):
+ *   eligible    = baseCap   (Traditional CONTRIBUTION is not MAGI-limited;
+ *                            only the DEDUCTION is, via §219(g) phase-out.
+ *                            The contributionLimit tool reports the
+ *                            contribution; the deduction phase-out is
+ *                            surfaced as a separate field for clients that
+ *                            need it.)
+ *
+ * Source: IRS Notice 2025-67 (2026 retirement plan limits) +
+ *         SECURE 2.0 Act §107 (catch-up indexing).
+ */
+import { LIMITS_IRA_2026, ROTH_PHASE_OUT_2026, TRADITIONAL_PHASE_OUT_2026, } from "./data/irs2026.js";
+/**
+ * SemVer of the IRA engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041 Position #4a):
+ * major bump = math change; minor = additive output; patch = numerical correction.
+ * NOT bumped for cosmetic refactors.
+ * - 1.0.0: initial v1 lift from ira-limits.js (S141 Wave 1A).
+ */
+export const ENGINE_VERSION = "1.0.0";
+/**
+ * IRS rounding rule for phase-out reductions: round to nearest $10, minimum
+ * $200 if any contribution is allowed. Per IRC §408A(c)(3)(B)(ii).
+ */
+function roundPhaseOutReduction(reduced) {
+    if (reduced <= 0)
+        return 0;
+    const rounded = Math.round(reduced / 10) * 10;
+    return Math.max(rounded, 200);
+}
+/**
+ * Compute IRA contribution limit + phase-out reduction for the given inputs.
+ *
+ * 1-to-1 logic port of site/src/utils/ira-limits.js `getContributionLimit` +
+ * `isCatchUpEligible` + `getRothContributionLimit` (the contribution-limit
+ * portion; future-value projection is out of scope per S141 Wave 1A).
+ *
+ * Filing-status key mapping vs. site (which uses 'single' / 'mfj' / 'mfs'):
+ * the MCP camelCase keys ('single' / 'marriedFilingJointly' /
+ * 'marriedFilingSeparately' / 'headOfHousehold') resolve to the same numeric
+ * phase-out thresholds — see ROTH_PHASE_OUT_2026 in data/irs2026.ts.
+ */
+export function contributionLimit(input) {
+    const { age, filingStatus, magi, type } = input;
+    // Base cap (Traditional and Roth share the same base contribution limit).
+    const baseCap = LIMITS_IRA_2026.standard;
+    const catchUpEligible = age >= LIMITS_IRA_2026.catchUpAge;
+    const catchUp = catchUpEligible ? LIMITS_IRA_2026.catchUp : 0;
+    const fullCap = baseCap + catchUp;
+    // --- Roth phase-out (eligibility-gated) ---
+    // The Roth contribution itself is phased out at high MAGI. Traditional
+    // contribution is NOT (only its deductibility is — surfaced separately).
+    let eligibleContribution;
+    let phaseOutReduction;
+    if (type === "roth") {
+        const phaseOut = ROTH_PHASE_OUT_2026[filingStatus];
+        if (magi <= phaseOut.start) {
+            eligibleContribution = fullCap;
+            phaseOutReduction = 0;
+        }
+        else if (magi >= phaseOut.end) {
+            eligibleContribution = 0;
+            phaseOutReduction = fullCap;
+        }
+        else {
+            const range = phaseOut.end - phaseOut.start;
+            const overStart = magi - phaseOut.start;
+            const reductionRatio = overStart / range;
+            const reducedRaw = fullCap * (1 - reductionRatio);
+            eligibleContribution = roundPhaseOutReduction(reducedRaw);
+            phaseOutReduction = fullCap - eligibleContribution;
+        }
+    }
+    else {
+        // Traditional: contribution is never MAGI-phased-out, only deduction is.
+        eligibleContribution = fullCap;
+        phaseOutReduction = 0;
+    }
+    // --- Traditional deduction-phase-out signal (informational, always reported) ---
+    const tradPhaseOut = TRADITIONAL_PHASE_OUT_2026[filingStatus];
+    let traditionalDeductionStatus;
+    if (magi <= tradPhaseOut.start) {
+        traditionalDeductionStatus = "fullyDeductible";
+    }
+    else if (magi >= tradPhaseOut.end) {
+        traditionalDeductionStatus = "notDeductible";
+    }
+    else {
+        traditionalDeductionStatus = "partiallyDeductible";
+    }
+    return {
+        eligibleContribution,
+        traditionalCap: baseCap,
+        rothCap: baseCap,
+        catchUp,
+        phaseOutReduction,
+        catchUpEligible,
+        traditionalDeductionStatus,
+        meta: {
+            tableYear: 2026,
+            source: "IRS Notice 2025-67",
+        },
+    };
+}
+//# sourceMappingURL=ira.js.map

package/dist/engines/ira.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ira.js","sourceRoot":"","sources":["../../src/engines/ira.ts"],"names":[],"mappings":"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"}

package/dist/engines/paycheck.d.ts

@@ -6,25 +6,37 @@
  * Per ADR-0039 § 5: pure synchronous functions, ENGINE_VERSION constant,
  * parity test against the site source as the gate.
  *
- * MCP-side scope decision (S136): the site engine includes per-state tax
- * tables loaded async via fetch(), SDI, NYC local tax, hourly-mode handling,
- * and YTD wage tracking. None of those fit a synchronous, self-contained
- * MCP tool. The v0.2.0 paycheck engine therefore covers:
- *   - Federal income-tax withholding (Percentage Method, IRS Pub 15-T 2026)
- *   - FICA (SS 6.2% + Medicare 1.45% + Additional Medicare 0.9%)
- *   - State estimate: $0 for no-tax states, otherwise a flat 5% estimate
- *     (clearly disclaimed as an approximation pending a future stateful tool).
- *   - Pre-tax + post-tax deductions on an annualized basis
+ * ## v0.3.0 changes (S141 Item #5)
  *
- * The state-tax limitation is documented in the tool envelope and disclaimer.
+ * Two YMYL-grade corrections vs v1.0.0:
  *
- * Math reference (annualized):
+ * 1. **MCP-AUDIT-011 — State-aware tax estimate.** The v1.0.0 flat 5% state
+ *    estimate is replaced with a state-aware effective-rate lookup using
+ *    marginal-bracket simplification (see `engines/data/stateTax2026.ts`).
+ *    Rates sourced from the Tax Foundation 2026 State Individual Income Tax
+ *    Rates report. No-tax states still return $0.
+ *
+ * 2. **MCP-AUDIT-012 — Additional Medicare base.** The 0.9% Additional
+ *    Medicare tax now correctly uses the FICA wages base
+ *    (gross − pre-tax cafeteria-plan deductions: 401k/HSA/dep-care/FSA),
+ *    not raw gross. Matches the IRS § 3101(b)(2) rule.
+ *
+ * Engine version bumped 1.0.0 → 1.1.0 (additive: new `state` semantics +
+ * new result fields). Math output differs in two ways: state tax becomes
+ * state-correct, and Additional Medicare correctly excludes pre-tax
+ * deductions. Per ADR-0039 § 5 / ADR-0041 D4a, a math fix is a patch bump
+ * if not breaking the public surface; we're using a MINOR bump because we
+ * add new result fields (`stateTaxSource`, `stateTaxNotes`,
+ * `stateEffectiveRate`).
+ *
+ * Math reference (annualized) — v0.3.0:
  *   federalTaxableIncome = max(0, grossAnnual − preTaxAnnual − stdDeduction)
  *   federalTax = bracketsLookup(federalTaxableIncome, brackets[filingStatus])
- *   ssTax     = min(grossAnnual − preTaxAnnual, ssWageBase) * 0.062
- *   medicare  = (grossAnnual − preTaxAnnual) * 0.0145
- *   addlMed   = max(0, grossAnnual − addlMedThreshold[filingStatus]) * 0.009
- *   stateTax  = noTaxState ? 0 : (grossAnnual − preTaxAnnual − stdDeduction) * 0.05
+ *   ficaWages = max(0, grossAnnual − preTaxAnnual)   // pre-tax deductions reduce FICA base
+ *   ssTax     = min(ficaWages, ssWageBase) * 0.062
+ *   medicare  = ficaWages * 0.0145
+ *   addlMed   = max(0, ficaWages − addlMedThreshold[filingStatus]) * 0.009
+ *   stateTax  = noTaxState ? 0 : federalTaxableIncome * stateEffectiveRate(state, federalTaxableIncome)
  *   netAnnual = grossAnnual − preTaxAnnual − federalTax − ficaTax − stateTax − postTaxAnnual
  *   per-paycheck values = annual / payPeriodsPerYear
  */
@@ -36,8 +48,13 @@ import { type FilingStatus, type PayFrequencyLabel } from "./data/federalTax.js"
  * - 0.2.0 (v0.1.0 publish): initial port (S136), shipped under out-of-policy package-surface version.
  * - 1.0.0 (v0.2.0 publish): one-time reset to align with ADR-0039 § 5 per ADR-0041 D4a.
  *   Math unchanged.
+ * - 1.1.0 (v0.3.0 publish, S141 Item #5): state-aware tax (MCP-AUDIT-011) +
+ *   Additional Medicare on FICA wages (MCP-AUDIT-012). Additive output fields:
+ *   stateTaxSource, stateTaxNotes, stateEffectiveRate. Per-state math differs
+ *   vs 1.0.0 for non-no-tax states; Additional Medicare differs for high
+ *   earners with pre-tax deductions.
  */
-export declare const ENGINE_VERSION = "1.0.0";
+export declare const ENGINE_VERSION = "1.1.0";
 /** Inputs to the paycheck net-pay engine. */
 export interface PaycheckNetPayInput {
     /** Gross annual salary, USD. */
@@ -79,6 +96,24 @@ export interface PaycheckNetPayResult {
     netPayAnnual: number;
     /** Whether the state has no income tax. */
     noStateIncomeTax: boolean;
+    /**
+     * v1.1.0 additive — citable source for the state-tax effective rate used.
+     * Same Tax Foundation 2026 report regardless of state; included for caller
+     * provenance.
+     */
+    stateTaxSource: string;
+    /**
+     * v1.1.0 additive — state-specific caveats (e.g., "Excludes NYC local tax",
+     * "Local municipal EIT NOT included"). Empty string when no caveats apply
+     * (no-tax states, flat-rate states with no local-tax overlay, etc.).
+     */
+    stateTaxNotes: string;
+    /**
+     * v1.1.0 additive — the effective rate (decimal, 0.093 = 9.3%) the engine
+     * applied to taxable income for the state-tax estimate. 0 for no-tax states
+     * and for state codes not modeled in our table.
+     */
+    stateEffectiveRate: number;
 }
 /**
  * Compute net pay (and the annualized + per-paycheck breakdown).

package/dist/engines/paycheck.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paycheck.d.ts","sourceRoot":"","sources":["../../src/engines/paycheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAQL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAEvB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB;IACrB,YAAY,EAAE,iBAAiB,CAAC;IAChC,kEAAkE;IAClE,mBAAmB,EAAE,YAAY,CAAC;IAClC,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wFAAwF;IACxF,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,4BAA4B;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CAoEvE"}
+{"version":3,"file":"paycheck.d.ts","sourceRoot":"","sources":["../../src/engines/paycheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAQL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAEvB,MAAM,sBAAsB,CAAC;AAO9B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB;IACrB,YAAY,EAAE,iBAAiB,CAAC;IAChC,kEAAkE;IAClE,mBAAmB,EAAE,YAAY,CAAC;IAClC,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wFAAwF;IACxF,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,4BAA4B;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAmBD;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CA+EvE"}

package/dist/engines/paycheck.js

@@ -6,29 +6,42 @@
  * Per ADR-0039 § 5: pure synchronous functions, ENGINE_VERSION constant,
  * parity test against the site source as the gate.
  *
- * MCP-side scope decision (S136): the site engine includes per-state tax
- * tables loaded async via fetch(), SDI, NYC local tax, hourly-mode handling,
- * and YTD wage tracking. None of those fit a synchronous, self-contained
- * MCP tool. The v0.2.0 paycheck engine therefore covers:
- *   - Federal income-tax withholding (Percentage Method, IRS Pub 15-T 2026)
- *   - FICA (SS 6.2% + Medicare 1.45% + Additional Medicare 0.9%)
- *   - State estimate: $0 for no-tax states, otherwise a flat 5% estimate
- *     (clearly disclaimed as an approximation pending a future stateful tool).
- *   - Pre-tax + post-tax deductions on an annualized basis
+ * ## v0.3.0 changes (S141 Item #5)
  *
- * The state-tax limitation is documented in the tool envelope and disclaimer.
+ * Two YMYL-grade corrections vs v1.0.0:
  *
- * Math reference (annualized):
+ * 1. **MCP-AUDIT-011 — State-aware tax estimate.** The v1.0.0 flat 5% state
+ *    estimate is replaced with a state-aware effective-rate lookup using
+ *    marginal-bracket simplification (see `engines/data/stateTax2026.ts`).
+ *    Rates sourced from the Tax Foundation 2026 State Individual Income Tax
+ *    Rates report. No-tax states still return $0.
+ *
+ * 2. **MCP-AUDIT-012 — Additional Medicare base.** The 0.9% Additional
+ *    Medicare tax now correctly uses the FICA wages base
+ *    (gross − pre-tax cafeteria-plan deductions: 401k/HSA/dep-care/FSA),
+ *    not raw gross. Matches the IRS § 3101(b)(2) rule.
+ *
+ * Engine version bumped 1.0.0 → 1.1.0 (additive: new `state` semantics +
+ * new result fields). Math output differs in two ways: state tax becomes
+ * state-correct, and Additional Medicare correctly excludes pre-tax
+ * deductions. Per ADR-0039 § 5 / ADR-0041 D4a, a math fix is a patch bump
+ * if not breaking the public surface; we're using a MINOR bump because we
+ * add new result fields (`stateTaxSource`, `stateTaxNotes`,
+ * `stateEffectiveRate`).
+ *
+ * Math reference (annualized) — v0.3.0:
  *   federalTaxableIncome = max(0, grossAnnual − preTaxAnnual − stdDeduction)
  *   federalTax = bracketsLookup(federalTaxableIncome, brackets[filingStatus])
- *   ssTax     = min(grossAnnual − preTaxAnnual, ssWageBase) * 0.062
- *   medicare  = (grossAnnual − preTaxAnnual) * 0.0145
- *   addlMed   = max(0, grossAnnual − addlMedThreshold[filingStatus]) * 0.009
- *   stateTax  = noTaxState ? 0 : (grossAnnual − preTaxAnnual − stdDeduction) * 0.05
+ *   ficaWages = max(0, grossAnnual − preTaxAnnual)   // pre-tax deductions reduce FICA base
+ *   ssTax     = min(ficaWages, ssWageBase) * 0.062
+ *   medicare  = ficaWages * 0.0145
+ *   addlMed   = max(0, ficaWages − addlMedThreshold[filingStatus]) * 0.009
+ *   stateTax  = noTaxState ? 0 : federalTaxableIncome * stateEffectiveRate(state, federalTaxableIncome)
  *   netAnnual = grossAnnual − preTaxAnnual − federalTax − ficaTax − stateTax − postTaxAnnual
  *   per-paycheck values = annual / payPeriodsPerYear
  */
 import { FEDERAL_TAX_BRACKETS_2026, STANDARD_DEDUCTIONS_2026, ADDITIONAL_MEDICARE_THRESHOLDS_2026, FICA_RATES, SS_WAGE_BASE, PAY_PERIODS_PER_YEAR, NO_TAX_STATES, } from "./data/federalTax.js";
+import { getStateEffectiveRate, getStateEntry, STATE_TAX_2026_META, } from "./data/stateTax2026.js";
 /**
  * SemVer of the paycheck engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041 Position #4a):
  * major bump = math change; minor = additive output; patch = numerical correction.
@@ -36,8 +49,13 @@ import { FEDERAL_TAX_BRACKETS_2026, STANDARD_DEDUCTIONS_2026, ADDITIONAL_MEDICAR
  * - 0.2.0 (v0.1.0 publish): initial port (S136), shipped under out-of-policy package-surface version.
  * - 1.0.0 (v0.2.0 publish): one-time reset to align with ADR-0039 § 5 per ADR-0041 D4a.
  *   Math unchanged.
+ * - 1.1.0 (v0.3.0 publish, S141 Item #5): state-aware tax (MCP-AUDIT-011) +
+ *   Additional Medicare on FICA wages (MCP-AUDIT-012). Additive output fields:
+ *   stateTaxSource, stateTaxNotes, stateEffectiveRate. Per-state math differs
+ *   vs 1.0.0 for non-no-tax states; Additional Medicare differs for high
+ *   earners with pre-tax deductions.
  */
-export const ENGINE_VERSION = "1.0.0";
+export const ENGINE_VERSION = "1.1.0";
 const ROUND = (v) => Math.round(v * 100) / 100;
 /**
  * Progressive bracket lookup — verbatim port of site `calculateBracketTax`.
@@ -72,23 +90,31 @@ export function netPay(input) {
     const stdDeduction = STANDARD_DEDUCTIONS_2026[federalFilingStatus];
     const federalTaxable = Math.max(0, adjustedAnnual - stdDeduction);
     const federalTaxAnnual = bracketTax(federalTaxable, FEDERAL_TAX_BRACKETS_2026[federalFilingStatus]);
-    // FICA on gross (less pre-tax cafeteria plan deductions; we conservatively
-    // apply pre-tax deductions to FICA since the kickoff input doesn't split
-    // 401k vs cafeteria-plan deductions — matches the more lenient employee view).
+    // FICA on gross less pre-tax cafeteria-plan deductions; we conservatively
+    // apply all pre-tax deductions to FICA since the input doesn't split 401k
+    // vs cafeteria-plan deductions — matches the more lenient employee view.
     const ficaWages = adjustedAnnual;
     const ssWageBase = SS_WAGE_BASE[2026] ?? SS_WAGE_BASE[2025];
     const ssTaxAnnual = Math.min(ficaWages, ssWageBase) * FICA_RATES.socialSecurityRate;
     const medicareAnnual = ficaWages * FICA_RATES.medicareRate;
     const addlMedThreshold = ADDITIONAL_MEDICARE_THRESHOLDS_2026[federalFilingStatus];
-    const addlMedAnnual = grossAnnualSalary > addlMedThreshold
-        ? (grossAnnualSalary - addlMedThreshold) * FICA_RATES.additionalMedicareRate
+    // MCP-AUDIT-012 fix (v1.1.0): Additional Medicare uses FICA wages base,
+    // not raw gross. Matches IRS § 3101(b)(2) / Form 8959 rule. Pre-tax
+    // health/HSA/dep-care deductions DO reduce the Additional Medicare base.
+    const addlMedAnnual = ficaWages > addlMedThreshold
+        ? (ficaWages - addlMedThreshold) * FICA_RATES.additionalMedicareRate
         : 0;
     const ficaTaxAnnual = ssTaxAnnual + medicareAnnual + addlMedAnnual;
-    // State tax: no-tax states explicit zero; everyone else gets a flat 5%
-    // estimate over taxable income (clearly disclaimed in the envelope).
+    // State tax: no-tax states explicit zero; everyone else uses state-aware
+    // effective-rate lookup (MCP-AUDIT-011 fix, v1.1.0). See stateTax2026.ts.
     const stateUpper = state.trim().toUpperCase();
     const noStateIncomeTax = NO_TAX_STATES.includes(stateUpper);
-    const stateTaxAnnual = noStateIncomeTax ? 0 : federalTaxable * 0.05;
+    const stateEffectiveRate = noStateIncomeTax
+        ? 0
+        : getStateEffectiveRate(stateUpper, federalTaxable);
+    const stateTaxAnnual = federalTaxable * stateEffectiveRate;
+    const stateEntry = noStateIncomeTax ? undefined : getStateEntry(stateUpper);
+    const stateTaxNotes = stateEntry?.notes ?? "";
     // Net annual + per-paycheck.
     const netPayAnnual = grossAnnualSalary -
         preTaxDeductionsAnnual -
@@ -108,6 +134,9 @@ export function netPay(input) {
         stateTaxAnnual: ROUND(stateTaxAnnual),
         netPayAnnual: ROUND(netPayAnnual),
         noStateIncomeTax,
+        stateTaxSource: STATE_TAX_2026_META.source,
+        stateTaxNotes,
+        stateEffectiveRate,
     };
 }
 //# sourceMappingURL=paycheck.js.map

package/dist/engines/paycheck.js.map

@@ -1 +1 @@
-{"version":3,"file":"paycheck.js","sourceRoot":"","sources":["../../src/engines/paycheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,mCAAmC,EACnC,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,aAAa,GAId,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AA8CtC,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AAEvD;;GAEG;AACH,SAAS,UAAU,CAAC,aAAqB,EAAE,QAAsB;IAC/D,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACrD,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,aAAa,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YAC1B,MAAM,gBAAgB,GAAG,aAAa,GAAG,CAAC,CAAC,GAAG,CAAC;YAC/C,OAAO,CAAC,CAAC,OAAO,GAAG,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAC,KAA0B;IAC/C,MAAM,EACJ,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,KAAK,EACL,sBAAsB,EACtB,uBAAuB,GACxB,GAAG,KAAK,CAAC;IAEV,MAAM,cAAc,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC;IAE1D,gEAAgE;IAChE,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,iBAAiB,GAAG,sBAAsB,CAAC,CAAC;IAE/E,iEAAiE;IACjE,MAAM,YAAY,GAAG,wBAAwB,CAAC,mBAAmB,CAAC,CAAC;IACnE,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC;IAClE,MAAM,gBAAgB,GAAG,UAAU,CACjC,cAAc,EACd,yBAAyB,CAAC,mBAAmB,CAAC,CAC/C,CAAC;IAEF,2EAA2E;IAC3E,yEAAyE;IACzE,+EAA+E;IAC/E,MAAM,SAAS,GAAG,cAAc,CAAC;IACjC,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5D,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,UAAU,CAAC,GAAG,UAAU,CAAC,kBAAkB,CAAC;IACpF,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,CAAC,YAAY,CAAC;IAC3D,MAAM,gBAAgB,GACpB,mCAAmC,CAAC,mBAAmB,CAAC,CAAC;IAC3D,MAAM,aAAa,GACjB,iBAAiB,GAAG,gBAAgB;QAClC,CAAC,CAAC,CAAC,iBAAiB,GAAG,gBAAgB,CAAC,GAAG,UAAU,CAAC,sBAAsB;QAC5E,CAAC,CAAC,CAAC,CAAC;IACR,MAAM,aAAa,GAAG,WAAW,GAAG,cAAc,GAAG,aAAa,CAAC;IAEnE,uEAAuE;IACvE,qEAAqE;IACrE,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,MAAM,gBAAgB,GAAI,aAAmC,CAAC,QAAQ,CACpE,UAAU,CACX,CAAC;IACF,MAAM,cAAc,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,GAAG,IAAI,CAAC;IAEpE,6BAA6B;IAC7B,MAAM,YAAY,GAChB,iBAAiB;QACjB,sBAAsB;QACtB,gBAAgB;QAChB,aAAa;QACb,cAAc;QACd,uBAAuB,CAAC;IAE1B,OAAO;QACL,gBAAgB,EAAE,KAAK,CAAC,iBAAiB,GAAG,cAAc,CAAC;QAC3D,UAAU,EAAE,KAAK,CAAC,gBAAgB,GAAG,cAAc,CAAC;QACpD,OAAO,EAAE,KAAK,CAAC,aAAa,GAAG,cAAc,CAAC;QAC9C,QAAQ,EAAE,KAAK,CAAC,cAAc,GAAG,cAAc,CAAC;QAChD,MAAM,EAAE,KAAK,CAAC,YAAY,GAAG,cAAc,CAAC;QAC5C,iBAAiB,EAAE,cAAc;QACjC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,CAAC;QACzC,aAAa,EAAE,KAAK,CAAC,aAAa,CAAC;QACnC,cAAc,EAAE,KAAK,CAAC,cAAc,CAAC;QACrC,YAAY,EAAE,KAAK,CAAC,YAAY,CAAC;QACjC,gBAAgB;KACjB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"paycheck.js","sourceRoot":"","sources":["../../src/engines/paycheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,mCAAmC,EACnC,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,aAAa,GAId,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAgEtC,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AAEvD;;GAEG;AACH,SAAS,UAAU,CAAC,aAAqB,EAAE,QAAsB;IAC/D,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,aAAa,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACrD,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,aAAa,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;YAC1B,MAAM,gBAAgB,GAAG,aAAa,GAAG,CAAC,CAAC,GAAG,CAAC;YAC/C,OAAO,CAAC,CAAC,OAAO,GAAG,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAC,KAA0B;IAC/C,MAAM,EACJ,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,KAAK,EACL,sBAAsB,EACtB,uBAAuB,GACxB,GAAG,KAAK,CAAC;IAEV,MAAM,cAAc,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC;IAE1D,gEAAgE;IAChE,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,iBAAiB,GAAG,sBAAsB,CAAC,CAAC;IAE/E,iEAAiE;IACjE,MAAM,YAAY,GAAG,wBAAwB,CAAC,mBAAmB,CAAC,CAAC;IACnE,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC;IAClE,MAAM,gBAAgB,GAAG,UAAU,CACjC,cAAc,EACd,yBAAyB,CAAC,mBAAmB,CAAC,CAC/C,CAAC;IAEF,0EAA0E;IAC1E,0EAA0E;IAC1E,yEAAyE;IACzE,MAAM,SAAS,GAAG,cAAc,CAAC;IACjC,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5D,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,UAAU,CAAC,GAAG,UAAU,CAAC,kBAAkB,CAAC;IACpF,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,CAAC,YAAY,CAAC;IAC3D,MAAM,gBAAgB,GACpB,mCAAmC,CAAC,mBAAmB,CAAC,CAAC;IAC3D,wEAAwE;IACxE,oEAAoE;IACpE,yEAAyE;IACzE,MAAM,aAAa,GACjB,SAAS,GAAG,gBAAgB;QAC1B,CAAC,CAAC,CAAC,SAAS,GAAG,gBAAgB,CAAC,GAAG,UAAU,CAAC,sBAAsB;QACpE,CAAC,CAAC,CAAC,CAAC;IACR,MAAM,aAAa,GAAG,WAAW,GAAG,cAAc,GAAG,aAAa,CAAC;IAEnE,yEAAyE;IACzE,0EAA0E;IAC1E,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,MAAM,gBAAgB,GAAI,aAAmC,CAAC,QAAQ,CACpE,UAAU,CACX,CAAC;IACF,MAAM,kBAAkB,GAAG,gBAAgB;QACzC,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,qBAAqB,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IACtD,MAAM,cAAc,GAAG,cAAc,GAAG,kBAAkB,CAAC;IAC3D,MAAM,UAAU,GAAG,gBAAgB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAC5E,MAAM,aAAa,GAAG,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC;IAE9C,6BAA6B;IAC7B,MAAM,YAAY,GAChB,iBAAiB;QACjB,sBAAsB;QACtB,gBAAgB;QAChB,aAAa;QACb,cAAc;QACd,uBAAuB,CAAC;IAE1B,OAAO;QACL,gBAAgB,EAAE,KAAK,CAAC,iBAAiB,GAAG,cAAc,CAAC;QAC3D,UAAU,EAAE,KAAK,CAAC,gBAAgB,GAAG,cAAc,CAAC;QACpD,OAAO,EAAE,KAAK,CAAC,aAAa,GAAG,cAAc,CAAC;QAC9C,QAAQ,EAAE,KAAK,CAAC,cAAc,GAAG,cAAc,CAAC;QAChD,MAAM,EAAE,KAAK,CAAC,YAAY,GAAG,cAAc,CAAC;QAC5C,iBAAiB,EAAE,cAAc;QACjC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,CAAC;QACzC,aAAa,EAAE,KAAK,CAAC,aAAa,CAAC;QACnC,cAAc,EAAE,KAAK,CAAC,cAAc,CAAC;QACrC,YAAY,EAAE,KAAK,CAAC,YAAY,CAAC;QACjC,gBAAgB;QAChB,cAAc,EAAE,mBAAmB,CAAC,MAAM;QAC1C,aAAa;QACb,kBAAkB;KACnB,CAAC;AACJ,CAAC"}

package/dist/engines/rmd.d.ts

@@ -0,0 +1,107 @@
+/**
+ * RMD (Required Minimum Distribution) engine — lifted from
+ * site/src/utils/rmd-engine.js (functions `calculateRMD`,
+ * `getDistributionPeriod`, `getRMDStartAge`).
+ *
+ * Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
+ * parity test against the site source as the gate.
+ *
+ * Scope (S141 Wave 1B Item #3): SINGLE-YEAR RMD distribution-amount
+ * calculation only. The site calculator's multi-year projection
+ * (`generateRMDProjection`) and pre-RMD age-projection path are OUT of
+ * scope for v1 — callers needing year-by-year projections should call the
+ * tool repeatedly with the projected balance for each year.
+ *
+ * Table coverage: ONLY the Uniform Lifetime Table (Pub. 590-B Table III,
+ * post-2022 version) is implemented, mirroring the site source which uses
+ * `UNIFORM_LIFETIME_TABLE` exclusively. The Joint Life Expectancy Table
+ * (Table II, applied when spouse is sole beneficiary AND 10+ years younger)
+ * is NOT in the site engine and is therefore NOT in this tool — adding it
+ * here would create a parity gap with the site calculator. The `tableUsed`
+ * field is always `"uniform-lifetime"` for v1; the union type leaves room
+ * for `"joint-life-expectancy"` in a future minor bump when the site adds it.
+ *
+ * Math reference (per IRC §401(a)(9) + Pub. 590-B):
+ *   distributionPeriod = UNIFORM_LIFETIME_TABLE[ownerAge]
+ *   rmdAmount          = accountBalance / distributionPeriod
+ *
+ * Missed-RMD penalty (SECURE 2.0 §302, effective 2023+):
+ *   penaltyIfMissed    = rmdAmount × 0.25                (default 25% excise tax)
+ *   reduced to 10% if corrected within IRS correction window (typically 2 years)
+ *   (down from 50% pre-SECURE-2.0)
+ *
+ * Source: IRS Publication 590-B (Uniform Lifetime Table III, post-2022) +
+ *         SECURE 2.0 Act §107 (RMD age tiers) + §302 (25% excise tax).
+ * Last verified: 2026-05-27.
+ */
+/**
+ * SemVer of the RMD engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041
+ * Position #4a): major bump = math change; minor = additive output; patch =
+ * numerical correction. NOT bumped for cosmetic refactors.
+ * - 1.0.0: initial v1 lift from rmd-engine.js (S141 Wave 1B).
+ */
+export declare const ENGINE_VERSION = "1.0.0";
+/**
+ * Which IRS RMD distribution-period table was applied. For v1 always
+ * `"uniform-lifetime"` (mirrors the site source). The `"joint-life-expectancy"`
+ * variant is reserved for a future minor when the site engine adds Table II.
+ */
+export type RmdTableUsed = "uniform-lifetime" | "joint-life-expectancy";
+/** Inputs to the RMD distribution-amount engine. */
+export interface RmdDistributionAmountInput {
+    /** Prior year-end account balance, USD. */
+    accountBalance: number;
+    /** Owner's age this calendar year (must be ≥ SECURE 2.0 RMD age, typically 73). */
+    ownerAge: number;
+    /**
+     * Spouse's age (optional). RESERVED FOR FUTURE Joint Life Expectancy Table
+     * support. v1 ignores this input — the Uniform Lifetime Table is always
+     * applied (matches site parity). Documented in tool description so callers
+     * know not to rely on it for v1.
+     */
+    spouseAge?: number;
+    /**
+     * Whether the spouse is the sole IRA beneficiary (optional). RESERVED FOR
+     * FUTURE Joint Life Expectancy Table support. v1 ignores this input.
+     */
+    isSpouseSoleBeneficiary?: boolean;
+}
+/** Result payload returned by the engine. */
+export interface RmdDistributionAmountResult {
+    /** Required minimum distribution this year, USD. */
+    rmdAmount: number;
+    /** Years (life-expectancy factor from the applied IRS table). */
+    distributionPeriod: number;
+    /** Duplicates distributionPeriod under a more semantic name. */
+    lifeExpectancyFactor: number;
+    /** Which IRS table was applied. Always `"uniform-lifetime"` for v1. */
+    tableUsed: RmdTableUsed;
+    /**
+     * Default excise tax owed if the RMD is missed (SECURE 2.0 §302, 25%).
+     * Reduced to 10% if corrected within the IRS correction window (typically
+     * 2 years) — callers should surface this nuance in the UI; the field
+     * itself reports the 25% default.
+     */
+    penaltyIfMissed: number;
+    /** Provenance metadata. */
+    meta: {
+        /** IRS table edition / tax year. */
+        tableYear: number;
+        /** Source authority (IRS publication / SECURE 2.0 citation). */
+        source: string;
+    };
+}
+/**
+ * Compute the required minimum distribution for the given inputs.
+ *
+ * 1-to-1 logic port of site/src/utils/rmd-engine.js `calculateRMD` +
+ * `getDistributionPeriod` (single-year path; multi-year projection out of
+ * scope). The site engine clamps lookups to [72, 120]; we additionally
+ * require ownerAge ≥ 73 (SECURE 2.0 floor for the 1951-1959 cohort, the
+ * common case in 2026) at the tool boundary via RMD_BOUNDS.
+ *
+ * Throws on undefined-period lookup — should be unreachable because bounds
+ * validation in the tool wrapper rejects out-of-range ages first.
+ */
+export declare function distributionAmount(input: RmdDistributionAmountInput): RmdDistributionAmountResult;
+//# sourceMappingURL=rmd.d.ts.map

package/dist/engines/rmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rmd.d.ts","sourceRoot":"","sources":["../../src/engines/rmd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAUH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,uBAAuB,CAAC;AAExE,oDAAoD;AACpD,MAAM,WAAW,0BAA0B;IACzC,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,6CAA6C;AAC7C,MAAM,WAAW,2BAA2B;IAC1C,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gEAAgE;IAChE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,SAAS,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,IAAI,EAAE;QACJ,oCAAoC;QACpC,SAAS,EAAE,MAAM,CAAC;QAClB,gEAAgE;QAChE,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,0BAA0B,GAChC,2BAA2B,CAyC7B"}