@retiregolden/planner-ui 0.1.0

package/src/planner/examples/buildAnnuityEstate.ts

@@ -0,0 +1,137 @@
+/** Annuity purchases + estate beneficiaries — demonstrates guaranteed income (SPIA/QLAC),
+ * purchase funding, exclusion ratio / RMD relief, and per-account beneficiary modeling for
+ * estate calculations (spouse rollover vs charity vs non-spouse).
+ * Positive case for estate/guaranteed-income depth enhancement.
+ */
+
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { EXAMPLE_FIXED_YEAR, exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'annuity-purchases-estate'
+
+export function buildAnnuityEstate(): Plan {
+  const me = exampleEntityId(EXAMPLE_ID, 'me')
+  const partner = exampleEntityId(EXAMPLE_ID, 'partner')
+  const plan = createEmptyPlan({ name: 'Annuity ladder with estate planning', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+
+  plan.household = {
+    filingStatus: 'marriedFilingJointly',
+    hasQualifyingDependent: false,
+    state: 'FL',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: me, name: 'Jordan', dob: '1961-03-10', sex: 'male', retirementAge: 65, longevity: { planningAge: 90, source: 'manual' } },
+      { id: partner, name: 'Taylor', dob: '1963-11-22', sex: 'female', retirementAge: 64, longevity: { planningAge: 93, source: 'manual' } },
+    ],
+  }
+
+  // Accounts including annuity purchases funded correctly per rules
+  const cashId = exampleEntityId(EXAMPLE_ID, 'cash')
+  const tiraId = exampleEntityId(EXAMPLE_ID, 'tira')
+  plan.accounts = [
+    { type: 'cash', id: cashId, name: 'Emergency cash', ownerPersonId: null, annualReturnPct: 2, balance: 315_000, annualContribution: 0 },
+    { type: 'traditional', id: tiraId, name: 'Jordan traditional IRA', ownerPersonId: me, annualReturnPct: null, kind: 'ira', balance: 915_000, annualContribution: 0, estateBeneficiary: { destination: 'spouse' } },
+    // SPIA non-qualified funded from cash
+    {
+      type: 'annuity',
+      id: exampleEntityId(EXAMPLE_ID, 'spiA'),
+      name: 'SPIA (non-qualified)',
+      ownerPersonId: null,
+      annualReturnPct: null,
+      startAge: 66,
+      monthlyAmount: 1450,
+      colaPct: 0,
+      taxablePct: 35,
+      purchase: {
+        year: EXAMPLE_FIXED_YEAR + 1,
+        premium: 220_000,
+        fundingAccountId: cashId,
+        taxQualification: 'nonQualified',
+      },
+      estateBeneficiary: { destination: 'charity', charityPct: 100 },
+    },
+    // QLAC qualified funded from traditional
+    {
+      type: 'annuity',
+      id: exampleEntityId(EXAMPLE_ID, 'qlac'),
+      name: 'QLAC (qualified deferred)',
+      ownerPersonId: null,
+      annualReturnPct: null,
+      startAge: 80,
+      monthlyAmount: 920,
+      colaPct: 2.5,
+      taxablePct: 100,
+      purchase: {
+        year: EXAMPLE_FIXED_YEAR + 2,
+        premium: 135_000,
+        fundingAccountId: tiraId,
+        taxQualification: 'qualified',
+        qlac: true,
+      },
+    },
+    { type: 'traditional', id: exampleEntityId(EXAMPLE_ID, '401k'), name: 'Jordan 401k', ownerPersonId: me, annualReturnPct: null, kind: 'employer', balance: 310_000, annualContribution: 0, estateBeneficiary: { destination: 'nonSpouse' } },
+    { type: 'roth', id: exampleEntityId(EXAMPLE_ID, 'roth'), name: 'Roth IRA', ownerPersonId: me, annualReturnPct: null, kind: 'ira', balance: 50_000, annualContribution: 0 },
+  ]
+
+  plan.incomes = [
+    { type: 'socialSecurity', id: exampleEntityId(EXAMPLE_ID, 'ss-j'), personId: me, piaMonthly: 2650, earnings: null, claimAge: { years: 70, months: 0 } },
+    { type: 'socialSecurity', id: exampleEntityId(EXAMPLE_ID, 'ss-t'), personId: partner, piaMonthly: 1720, earnings: null, claimAge: { years: 67, months: 0 } },
+  ]
+
+  // Pension as account (not income)
+  type PensionAccount = Extract<Plan['accounts'][number], { type: 'pension' }>
+  const pension: PensionAccount = {
+    type: 'pension',
+    id: exampleEntityId(EXAMPLE_ID, 'pension'),
+    name: 'Pension (Jordan)',
+    ownerPersonId: me,
+    annualReturnPct: null,
+    startAge: 65,
+    monthlyAmount: 1500,
+    colaPct: 2.0,
+    survivorPct: 50,
+  }
+  plan.accounts.push(pension)
+
+  plan.expenses = {
+    baseAnnual: 78_000,
+    phases: [
+      { fromAge: 75, multiplier: 0.88 },
+    ],
+    oneTimeGoals: [],
+    healthcare: { pre65MonthlyPremiumPerPerson: 880, applyAcaCredit: false, medicareExtrasMonthlyPerPerson: 210 },
+  }
+
+  plan.strategies = {
+    withdrawalOrder: { mode: 'sequential' },
+    rothConversion: { mode: 'fillToTarget', target: 'topOfBracket', targetValue: 24, startYear: EXAMPLE_FIXED_YEAR + 1, endYear: EXAMPLE_FIXED_YEAR + 7 },
+    qcdAnnual: 5000,
+  }
+
+  plan.assumptions = {
+    inflationPct: 2.3,
+    healthcareExtraInflationPct: 3,
+    defaultReturnPct: 5.2,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 120_000,
+    heirTaxRatePct: 28,
+    safeWithdrawalRatePct: 3.5,
+  }
+
+  // Scenario: no Roth conversions (for A-B comparison of annuity effect)
+  plan.scenarios = [
+    {
+      id: exampleEntityId(EXAMPLE_ID, 'no-conversion'),
+      name: 'No Roth conversions (manual compare)',
+      patch: { strategies: { rothConversion: { mode: 'none' } } },
+    },
+  ]
+
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`annuity-purchases-estate invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildBaristaFire.ts

@@ -0,0 +1,115 @@
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'barista-fire'
+
+export function buildBaristaFire(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const plan = createEmptyPlan({ name: 'Barista FIRE', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+  plan.household = {
+    filingStatus: 'single',
+    hasQualifyingDependent: false,
+    state: 'OR',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: p1, name: 'Robin', dob: '1996-01-01', sex: 'average', retirementAge: 40, longevity: { planningAge: 90, source: 'manual' } },
+    ],
+  }
+  
+  // Born 1996. Current year is 2026. Age is 30.
+  // Turns 40 in 2036. Turns 65 in 2061.
+  const startYear = 2026
+  const turn40Year = startYear + 10
+  const turn65Year = startYear + 35
+
+  plan.accounts = [
+    {
+      type: 'traditional',
+      id: exampleEntityId(EXAMPLE_ID, 'pretax-401k'),
+      name: 'Pre-tax 401(k)',
+      ownerPersonId: p1,
+      annualReturnPct: 7.5,
+      kind: 'employer',
+      balance: 120_000,
+      annualContribution: 18_000,
+    },
+    {
+      type: 'roth',
+      id: exampleEntityId(EXAMPLE_ID, 'roth-ira'),
+      name: 'Roth IRA',
+      ownerPersonId: p1,
+      annualReturnPct: 7.5,
+      kind: 'ira',
+      balance: 30_000,
+      annualContribution: 5_000,
+    },
+    {
+      type: 'taxable',
+      id: exampleEntityId(EXAMPLE_ID, 'taxable-brokerage'),
+      name: 'Taxable Brokerage',
+      ownerPersonId: null,
+      annualReturnPct: 7.5,
+      balance: 100_000,
+      costBasis: 80_000,
+      annualContribution: 10_000,
+      contributionSchedule: [
+        {
+          annualAmount: 10_000,
+          fromAge: 30,
+          toAge: 40,
+          escalationPct: 0,
+        },
+      ],
+    },
+  ]
+  plan.incomes = [
+    {
+      type: 'wages',
+      id: exampleEntityId(EXAMPLE_ID, 'primary-wages'),
+      personId: p1,
+      annualGross: 95_000,
+      endAge: 40,
+      realGrowthPct: 3,
+    },
+    {
+      type: 'socialSecurity',
+      id: exampleEntityId(EXAMPLE_ID, 'ss'),
+      personId: p1,
+      piaMonthly: 2_300,
+      earnings: null,
+      claimAge: { years: 67, months: 0 },
+    },
+    {
+      type: 'recurring',
+      id: exampleEntityId(EXAMPLE_ID, 'barista-job'),
+      label: 'Barista part-time work',
+      annualAmount: 35_000,
+      startYear: turn40Year,
+      endYear: turn65Year,
+      inflationAdjusted: true,
+      taxTreatment: 'ordinary',
+    },
+  ]
+  plan.expenses = {
+    baseAnnual: 45_000,
+    phases: [],
+    oneTimeGoals: [],
+    healthcare: { pre65MonthlyPremiumPerPerson: 550, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 200 },
+  }
+  plan.assumptions = {
+    inflationPct: 2.5,
+    healthcareExtraInflationPct: 2,
+    defaultReturnPct: 6,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 95_000,
+    heirTaxRatePct: 25,
+    safeWithdrawalRatePct: 4,
+  }
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`barista-fire invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildBracketFillRoth.ts

@@ -0,0 +1,65 @@
+/** Bracket-fill Roth conversions — converting up to a bracket top. */
+
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { EXAMPLE_FIXED_YEAR, exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'bracket-fill-roth'
+
+export function buildBracketFillRoth(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const p2 = exampleEntityId(EXAMPLE_ID, 'p2')
+  const plan = createEmptyPlan({ name: 'Bracket-fill Roth conversions', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+  plan.household = {
+    filingStatus: 'marriedFilingJointly',
+    hasQualifyingDependent: false,
+    state: 'FL',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: p1, name: 'Morgan', dob: '1953-01-01', sex: 'male', retirementAge: 65, longevity: { planningAge: 92, source: 'manual' } },
+      { id: p2, name: 'Riley', dob: '1955-01-01', sex: 'female', retirementAge: 65, longevity: { planningAge: 94, source: 'manual' } },
+    ],
+  }
+  plan.accounts = [
+    { type: 'cash', id: exampleEntityId(EXAMPLE_ID, 'cash'), name: 'Cash reserve', ownerPersonId: null, annualReturnPct: 2, balance: 80_000, annualContribution: 0 },
+    { type: 'traditional', id: exampleEntityId(EXAMPLE_ID, 'ira-m'), name: 'Morgan IRA', ownerPersonId: p1, annualReturnPct: null, kind: 'ira', balance: 700_000, annualContribution: 0 },
+    { type: 'traditional', id: exampleEntityId(EXAMPLE_ID, 'ira-r'), name: 'Riley IRA', ownerPersonId: p2, annualReturnPct: null, kind: 'ira', balance: 400_000, annualContribution: 0 },
+    { type: 'roth', id: exampleEntityId(EXAMPLE_ID, 'roth'), name: 'Morgan Roth IRA', ownerPersonId: p1, annualReturnPct: null, kind: 'ira', balance: 50_000, annualContribution: 0 },
+  ]
+  plan.incomes = [
+    { type: 'socialSecurity', id: exampleEntityId(EXAMPLE_ID, 'ss-m'), personId: p1, piaMonthly: 2_500, earnings: null, claimAge: { years: 67, months: 0 } },
+    { type: 'socialSecurity', id: exampleEntityId(EXAMPLE_ID, 'ss-r'), personId: p2, piaMonthly: 1_800, earnings: null, claimAge: { years: 67, months: 0 } },
+  ]
+  plan.expenses = {
+    baseAnnual: 90_000,
+    phases: [{ fromAge: 80, multiplier: 0.85 }],
+    oneTimeGoals: [],
+    healthcare: { pre65MonthlyPremiumPerPerson: 0, applyAcaCredit: false, medicareExtrasMonthlyPerPerson: 250 },
+  }
+  plan.strategies = {
+    withdrawalOrder: { mode: 'sequential' },
+    rothConversion: {
+      mode: 'fillToTarget',
+      target: 'topOfBracket',
+      targetValue: 22,
+      startYear: EXAMPLE_FIXED_YEAR,
+      endYear: EXAMPLE_FIXED_YEAR + 8,
+    },
+    qcdAnnual: 10_000,
+  }
+  plan.assumptions = {
+    inflationPct: 2.5,
+    healthcareExtraInflationPct: 3,
+    defaultReturnPct: 5,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 0,
+    heirTaxRatePct: 25,
+    safeWithdrawalRatePct: 4,
+  }
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`bracket-fill roth invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildBridgeEarlyRetirement.ts

@@ -0,0 +1,94 @@
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'bridge-early-retirement'
+
+export function buildBridgeEarlyRetirement(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const plan = createEmptyPlan({ name: 'Bridge to 59½ (SEPP)', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+  plan.household = {
+    filingStatus: 'single',
+    hasQualifyingDependent: false,
+    state: 'CA',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: p1, name: 'Jordan', dob: '1981-01-01', sex: 'average', retirementAge: 45, longevity: { planningAge: 90, source: 'manual' } },
+    ],
+  }
+  plan.accounts = [
+    {
+      type: 'traditional',
+      id: exampleEntityId(EXAMPLE_ID, 'traditional-401k'),
+      name: 'Traditional IRA (SEPP)',
+      ownerPersonId: p1,
+      annualReturnPct: 7.5,
+      kind: 'ira',
+      balance: 1_200_000,
+      annualContribution: 0,
+      sepp: {
+        startAge: 45,
+        method: 'amortization',
+      },
+    },
+    {
+      type: 'roth',
+      id: exampleEntityId(EXAMPLE_ID, 'roth-ira'),
+      name: 'Roth IRA',
+      ownerPersonId: p1,
+      annualReturnPct: 7.5,
+      kind: 'ira',
+      balance: 125_000,
+      annualContribution: 0,
+    },
+    {
+      type: 'taxable',
+      id: exampleEntityId(EXAMPLE_ID, 'taxable-brokerage'),
+      name: 'Taxable Brokerage',
+      ownerPersonId: null,
+      annualReturnPct: 7,
+      balance: 250_000,
+      costBasis: 200_000,
+      annualContribution: 0,
+    },
+  ]
+  plan.incomes = [
+    {
+      type: 'wages',
+      id: exampleEntityId(EXAMPLE_ID, 'wages'),
+      personId: p1,
+      annualGross: 140_000,
+      endAge: 44,
+      realGrowthPct: 4,
+    },
+    {
+      type: 'socialSecurity',
+      id: exampleEntityId(EXAMPLE_ID, 'ss'),
+      personId: p1,
+      piaMonthly: 2_900,
+      earnings: null,
+      claimAge: { years: 67, months: 0 },
+    },
+  ]
+  plan.expenses = {
+    baseAnnual: 50_000,
+    phases: [],
+    oneTimeGoals: [],
+    healthcare: { pre65MonthlyPremiumPerPerson: 600, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 200 },
+  }
+  plan.assumptions = {
+    inflationPct: 2.5,
+    healthcareExtraInflationPct: 2,
+    defaultReturnPct: 6,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 60_000,
+    heirTaxRatePct: 25,
+    safeWithdrawalRatePct: 4,
+  }
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`bridge-early-retirement invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildBrokerageNoHsa.ts

@@ -0,0 +1,109 @@
+/** Brokerage instead of HSA control (A-B pair for HSA depth).
+ * Same person, longevity, expenses, incomes, property sale, traditional IRA (with basis),
+ * but the HSA balance + contributions are instead held in a taxable brokerage account.
+ * Compare to hsa-property-depth to see the tax-free medical withdrawal + reimburse
+ * advantage vs ordinary taxable growth/withdrawals.
+ */
+
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { EXAMPLE_FIXED_YEAR, exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'brokerage-no-hsa'
+
+export function buildBrokerageNoHsa(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const plan = createEmptyPlan({ name: 'Brokerage instead of HSA', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+
+  plan.household = {
+    filingStatus: 'single',
+    hasQualifyingDependent: false,
+    state: 'TX',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: p1, name: 'Harper', dob: '1964-02-28', sex: 'female', retirementAge: 61, longevity: { planningAge: 89, source: 'manual' } },
+    ],
+  }
+
+  // HSA 48k + future contribs moved into taxable brokerage
+  // (48k initial + roughly equivalent ongoing contribution capacity)
+  plan.accounts = [
+    {
+      type: 'taxable',
+      id: exampleEntityId(EXAMPLE_ID, 'brokerage'),
+      name: 'Taxable brokerage (HSA-equivalent money)',
+      ownerPersonId: null,
+      annualReturnPct: null,
+      balance: 48_000,
+      costBasis: 48_000,
+      annualContribution: 4150, // same ongoing "savings" rate as HSA contrib
+      contributionSchedule: [{ annualAmount: 4150, fromAge: 61, toAge: 65, escalationPct: 0 }],
+    },
+    {
+      type: 'traditional',
+      id: exampleEntityId(EXAMPLE_ID, 'tira'),
+      name: 'Traditional IRA (mixed basis)',
+      ownerPersonId: p1,
+      annualReturnPct: null,
+      kind: 'ira',
+      balance: 310_000,
+      nondeductibleBasis: 68000,
+      annualContribution: 0,
+    },
+    {
+      type: 'property',
+      id: exampleEntityId(EXAMPLE_ID, 'home'),
+      name: 'Primary residence',
+      ownerPersonId: null,
+      annualReturnPct: null,
+      value: 385_000,
+      plannedSaleYear: EXAMPLE_FIXED_YEAR + 7,
+      expectedNetProceeds: null,
+      costBasis: 172_000,
+      sellingCostPct: 6,
+      primaryResidence: true,
+      depreciationRecapture: 12000,
+      propertyTaxAnnual: 4800,
+      insuranceAnnual: 2100,
+    },
+    { type: 'cash', id: exampleEntityId(EXAMPLE_ID, 'cash'), name: 'Cash', ownerPersonId: null, annualReturnPct: 1.8, balance: 62_000, annualContribution: 0 },
+  ]
+
+  plan.careEvents = [
+    { id: exampleEntityId(EXAMPLE_ID, 'care'), personId: p1, startAge: 82, durationYears: 2, annualCost: 72000 },
+  ]
+
+  plan.expenses = {
+    baseAnnual: 51_000,
+    phases: [],
+    oneTimeGoals: [],
+    healthcare: { pre65MonthlyPremiumPerPerson: 690, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 165 },
+  }
+
+  plan.incomes = [
+    { type: 'socialSecurity', id: exampleEntityId(EXAMPLE_ID, 'ss'), personId: p1, piaMonthly: 1720, earnings: null, claimAge: { years: 67, months: 0 } },
+  ]
+
+  plan.strategies = {
+    withdrawalOrder: { mode: 'sequential' },
+    rothConversion: { mode: 'fillToTarget', target: 'topOfBracket', targetValue: 24, startYear: EXAMPLE_FIXED_YEAR + 3, endYear: EXAMPLE_FIXED_YEAR + 11 },
+    qcdAnnual: 0,
+  }
+
+  plan.assumptions = {
+    inflationPct: 2.6,
+    healthcareExtraInflationPct: 3.4,
+    defaultReturnPct: 4.9,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 42000,
+    heirTaxRatePct: 22,
+    safeWithdrawalRatePct: 3.6,
+  }
+
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`brokerage-no-hsa invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildCoastFire.ts

@@ -0,0 +1,88 @@
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'coast-fire'
+
+export function buildCoastFire(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const plan = createEmptyPlan({ name: 'Coast FIRE', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+  plan.household = {
+    filingStatus: 'single',
+    hasQualifyingDependent: false,
+    state: 'CO',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: p1, name: 'Morgan', dob: '1996-01-01', sex: 'average', retirementAge: 60, longevity: { planningAge: 90, source: 'manual' } },
+    ],
+  }
+  plan.accounts = [
+    {
+      type: 'traditional',
+      id: exampleEntityId(EXAMPLE_ID, 'ira'),
+      name: 'Traditional IRA',
+      ownerPersonId: p1,
+      annualReturnPct: 7.5,
+      kind: 'ira',
+      balance: 150_000,
+      annualContribution: 0,
+      contributionSchedule: [
+        {
+          annualAmount: 25_000,
+          fromAge: 30,
+          toAge: 40,
+          escalationPct: 0,
+        },
+      ],
+    },
+    {
+      type: 'roth',
+      id: exampleEntityId(EXAMPLE_ID, 'roth-ira'),
+      name: 'Roth IRA',
+      ownerPersonId: p1,
+      annualReturnPct: 7.5,
+      kind: 'ira',
+      balance: 50_000,
+      annualContribution: 0,
+    },
+  ]
+  plan.incomes = [
+    {
+      type: 'wages',
+      id: exampleEntityId(EXAMPLE_ID, 'wages'),
+      personId: p1,
+      annualGross: 90_000,
+      endAge: null,
+      realGrowthPct: 2,
+    },
+    {
+      type: 'socialSecurity',
+      id: exampleEntityId(EXAMPLE_ID, 'ss'),
+      personId: p1,
+      piaMonthly: 2_500,
+      earnings: null,
+      claimAge: { years: 67, months: 0 },
+    },
+  ]
+  plan.expenses = {
+    baseAnnual: 50_000,
+    phases: [],
+    oneTimeGoals: [],
+    healthcare: { pre65MonthlyPremiumPerPerson: 400, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 150 },
+  }
+  plan.assumptions = {
+    inflationPct: 2.5,
+    healthcareExtraInflationPct: 2,
+    defaultReturnPct: 6,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 90_000,
+    heirTaxRatePct: 25,
+    safeWithdrawalRatePct: 4,
+  }
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`coast-fire invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildContext.ts

@@ -0,0 +1,20 @@
+/** Fixed clock and deterministic entity ids so example golden tests stay stable. */
+
+export const EXAMPLE_FIXED_NOW_ISO = '2026-06-29T12:00:00.000Z'
+
+export function exampleFixedNow(): Date {
+  return new Date(EXAMPLE_FIXED_NOW_ISO)
+}
+
+export const EXAMPLE_FIXED_YEAR = 2026
+
+/** Stable ids within an example plan (not the IndexedDB plan id). */
+export function exampleEntityId(exampleId: string, suffix: string): string {
+  return `${exampleId}--${suffix}`
+}
+
+/** Deterministic `newId` for createEmptyPlan — resets on each build() call. */
+export function exampleIdFactory(exampleId: string): () => string {
+  let index = 0
+  return () => exampleEntityId(exampleId, `seq-${index++}`)
+}