@markcolabs/mcp 0.1.0

package/dist/engines/data/irs2026.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"irs2026.d.ts","sourceRoot":"","sources":["../../../src/engines/data/irs2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,gBAAgB;IAC3B,oCAAoC;;IAEpC,qDAAqD;;IAErD,yDAAyD;;IAEzD,kDAAkD;;IAElD,gDAAgD;;IAEhD,oCAAoC;;IAEpC,sCAAsC;;IAEtC,oCAAoC;;CAE5B,CAAC"}

package/dist/engines/data/irs2026.js

@@ -0,0 +1,30 @@
+/**
+ * Self-contained 2026 IRS retirement-plan limits subset for the MCP package's
+ * 401(k) projection engine.
+ *
+ * Mirrored from site/src/data/annual-limits.js LIMITS_401K_2026. See
+ * engines/data/ssa.ts for full rationale on the mirror pattern.
+ *
+ * Source: IRS Notice 2025-67 (2026 retirement-plan limits) +
+ *         SECURE 2.0 Act §109 (super catch-up provision for ages 60-63).
+ * Last verified: 2026-05-09.
+ */
+export const LIMITS_401K_2026 = {
+    /** Base employee deferral limit. */
+    base: 24_500,
+    /** Regular catch-up amount for ages 50-59 or 64+. */
+    catchUp: 8_000,
+    /** Super catch-up amount for ages 60-63 (SECURE 2.0). */
+    superCatchUp: 11_250,
+    /** Total deferral limit with regular catch-up. */
+    totalWithCatchUp: 32_500,
+    /** Total deferral limit with super catch-up. */
+    totalWithSuperCatchUp: 35_750,
+    /** Minimum age for any catch-up. */
+    catchUpAge: 50,
+    /** Start of super catch-up window. */
+    superCatchUpAgeStart: 60,
+    /** End of super catch-up window. */
+    superCatchUpAgeEnd: 63,
+};
+//# sourceMappingURL=irs2026.js.map

package/dist/engines/data/irs2026.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"irs2026.js","sourceRoot":"","sources":["../../../src/engines/data/irs2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,oCAAoC;IACpC,IAAI,EAAE,MAAM;IACZ,qDAAqD;IACrD,OAAO,EAAE,KAAK;IACd,yDAAyD;IACzD,YAAY,EAAE,MAAM;IACpB,kDAAkD;IAClD,gBAAgB,EAAE,MAAM;IACxB,gDAAgD;IAChD,qBAAqB,EAAE,MAAM;IAC7B,oCAAoC;IACpC,UAAU,EAAE,EAAE;IACd,sCAAsC;IACtC,oBAAoB,EAAE,EAAE;IACxB,oCAAoC;IACpC,kBAAkB,EAAE,EAAE;CACd,CAAC"}

package/dist/engines/data/ssa.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Self-contained SSA constants subset for the @markcolabs/mcp package.
+ *
+ * Mirrored from site/src/data/annual-limits.js and site/src/utils/social-security-engine.js
+ * (re-export-of-truth pattern). Per ADR-0039 § 5 + S136 kickoff: the npm-published
+ * MCP package may NOT import from site/src/ at runtime, so the regulatory data
+ * subset that the SS engine depends on is mirrored here. When site values change,
+ * update this file in lockstep with the source and bump the SS engine ENGINE_VERSION.
+ *
+ * Source of truth: site/src/data/annual-limits.js
+ * - SSA_BEND_POINTS keyed by eligibility year (year a person turns 62)
+ * - SS_WAGE_BASE keyed by calendar year (max earnings subject to SS tax)
+ * Source: SSA Fact Sheet, https://www.ssa.gov/oact/cola/cbb.html
+ *         SSA Bend Points history, https://www.ssa.gov/oact/cola/bendpoints.html
+ *
+ * Last verified: 2026-05-09 (matches site annual-limits.js verification dates).
+ */
+/**
+ * Average Wage Indexing series bend points by eligibility year.
+ * Eligibility year = year person turns 62.
+ *
+ * Subset includes 2014–2026; older years are not needed for current users
+ * (someone born in 1952 turned 62 in 2014; older birthdays use even-older bend
+ * points but the SS engine accepts anything in the lookup, falling back to the
+ * latest available year with `estimated: true`).
+ */
+export declare const SSA_BEND_POINTS: Record<number, {
+    first: number;
+    second: number;
+}>;
+/**
+ * Social Security wage base by calendar year (max earnings subject to SS tax).
+ */
+export declare const SS_WAGE_BASE: Record<number, number>;
+/**
+ * Default life expectancy used by lifetime-benefit projections (SSA actuarial table proxy).
+ */
+export declare const DEFAULT_LIFE_EXPECTANCY = 85;
+//# sourceMappingURL=ssa.d.ts.map

package/dist/engines/data/ssa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssa.d.ts","sourceRoot":"","sources":["../../../src/engines/data/ssa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAc7E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAK/C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC"}

package/dist/engines/data/ssa.js

@@ -0,0 +1,55 @@
+/**
+ * Self-contained SSA constants subset for the @markcolabs/mcp package.
+ *
+ * Mirrored from site/src/data/annual-limits.js and site/src/utils/social-security-engine.js
+ * (re-export-of-truth pattern). Per ADR-0039 § 5 + S136 kickoff: the npm-published
+ * MCP package may NOT import from site/src/ at runtime, so the regulatory data
+ * subset that the SS engine depends on is mirrored here. When site values change,
+ * update this file in lockstep with the source and bump the SS engine ENGINE_VERSION.
+ *
+ * Source of truth: site/src/data/annual-limits.js
+ * - SSA_BEND_POINTS keyed by eligibility year (year a person turns 62)
+ * - SS_WAGE_BASE keyed by calendar year (max earnings subject to SS tax)
+ * Source: SSA Fact Sheet, https://www.ssa.gov/oact/cola/cbb.html
+ *         SSA Bend Points history, https://www.ssa.gov/oact/cola/bendpoints.html
+ *
+ * Last verified: 2026-05-09 (matches site annual-limits.js verification dates).
+ */
+/**
+ * Average Wage Indexing series bend points by eligibility year.
+ * Eligibility year = year person turns 62.
+ *
+ * Subset includes 2014–2026; older years are not needed for current users
+ * (someone born in 1952 turned 62 in 2014; older birthdays use even-older bend
+ * points but the SS engine accepts anything in the lookup, falling back to the
+ * latest available year with `estimated: true`).
+ */
+export const SSA_BEND_POINTS = {
+    2014: { first: 816, second: 4917 },
+    2015: { first: 826, second: 4980 },
+    2016: { first: 856, second: 5157 },
+    2017: { first: 885, second: 5336 },
+    2018: { first: 895, second: 5397 },
+    2019: { first: 926, second: 5583 },
+    2020: { first: 960, second: 5785 },
+    2021: { first: 996, second: 6002 },
+    2022: { first: 1024, second: 6172 },
+    2023: { first: 1115, second: 6721 },
+    2024: { first: 1174, second: 7078 },
+    2025: { first: 1226, second: 7391 },
+    2026: { first: 1286, second: 7749 },
+};
+/**
+ * Social Security wage base by calendar year (max earnings subject to SS tax).
+ */
+export const SS_WAGE_BASE = {
+    2025: 176_100,
+    2026: 176_100, // SSA Fact Sheet 2026 (verified AL-2026-001, S134)
+    2027: 180_000, // Projected
+    2028: 184_000, // Projected
+};
+/**
+ * Default life expectancy used by lifetime-benefit projections (SSA actuarial table proxy).
+ */
+export const DEFAULT_LIFE_EXPECTANCY = 85;
+//# sourceMappingURL=ssa.js.map

package/dist/engines/data/ssa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssa.js","sourceRoot":"","sources":["../../../src/engines/data/ssa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAsD;IAChF,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAClC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAClC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAClC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAClC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAClC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAClC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAClC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;IAClC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IACnC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IACnC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IACnC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IACnC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAA2B;IAClD,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,OAAO,EAAE,mDAAmD;IAClE,IAAI,EAAE,OAAO,EAAE,YAAY;IAC3B,IAAI,EAAE,OAAO,EAAE,YAAY;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC"}

package/dist/engines/mortgage.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Mortgage engine — lifted from site/src/pages/mortgage-calculator/mortgage-calculator.js
+ * (function `calculateMonthlyPI`).
+ *
+ * Per ADR-0039 § 5 (Calc-Engine Lift Pattern):
+ * - Pure synchronous functions of inputs → results. No DOM, no fetch.
+ * - ENGINE_VERSION bumps when math changes (semver).
+ * - Parity tests at packages/mcp/test/parity/mortgage.test.ts gate this engine
+ *   against the source site calculator JS to the cent.
+ *
+ * Math reference (standard amortization formula):
+ *   M = P * [r(1+r)^n] / [(1+r)^n - 1]
+ *   where:
+ *     M = monthly payment
+ *     P = principal (loan amount)
+ *     r = monthly interest rate (annual / 12, as decimal)
+ *     n = number of monthly payments (years * 12)
+ *
+ * For 0% rate the formula reduces to: M = P / n
+ */
+/**
+ * SemVer of the mortgage engine math. Bumps when math changes OR when the
+ * package's overall surface area changes meaningfully (S136 batch bump).
+ * - 0.1.0: initial v1 lift from mortgage-calculator.js (Sprint 135 Item 5).
+ * - 0.2.0: minor batch bump on S136 (no math change here, but package adds
+ *   3 new engines; bump keeps cross-engine ENGINE_VERSION values aligned for
+ *   the v0.1.0 npm publish surface).
+ */
+export declare const ENGINE_VERSION = "0.2.0";
+/**
+ * Inputs to the mortgage monthly-payment engine.
+ *
+ * Per ADR-0039 § 2:
+ * - Monetary fields are bare USD numbers.
+ * - Percentage fields use whole-number-percent units (e.g., 6.5 for 6.5%).
+ *
+ * NOTE on convention vs. sprint prompt: the sprint prompt referenced
+ * decimal-rate inputs (0.065). ADR-0039 § 2 locks the `Percent` suffix +
+ * whole-number-percent convention. The contract wins; this engine accepts
+ * `annualRatePercent` (e.g., 6.5).
+ */
+export interface MortgageMonthlyPaymentInput {
+    /** Principal loan amount in USD. */
+    principal: number;
+    /** Annual interest rate as whole-number percent (e.g., 6.5 for 6.5%). */
+    annualRatePercent: number;
+    /** Loan term in years. Must be a positive integer. */
+    termYears: number;
+}
+/**
+ * Result payload (what goes inside ToolResult.result).
+ */
+export interface MortgageMonthlyPaymentResult {
+    /** Monthly principal & interest payment, in USD. */
+    monthlyPayment: number;
+    /** Total interest paid over the life of the loan, in USD. */
+    totalInterest: number;
+    /** Total paid (principal + interest) over the life of the loan, in USD. */
+    totalPaid: number;
+}
+/**
+ * Compute the monthly principal & interest payment.
+ *
+ * 1-to-1 port of site/src/pages/mortgage-calculator/mortgage-calculator.js
+ * function `calculateMonthlyPI`. Same math, same edge case handling
+ * (0% rate → straight-line amortization).
+ */
+export declare function monthlyPayment(input: MortgageMonthlyPaymentInput): MortgageMonthlyPaymentResult;
+//# sourceMappingURL=mortgage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mortgage.d.ts","sourceRoot":"","sources":["../../src/engines/mortgage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,2BAA2B;IAC1C,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,2BAA2B,GACjC,4BAA4B,CAwB9B"}

package/dist/engines/mortgage.js

@@ -0,0 +1,59 @@
+/**
+ * Mortgage engine — lifted from site/src/pages/mortgage-calculator/mortgage-calculator.js
+ * (function `calculateMonthlyPI`).
+ *
+ * Per ADR-0039 § 5 (Calc-Engine Lift Pattern):
+ * - Pure synchronous functions of inputs → results. No DOM, no fetch.
+ * - ENGINE_VERSION bumps when math changes (semver).
+ * - Parity tests at packages/mcp/test/parity/mortgage.test.ts gate this engine
+ *   against the source site calculator JS to the cent.
+ *
+ * Math reference (standard amortization formula):
+ *   M = P * [r(1+r)^n] / [(1+r)^n - 1]
+ *   where:
+ *     M = monthly payment
+ *     P = principal (loan amount)
+ *     r = monthly interest rate (annual / 12, as decimal)
+ *     n = number of monthly payments (years * 12)
+ *
+ * For 0% rate the formula reduces to: M = P / n
+ */
+/**
+ * SemVer of the mortgage engine math. Bumps when math changes OR when the
+ * package's overall surface area changes meaningfully (S136 batch bump).
+ * - 0.1.0: initial v1 lift from mortgage-calculator.js (Sprint 135 Item 5).
+ * - 0.2.0: minor batch bump on S136 (no math change here, but package adds
+ *   3 new engines; bump keeps cross-engine ENGINE_VERSION values aligned for
+ *   the v0.1.0 npm publish surface).
+ */
+export const ENGINE_VERSION = "0.2.0";
+/**
+ * Compute the monthly principal & interest payment.
+ *
+ * 1-to-1 port of site/src/pages/mortgage-calculator/mortgage-calculator.js
+ * function `calculateMonthlyPI`. Same math, same edge case handling
+ * (0% rate → straight-line amortization).
+ */
+export function monthlyPayment(input) {
+    const { principal, annualRatePercent, termYears } = input;
+    const monthlyRate = annualRatePercent / 100 / 12;
+    const numPayments = termYears * 12;
+    let monthly;
+    if (annualRatePercent === 0) {
+        monthly = principal / numPayments;
+    }
+    else {
+        monthly =
+            principal *
+                ((monthlyRate * Math.pow(1 + monthlyRate, numPayments)) /
+                    (Math.pow(1 + monthlyRate, numPayments) - 1));
+    }
+    const totalPaid = monthly * numPayments;
+    const totalInterest = totalPaid - principal;
+    return {
+        monthlyPayment: monthly,
+        totalInterest,
+        totalPaid,
+    };
+}
+//# sourceMappingURL=mortgage.js.map

package/dist/engines/mortgage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mortgage.js","sourceRoot":"","sources":["../../src/engines/mortgage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAmCtC;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAkC;IAElC,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IAE1D,MAAM,WAAW,GAAG,iBAAiB,GAAG,GAAG,GAAG,EAAE,CAAC;IACjD,MAAM,WAAW,GAAG,SAAS,GAAG,EAAE,CAAC;IAEnC,IAAI,OAAe,CAAC;IACpB,IAAI,iBAAiB,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC;IACpC,CAAC;SAAM,CAAC;QACN,OAAO;YACL,SAAS;gBACT,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,EAAE,WAAW,CAAC,CAAC;oBACrD,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;IACxC,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC;IAE5C,OAAO;QACL,cAAc,EAAE,OAAO;QACvB,aAAa;QACb,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/engines/paycheck.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Paycheck net-pay engine — lifted from
+ * site/src/utils/paycheck-tax-engine.js (functions `calculateBracketTax`,
+ * `calculateFederalWithholding`, `calculateFICA`).
+ *
+ * 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
+ *
+ * The state-tax limitation is documented in the tool envelope and disclaimer.
+ *
+ * Math reference (annualized):
+ *   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
+ *   netAnnual = grossAnnual − preTaxAnnual − federalTax − ficaTax − stateTax − postTaxAnnual
+ *   per-paycheck values = annual / payPeriodsPerYear
+ */
+import { type FilingStatus, type PayFrequencyLabel } from "./data/federalTax.js";
+/**
+ * SemVer of the paycheck engine.
+ * - 0.2.0: initial port (S136). Co-incident with the package-wide S136 batch bump.
+ */
+export declare const ENGINE_VERSION = "0.2.0";
+/** Inputs to the paycheck net-pay engine. */
+export interface PaycheckNetPayInput {
+    /** Gross annual salary, USD. */
+    grossAnnualSalary: number;
+    /** Pay frequency. */
+    payFrequency: PayFrequencyLabel;
+    /** Federal filing status (camelCase, matches paycheck engine). */
+    federalFilingStatus: FilingStatus;
+    /** Two-letter state code (e.g., "CA", "TX"). */
+    state: string;
+    /** Number of dependents claimed. */
+    dependents: number;
+    /** Total pre-tax deductions (401k, HSA, FSA, etc.) per year, USD. */
+    preTaxDeductionsAnnual: number;
+    /** Total post-tax deductions (Roth contributions, garnishments, etc.) per year, USD. */
+    postTaxDeductionsAnnual: number;
+}
+/** Result payload returned by the engine. */
+export interface PaycheckNetPayResult {
+    /** Gross pay per paycheck, USD. */
+    grossPerPaycheck: number;
+    /** Federal income-tax withholding per paycheck, USD. */
+    federalTax: number;
+    /** Total FICA per paycheck (SS + Medicare + Additional Medicare), USD. */
+    ficaTax: number;
+    /** State-tax estimate per paycheck, USD. */
+    stateTax: number;
+    /** Net pay per paycheck, USD. */
+    netPay: number;
+    /** Number of pay periods per year. */
+    payPeriodsPerYear: number;
+    /** Annualized federal tax, USD. */
+    federalTaxAnnual: number;
+    /** Annualized FICA, USD. */
+    ficaTaxAnnual: number;
+    /** Annualized state tax estimate, USD. */
+    stateTaxAnnual: number;
+    /** Annualized net pay, USD. */
+    netPayAnnual: number;
+    /** Whether the state has no income tax. */
+    noStateIncomeTax: boolean;
+}
+/**
+ * Compute net pay (and the annualized + per-paycheck breakdown).
+ *
+ * Implementation note: dependents currently has no effect under the simplified
+ * 2026 federal Percentage Method (the site engine likewise doesn't apply
+ * dependent credits in the per-paycheck calc). The field is part of the
+ * contract for forward compatibility (Form W-4 line 3 dependents credit may be
+ * added in a later engine version).
+ */
+export declare function netPay(input: PaycheckNetPayInput): PaycheckNetPayResult;
+//# sourceMappingURL=paycheck.d.ts.map

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

@@ -0,0 +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;;;GAGG;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"}

package/dist/engines/paycheck.js

@@ -0,0 +1,109 @@
+/**
+ * Paycheck net-pay engine — lifted from
+ * site/src/utils/paycheck-tax-engine.js (functions `calculateBracketTax`,
+ * `calculateFederalWithholding`, `calculateFICA`).
+ *
+ * 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
+ *
+ * The state-tax limitation is documented in the tool envelope and disclaimer.
+ *
+ * Math reference (annualized):
+ *   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
+ *   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";
+/**
+ * SemVer of the paycheck engine.
+ * - 0.2.0: initial port (S136). Co-incident with the package-wide S136 batch bump.
+ */
+export const ENGINE_VERSION = "0.2.0";
+const ROUND = (v) => Math.round(v * 100) / 100;
+/**
+ * Progressive bracket lookup — verbatim port of site `calculateBracketTax`.
+ */
+function bracketTax(taxableIncome, brackets) {
+    if (!brackets.length || taxableIncome <= 0)
+        return 0;
+    for (let i = brackets.length - 1; i >= 0; i--) {
+        const b = brackets[i];
+        if (taxableIncome > b.min) {
+            const taxableInBracket = taxableIncome - b.min;
+            return b.baseTax + taxableInBracket * b.rate;
+        }
+    }
+    return 0;
+}
+/**
+ * Compute net pay (and the annualized + per-paycheck breakdown).
+ *
+ * Implementation note: dependents currently has no effect under the simplified
+ * 2026 federal Percentage Method (the site engine likewise doesn't apply
+ * dependent credits in the per-paycheck calc). The field is part of the
+ * contract for forward compatibility (Form W-4 line 3 dependents credit may be
+ * added in a later engine version).
+ */
+export function netPay(input) {
+    const { grossAnnualSalary, payFrequency, federalFilingStatus, state, preTaxDeductionsAnnual, postTaxDeductionsAnnual, } = input;
+    const periodsPerYear = PAY_PERIODS_PER_YEAR[payFrequency];
+    // Annual basis after pre-tax deductions (income-tax-reducible).
+    const adjustedAnnual = Math.max(0, grossAnnualSalary - preTaxDeductionsAnnual);
+    // Federal: standard deduction → taxable income → bracket lookup.
+    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).
+    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
+        : 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).
+    const stateUpper = state.trim().toUpperCase();
+    const noStateIncomeTax = NO_TAX_STATES.includes(stateUpper);
+    const stateTaxAnnual = noStateIncomeTax ? 0 : federalTaxable * 0.05;
+    // Net annual + per-paycheck.
+    const netPayAnnual = grossAnnualSalary -
+        preTaxDeductionsAnnual -
+        federalTaxAnnual -
+        ficaTaxAnnual -
+        stateTaxAnnual -
+        postTaxDeductionsAnnual;
+    return {
+        grossPerPaycheck: ROUND(grossAnnualSalary / periodsPerYear),
+        federalTax: ROUND(federalTaxAnnual / periodsPerYear),
+        ficaTax: ROUND(ficaTaxAnnual / periodsPerYear),
+        stateTax: ROUND(stateTaxAnnual / periodsPerYear),
+        netPay: ROUND(netPayAnnual / periodsPerYear),
+        payPeriodsPerYear: periodsPerYear,
+        federalTaxAnnual: ROUND(federalTaxAnnual),
+        ficaTaxAnnual: ROUND(ficaTaxAnnual),
+        stateTaxAnnual: ROUND(stateTaxAnnual),
+        netPayAnnual: ROUND(netPayAnnual),
+        noStateIncomeTax,
+    };
+}
+//# sourceMappingURL=paycheck.js.map

package/dist/engines/paycheck.js.map

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

package/dist/engines/retirement401k.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 401(k) projection engine — lifted from
+ * site/src/pages/401k-retirement-calculator/401k-retirement-calculator.js
+ * (functions `calculateEmployerMatch`, `calculateFutureValue`,
+ * `generateYearlyBreakdown`, `getIRSLimit`, `getCatchUpAmount`,
+ * `calculate401kResults`).
+ *
+ * Per ADR-0039 § 5 (Calc-Engine Lift Pattern):
+ * - Pure synchronous functions of inputs → results. No DOM, no fetch.
+ * - ENGINE_VERSION bumps when math changes.
+ * - Parity tests at packages/mcp/test/parity/retirement401k.test.ts gate this
+ *   engine against the source site calculator JS.
+ *
+ * MCP-side enhancement on top of the lift: the kickoff-defined input
+ * `annualSalaryGrowthPercent` is honored in this engine. The site engine
+ * applies a *flat* annual contribution; here we step year-by-year so each
+ * year's employee contribution + employer match scales with the cumulative
+ * salary growth. When `annualSalaryGrowthPercent === 0` the math is identical
+ * to the site engine (parity test "happy path" covers this).
+ *
+ * Math reference (year-by-year, mirroring the site's Math.pow form when growth=0):
+ *   contrib_year_i  = annualSalary * (1 + g)^i * (employeePct/100)
+ *                       (capped per IRS limit)
+ *   match_year_i    = annualSalary * (1 + g)^i * (matchedPct/100) * (employerMatchPct/100)
+ *   balance_year_i  = balance_year_{i-1} * (1 + r) + contrib_year_i + match_year_i
+ *   balance_year_0  = currentBalance
+ *
+ * IRS limits: per IRS Notice 2025-67 (2026) — see engines/data/irs2026.ts.
+ */
+/**
+ * SemVer of the 401(k) projection engine.
+ * - 0.2.0: initial port (S136). Co-incident with the package-wide S136 batch bump.
+ */
+export declare const ENGINE_VERSION = "0.2.0";
+/** Inputs to the 401(k) projection engine. */
+export interface Retirement401kProjectionInput {
+    /** Current 401(k) balance, USD. */
+    currentBalance: number;
+    /** Current annual gross salary, USD. */
+    annualSalary: number;
+    /** Employee contribution as percent of salary (0-100). */
+    contributionPercent: number;
+    /**
+     * Employer match percent (0-100). Example: 50 means employer contributes
+     * $0.50 for each $1 the employee contributes, up to the match cap.
+     */
+    employerMatchPercent: number;
+    /**
+     * Cap on how much of the employee's contribution percent the employer
+     * matches. Example: 6 means the employer matches up to 6% of salary.
+     */
+    employerMatchLimitPercent: number;
+    /** Annual salary growth percent (0-20). 0 mirrors the site engine's flat-salary path. */
+    annualSalaryGrowthPercent: number;
+    /** Annual investment return percent (0-20). */
+    annualReturnPercent: number;
+    /** Current age (used for catch-up eligibility). */
+    currentAge: number;
+    /** Target retirement age (must be > currentAge). */
+    retirementAge: number;
+    /**
+     * Whether to enable catch-up contributions when eligible. Default true:
+     * if the user's age is in a catch-up window, apply the catch-up cap.
+     * Mirrors the site `catchUpToggle` form field semantics.
+     */
+    catchUpEnabled?: boolean;
+}
+/** One row of the year-by-year projection table. */
+export interface Retirement401kYearRow {
+    /** Years from start (1..yearsToRetirement). */
+    year: number;
+    /** Age at end of this year. */
+    age: number;
+    /** Employee contribution this year (after IRS cap), USD. */
+    employeeContribution: number;
+    /** Employer match this year, USD. */
+    employerMatch: number;
+    /** Investment growth credited this year, USD. */
+    growth: number;
+    /** Ending balance for this year, USD. */
+    endingBalance: number;
+}
+/** Result payload returned by the engine. */
+export interface Retirement401kProjectionResult {
+    /** Final 401(k) balance at retirement age, USD. */
+    futureBalance: number;
+    /** Sum of all employee contributions over the projection, USD. */
+    totalContributions: number;
+    /** Sum of all employer match contributions over the projection, USD. */
+    employerContribTotal: number;
+    /** futureBalance − (currentBalance + totalContributions + employerContribTotal). */
+    growthEarned: number;
+    /** Year-by-year rows from year 1 to year yearsToRetirement. */
+    yearByYear: Retirement401kYearRow[];
+}
+/**
+ * Project a 401(k) balance year by year through retirement.
+ *
+ * Uses the same per-year accumulation pattern as the site's
+ * `generateYearlyBreakdown` / `calculateFutureValue` (compounded annual return,
+ * end-of-year contributions). Differs from the site only in honoring
+ * `annualSalaryGrowthPercent` per kickoff input list.
+ */
+export declare function projection(input: Retirement401kProjectionInput): Retirement401kProjectionResult;
+//# sourceMappingURL=retirement401k.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retirement401k.d.ts","sourceRoot":"","sources":["../../src/engines/retirement401k.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH;;;GAGG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,8CAA8C;AAC9C,MAAM,WAAW,6BAA6B;IAC5C,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,yBAAyB,EAAE,MAAM,CAAC;IAClC,yFAAyF;IACzF,yBAAyB,EAAE,MAAM,CAAC;IAClC,+CAA+C;IAC/C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,6CAA6C;AAC7C,MAAM,WAAW,8BAA8B;IAC7C,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,UAAU,EAAE,qBAAqB,EAAE,CAAC;CACrC;AA4CD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,6BAA6B,GACnC,8BAA8B,CA2EhC"}