@retiregolden/engine 0.1.0

package/dist/testing/money.js

@@ -0,0 +1,17 @@
+/**
+ * Tolerance assertions for money and percentages. Deliberately framework-free
+ * (a thrown Error fails a test in any runner), so `@retiregolden/engine/testing/*`
+ * carries no runtime dependency on vitest for consumers.
+ */
+function expectWithin(kind, actual, expected, tolerance) {
+    const delta = Math.abs(actual - expected);
+    if (Number.isNaN(delta) || delta > tolerance) {
+        throw new Error(`expected ${kind} ${actual} to be within ${tolerance} of ${expected} (off by ${delta})`);
+    }
+}
+export function expectMoney(actual, expected, tolerance = 0.01) {
+    expectWithin('money', actual, expected, tolerance);
+}
+export function expectPercent(actual, expected, tolerance = 0.0001) {
+    expectWithin('percent', actual, expected, tolerance);
+}

package/dist/testing/planFixtures.d.ts

@@ -0,0 +1,29 @@
+import { type Account, type IncomeStream, type Plan } from '../model/plan.js';
+import type { ProjectionResult, TaxCalculator } from '../projection/types.js';
+export declare function testId(prefix?: string): string;
+export declare function fixedNow(): Date;
+export interface SinglePlanOptions {
+    dob?: string;
+    planningAge?: number;
+    retirementAge?: number | null;
+    state?: string;
+}
+export interface CouplePlanOptions {
+    p1Dob?: string;
+    p2Dob?: string;
+    p1PlanningAge?: number;
+    p2PlanningAge?: number;
+    p1RetirementAge?: number | null;
+    p2RetirementAge?: number | null;
+    state?: string;
+}
+export declare function singlePersonPlan(opts?: SinglePlanOptions): Plan;
+export declare function couplePlan(opts?: CouplePlanOptions): Plan;
+export declare function cashAccount(id: string, balance: number): Account;
+export declare function taxableAccount(id: string, balance: number, costBasis: number): Account;
+export declare function traditionalAccount(id: string, balance: number, ownerPersonId?: string, kind?: 'ira' | 'employer'): Account;
+export declare function recurringOrdinaryIncome(id: string, annualAmount: number, startYear?: number | null): IncomeStream;
+export declare function socialSecurityIncome(id: string, piaMonthly: number, claimAgeYears: number, personId?: string): IncomeStream;
+export declare function validatePlan(plan: Plan): Plan;
+export declare function productionTaxCalculator(): TaxCalculator;
+export declare function runPlan(plan: Plan, taxCalculator: TaxCalculator, startYear?: number): ProjectionResult;

package/dist/testing/planFixtures.js

@@ -0,0 +1,141 @@
+import { createEmptyPlan, parsePlan } from '../model/plan.js';
+import { combineTaxCalculators, createFederalTaxCalculator } from '../tax/federalTax.js';
+import { createStateTaxCalculator } from '../tax/stateTax.js';
+import { simulatePlan } from '../projection/simulate.js';
+let idCounter = 0;
+export function testId(prefix = 'test') {
+    idCounter += 1;
+    return `${prefix}-${idCounter}`;
+}
+export function fixedNow() {
+    return new Date('2026-01-01T00:00:00.000Z');
+}
+export function singlePersonPlan(opts = {}) {
+    const plan = createEmptyPlan({ newId: () => testId('plan'), now: fixedNow, name: 'Test plan' });
+    plan.household.filingStatus = 'single';
+    plan.household.state = opts.state ?? 'KY';
+    plan.household.people = [
+        {
+            id: 'p1',
+            name: 'Pat',
+            dob: opts.dob ?? '1966-01-01',
+            sex: 'average',
+            retirementAge: opts.retirementAge ?? null,
+            longevity: { planningAge: opts.planningAge ?? 60, source: 'manual' },
+        },
+    ];
+    plan.assumptions.inflationPct = 0;
+    plan.assumptions.healthcareExtraInflationPct = 0;
+    plan.assumptions.defaultReturnPct = 0;
+    plan.assumptions.ssCola = { mode: 'fixed', annualPct: 0 };
+    plan.assumptions.ssHaircut = null;
+    plan.assumptions.stateEffectiveTaxPct = 0;
+    plan.assumptions.recentAnnualMagi = 0;
+    plan.accounts = [];
+    plan.incomes = [];
+    plan.expenses.baseAnnual = 0;
+    plan.expenses.phases = [];
+    plan.expenses.oneTimeGoals = [];
+    plan.expenses.healthcare = {
+        pre65MonthlyPremiumPerPerson: 0,
+        applyAcaCredit: false,
+        medicareExtrasMonthlyPerPerson: 0,
+    };
+    plan.strategies.withdrawalOrder = { mode: 'sequential' };
+    plan.strategies.rothConversion = { mode: 'none' };
+    plan.strategies.qcdAnnual = 0;
+    return plan;
+}
+export function couplePlan(opts = {}) {
+    const plan = singlePersonPlan({
+        dob: opts.p1Dob,
+        planningAge: opts.p1PlanningAge,
+        retirementAge: opts.p1RetirementAge,
+        state: opts.state,
+    });
+    plan.household.filingStatus = 'marriedFilingJointly';
+    plan.household.people = [
+        {
+            id: 'p1',
+            name: 'Pat',
+            dob: opts.p1Dob ?? '1966-01-01',
+            sex: 'average',
+            retirementAge: opts.p1RetirementAge ?? null,
+            longevity: { planningAge: opts.p1PlanningAge ?? 60, source: 'manual' },
+        },
+        {
+            id: 'p2',
+            name: 'Robin',
+            dob: opts.p2Dob ?? '1966-01-01',
+            sex: 'average',
+            retirementAge: opts.p2RetirementAge ?? null,
+            longevity: { planningAge: opts.p2PlanningAge ?? 60, source: 'manual' },
+        },
+    ];
+    return plan;
+}
+export function cashAccount(id, balance) {
+    return { type: 'cash', id, name: id, ownerPersonId: null, annualReturnPct: 0, balance, annualContribution: 0 };
+}
+export function taxableAccount(id, balance, costBasis) {
+    return {
+        type: 'taxable',
+        id,
+        name: id,
+        ownerPersonId: null,
+        annualReturnPct: 0,
+        balance,
+        costBasis,
+        interestYieldPct: 0,
+        dividendYieldPct: 0,
+        qualifiedRatio: 0.85,
+        reinvestDividends: true,
+        annualContribution: 0,
+    };
+}
+export function traditionalAccount(id, balance, ownerPersonId = 'p1', kind = 'ira') {
+    return {
+        type: 'traditional',
+        id,
+        name: id,
+        ownerPersonId,
+        annualReturnPct: 0,
+        kind,
+        balance,
+        annualContribution: 0,
+    };
+}
+export function recurringOrdinaryIncome(id, annualAmount, startYear = null) {
+    return {
+        type: 'recurring',
+        id,
+        label: id,
+        annualAmount,
+        startYear,
+        endYear: null,
+        inflationAdjusted: false,
+        taxTreatment: 'ordinary',
+    };
+}
+export function socialSecurityIncome(id, piaMonthly, claimAgeYears, personId = 'p1') {
+    return {
+        type: 'socialSecurity',
+        id,
+        personId,
+        piaMonthly,
+        earnings: null,
+        claimAge: { years: claimAgeYears, months: 0 },
+    };
+}
+export function validatePlan(plan) {
+    const parsed = parsePlan(plan);
+    if (!parsed.ok)
+        throw new Error(parsed.issues.join('; '));
+    return parsed.plan;
+}
+export function productionTaxCalculator() {
+    return combineTaxCalculators(createFederalTaxCalculator(), createStateTaxCalculator());
+}
+export function runPlan(plan, taxCalculator, startYear = 2026) {
+    return simulatePlan(validatePlan(plan), { startYear, taxCalculator });
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@retiregolden/engine",
+  "version": "0.1.0",
+  "description": "Pure-TypeScript retirement-planning engine: year-by-year household projection with federal + state taxes, Social Security, RMDs, Roth conversions, withdrawal strategies, Monte Carlo, and an LP optimizer. Deterministic, no DOM, no network.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RetireGolden/RetireGolden.git",
+    "directory": "packages/engine"
+  },
+  "homepage": "https://github.com/RetireGolden/RetireGolden/tree/main/packages/engine#readme",
+  "bugs": "https://github.com/RetireGolden/RetireGolden/issues",
+  "keywords": [
+    "retirement",
+    "financial-planning",
+    "social-security",
+    "roth-conversion",
+    "monte-carlo",
+    "tax"
+  ],
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./decisions": {
+      "types": "./dist/decisions/index.d.ts",
+      "default": "./dist/decisions/index.js"
+    },
+    "./params": {
+      "types": "./dist/params/index.d.ts",
+      "default": "./dist/params/index.js"
+    },
+    "./params/state": {
+      "types": "./dist/params/state/index.d.ts",
+      "default": "./dist/params/state/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint .",
+    "test": "tsc -p tsconfig.test.json && vitest run",
+    "test:coverage": "tsc -p tsconfig.test.json && vitest run --coverage",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "highs": "^1.14.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@vitest/coverage-v8": "^4.1.6",
+    "eslint": "^10.3.0",
+    "globals": "^17.6.0",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.59.2",
+    "vitest": "^4.0.16"
+  }
+}