@retiregolden/planner-ui 0.1.0

package/src/planner/ssAnalysis.ts

@@ -0,0 +1,325 @@
+/**
+ * Social Security claiming analysis for the planner.
+ *
+ * Two layers, mirroring the V5 plan:
+ *  - whole-plan sweep: for every combination of claim ages, run the full
+ *    deterministic projection and rank by ending after-tax estate (the choice
+ *    interacts with taxes, Roth conversions, IRMAA, ACA, RMDs);
+ *  - benefits-only: mortality-weighted expected present value of the benefits
+ *    alone (socialSecurity/expectedPv), the actuarial lens.
+ *
+ * @see DOCS/features/social-security.md
+ */
+
+import type { IncomeStream, Person, Plan } from '@retiregolden/engine/model/plan'
+import { summarizeProjection, type ProjectionSummary } from '@retiregolden/engine/projection/compare'
+import { simulatePlan } from '@retiregolden/engine/projection/simulate'
+import {
+  createDecisionContext,
+  evaluateCandidate,
+  objectivePolicyForPlan,
+  rankEvaluations,
+  socialSecurityClaimGridGenerator,
+  type ObjectivePolicyId,
+} from '@retiregolden/engine/decisions'
+import {
+  expectedPvCouple,
+  expectedPvSingle,
+  type ClaimantInput,
+} from '../socialSecurity/expectedPv'
+import { spousalBenefitFactor } from '@retiregolden/engine/socialSecurity/claimFactor'
+import { DIVORCED_MIN_MARRIAGE_YEARS } from '@retiregolden/engine/socialSecurity/maritalBenefits'
+import {
+  computePiaFromEarnings,
+  isPiaFromEarningsError,
+  piaInputFromEarnings,
+  resolveEarningsProjection,
+  type PiaFromEarningsResult,
+} from '@retiregolden/engine/socialSecurity/piaFromEarnings'
+import { currentStartYear, taxCalculatorFor } from './useProjection'
+
+type SsStream = Extract<IncomeStream, { type: 'socialSecurity' }>
+
+export const CLAIM_AGES = [62, 63, 64, 65, 66, 67, 68, 69, 70] as const
+
+export function dobParts(person: Person): { y: number; m: number; d: number } {
+  return { y: Number(person.dob.slice(0, 4)), m: Number(person.dob.slice(5, 7)), d: Number(person.dob.slice(8, 10)) }
+}
+
+/**
+ * Claim ages worth considering for a person: 62–70, but never earlier than the
+ * age they have already reached (you can't claim in the past). Someone already
+ * past 70 is left with 70.
+ */
+export function candidateClaimAges(person: Person, startYear: number): number[] {
+  const currentAge = startYear - dobParts(person).y
+  const ages = CLAIM_AGES.filter((a) => a >= currentAge)
+  return ages.length > 0 ? ages : [70]
+}
+
+export function ssStreamFor(plan: Plan, personId: string): SsStream | undefined {
+  return plan.incomes.find((s): s is SsStream => s.type === 'socialSecurity' && s.personId === personId)
+}
+
+export interface ResolvedPia {
+  /** Monthly PIA at FRA in today's dollars, or null if it can't be resolved. */
+  piaMonthly: number | null
+  warning: string | null
+  /** Full earnings-mode computation detail (indexed years, projection, AIME), when derived from earnings. */
+  detail: PiaFromEarningsResult | null
+}
+
+/** Resolve a stream's PIA the same way the engine does: entered, or derived from earnings. */
+export function resolvePia(person: Person, stream: SsStream): ResolvedPia {
+  if (stream.piaMonthly !== null) return { piaMonthly: stream.piaMonthly, warning: null, detail: null }
+  if (!stream.earnings || stream.earnings.length === 0) {
+    return { piaMonthly: null, warning: 'No PIA entered and no earnings history.', detail: null }
+  }
+  const { y, m, d } = dobParts(person)
+  const projection = resolveEarningsProjection(stream.earningsProjection, person.retirementAge)
+  const result = computePiaFromEarnings(piaInputFromEarnings(y, m, d, stream.earnings, projection))
+  if (isPiaFromEarningsError(result)) {
+    return { piaMonthly: null, warning: `Earnings history could not be used (${result.code}).`, detail: null }
+  }
+  return {
+    piaMonthly: result.piaMonthly,
+    warning: result.usesStandInForFutureTables ? 'PIA uses stand-in SSA tables for years beyond published data.' : null,
+    detail: result,
+  }
+}
+
+/** People who have a Social Security stream with a resolvable benefit. */
+export function claimingPeople(plan: Plan): { person: Person; stream: SsStream; pia: number }[] {
+  const out: { person: Person; stream: SsStream; pia: number }[] = []
+  for (const person of plan.household.people) {
+    const stream = ssStreamFor(plan, person.id)
+    if (!stream) continue
+    const { piaMonthly } = resolvePia(person, stream)
+    if (piaMonthly !== null && piaMonthly > 0) out.push({ person, stream, pia: piaMonthly })
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// Whole-plan sweep
+// ---------------------------------------------------------------------------
+
+export interface SweepRow {
+  /** Claim age (years) per claiming person, keyed by personId. */
+  claimByPersonId: Record<string, number>
+  summary: ProjectionSummary
+  /** Objective-policy metric delta versus the current plan; higher is better. */
+  primaryValue: number
+  eligible: boolean
+  lossReason: string | null
+}
+
+export interface SweepResult {
+  /** personId order the grid axes follow (1 entry = single, 2 = couple). */
+  personIds: string[]
+  objectivePolicyId: ObjectivePolicyId
+  primaryMetricLabel: string
+  rows: SweepRow[]
+  /** Rows sorted by the selected objective policy, descending. */
+  ranked: SweepRow[]
+}
+
+export function planWithClaimAges(plan: Plan, claimByPersonId: Record<string, number>): Plan {
+  const next = structuredClone(plan)
+  for (const stream of next.incomes) {
+    if (stream.type === 'socialSecurity' && claimByPersonId[stream.personId] !== undefined) {
+      stream.claimAge = { years: claimByPersonId[stream.personId]!, months: 0 }
+    }
+  }
+  return next
+}
+
+/**
+ * Run the full projection for every claim-age combination (62–70 per claiming
+ * person) and rank by ending after-tax estate. 9 runs single, 81 couple —
+ * each ~a few ms, so this stays well under a frame budget on the main thread.
+ */
+export function sweepClaimingStrategies(
+  plan: Plan,
+  startYear = currentStartYear(),
+  objectivePolicyId: ObjectivePolicyId = 'max-after-tax-estate',
+): SweepResult {
+  const people = claimingPeople(plan)
+  const personIds = people.map((p) => p.person.id)
+  const taxCalculator = taxCalculatorFor(plan)
+  if (personIds.length === 0) {
+    const policy = objectivePolicyForPlan(objectivePolicyId, plan)
+    return { personIds, objectivePolicyId, primaryMetricLabel: policy.primaryMetricLabel, rows: [], ranked: [] }
+  }
+
+  const ctx = createDecisionContext(plan, { startYear, taxCalculator })
+  const policy = objectivePolicyForPlan(objectivePolicyId, plan)
+  const candidates = socialSecurityClaimGridGenerator.generate(ctx)
+  const evaluations = candidates.map((candidate) => evaluateCandidate(ctx, candidate))
+  const { ranked: rankedDecisions } = rankEvaluations(evaluations, ctx, policy, 0)
+
+  const rowByCandidateId = new Map<string, SweepRow>()
+  for (const row of rankedDecisions) {
+    const claimByPersonId = row.evaluation.candidate.metadata?.['claimByPersonId']
+    if (!claimByPersonId || typeof claimByPersonId !== 'object') continue
+    const claim = claimByPersonId as Record<string, number>
+    if (!personIds.every((id) => typeof claim[id] === 'number')) continue
+    rowByCandidateId.set(row.evaluation.candidate.id, {
+      claimByPersonId: Object.fromEntries(personIds.map((id) => [id, claim[id]!])),
+      summary: row.evaluation.candidateSummary,
+      primaryValue: row.primaryValue,
+      eligible: row.eligible,
+      lossReason: row.lossReason,
+    })
+  }
+
+  const rows = candidates
+    .map((candidate) => rowByCandidateId.get(candidate.id))
+    .filter((row): row is SweepRow => row !== undefined)
+  const ranked = rankedDecisions
+    .map((row) => rowByCandidateId.get(row.evaluation.candidate.id))
+    .filter((row): row is SweepRow => row !== undefined)
+  return { personIds, objectivePolicyId, primaryMetricLabel: policy.primaryMetricLabel, rows, ranked }
+}
+
+// ---------------------------------------------------------------------------
+// Monthly refinement around the best whole-year strategy
+// ---------------------------------------------------------------------------
+
+export interface MonthlyClaim {
+  years: number
+  months: number
+}
+
+export interface MonthlyRefinement {
+  claimByPersonId: Record<string, MonthlyClaim>
+  summary: ProjectionSummary
+}
+
+export function planWithClaimAgesMonthly(plan: Plan, claimByPersonId: Record<string, MonthlyClaim>): Plan {
+  const next = structuredClone(plan)
+  for (const stream of next.incomes) {
+    if (stream.type === 'socialSecurity' && claimByPersonId[stream.personId] !== undefined) {
+      stream.claimAge = { ...claimByPersonId[stream.personId]! }
+    }
+  }
+  return next
+}
+
+/**
+ * Second-pass monthly refinement: starting from the best whole-year strategy,
+ * sweep each claiming person's claim age to the month within ±1 year (clamped to
+ * 62y0m–70y0m and the current age) by coordinate ascent, keeping the best
+ * after-tax estate. ~25 runs per person, so it stays on the main thread.
+ */
+export function refineClaimingMonthly(
+  plan: Plan,
+  baseClaimYears: Record<string, number>,
+  startYear = currentStartYear(),
+): MonthlyRefinement {
+  const people = claimingPeople(plan)
+  const taxCalculator = taxCalculatorFor(plan)
+  const evaluate = (claim: Record<string, MonthlyClaim>): ProjectionSummary => {
+    const candidate = planWithClaimAgesMonthly(plan, claim)
+    return summarizeProjection(candidate, simulatePlan(candidate, { startYear, taxCalculator }))
+  }
+
+  let best: Record<string, MonthlyClaim> = {}
+  for (const id of Object.keys(baseClaimYears)) best[id] = { years: baseClaimYears[id]!, months: 0 }
+  let bestSummary = evaluate(best)
+
+  for (const { person } of people) {
+    const baseYear = best[person.id]!.years
+    const currentAge = startYear - dobParts(person).y
+    let localBest = best[person.id]!
+    for (let yy = baseYear - 1; yy <= baseYear + 1; yy++) {
+      if (yy < 62 || yy > 70 || yy < currentAge) continue
+      const maxMonth = yy === 70 ? 0 : 11 // engine caps claim at 70y0m
+      for (let mm = 0; mm <= maxMonth; mm++) {
+        const summary = evaluate({ ...best, [person.id]: { years: yy, months: mm } })
+        if (summary.endingAfterTaxEstate > bestSummary.endingAfterTaxEstate) {
+          bestSummary = summary
+          localBest = { years: yy, months: mm }
+        }
+      }
+    }
+    best = { ...best, [person.id]: localBest }
+  }
+  return { claimByPersonId: best, summary: bestSummary }
+}
+
+// ---------------------------------------------------------------------------
+// Benefits-only (actuarial) ranking
+// ---------------------------------------------------------------------------
+
+export interface BenefitsPvRow {
+  claimByPersonId: Record<string, number>
+  expectedPv: number
+}
+
+function claimantInput(person: Person, pia: number, claimYears: number, startYear: number): ClaimantInput {
+  const { y, m, d } = dobParts(person)
+  return {
+    currentAge: Math.max(0, startYear - y),
+    dob: { year: y, month: m, day: d },
+    sex: person.sex,
+    piaMonthly: pia,
+    claimAge: { years: claimYears, months: 0 },
+  }
+}
+
+/**
+ * Best divorced-spousal monthly benefit (0.5 × ex PIA, reduced for the claim age)
+ * across eligible ex-spouses, for a currently-unmarried claimant. The actuarial
+ * view assumes the ex is eligible; survivor benefits are handled separately by
+ * the survivor-switching analysis.
+ */
+function divorcedSpousalFloorMonthly(person: Person, stream: SsStream, claimYears: number, householdSingle: boolean): number {
+  if (!householdSingle) return 0
+  const { y, m, d } = dobParts(person)
+  let best = 0
+  for (const r of stream.formerSpouses ?? []) {
+    if (r.relationship !== 'divorced' || r.marriageYears < DIVORCED_MIN_MARRIAGE_YEARS) continue
+    best = Math.max(best, 0.5 * r.piaMonthly * spousalBenefitFactor(y, m, d, { years: claimYears, months: 0 }))
+  }
+  return best
+}
+
+/**
+ * Mortality-weighted expected PV of benefits for every claim-age combination,
+ * ranked descending. Ignores the portfolio and taxes — the pure insurance view.
+ */
+export function benefitsOnlyRanking(plan: Plan, discountRate: number, startYear = currentStartYear()): {
+  personIds: string[]
+  rows: BenefitsPvRow[]
+  ranked: BenefitsPvRow[]
+} {
+  const people = claimingPeople(plan)
+  const personIds = people.map((p) => p.person.id)
+  const householdSingle = plan.household.people.length === 1
+  const rows: BenefitsPvRow[] = []
+
+  if (people.length === 1) {
+    const { person, pia, stream } = people[0]!
+    for (const age of candidateClaimAges(person, startYear)) {
+      const benefitFloorMonthly = divorcedSpousalFloorMonthly(person, stream, age, householdSingle)
+      const pv = expectedPvSingle({ ...claimantInput(person, pia, age, startYear), benefitFloorMonthly }, { discountRate })
+      rows.push({ claimByPersonId: { [person.id]: age }, expectedPv: pv })
+    }
+  } else if (people.length === 2) {
+    const [a, b] = people
+    for (const ageA of candidateClaimAges(a!.person, startYear)) {
+      for (const ageB of candidateClaimAges(b!.person, startYear)) {
+        const pv = expectedPvCouple(
+          claimantInput(a!.person, a!.pia, ageA, startYear),
+          claimantInput(b!.person, b!.pia, ageB, startYear),
+          { discountRate },
+        )
+        rows.push({ claimByPersonId: { [a!.person.id]: ageA, [b!.person.id]: ageB }, expectedPv: pv })
+      }
+    }
+  }
+
+  const ranked = [...rows].sort((x, y) => y.expectedPv - x.expectedPv)
+  return { personIds, rows, ranked }
+}

package/src/planner/successBand.ts

@@ -0,0 +1,20 @@
+/**
+ * Display-only tone banding for the Monte Carlo success rate (UI/UX round 2,
+ * Step 3). Red is reserved for genuinely failing plans so a high-60s/70s plan no
+ * longer reads as failure; the number and every computed metric are untouched.
+ * Bands agree with the "Understanding Monte Carlo success rate" Learning Center
+ * article.
+ */
+export function successBand(rate: number): { color: string; severity: string; verdict: string } {
+  const pct = rate * 100
+  if (pct >= 90) return { color: 'var(--good)', severity: 'on track', verdict: 'On track in nearly all markets.' }
+  if (pct >= 75)
+    return {
+      color: 'var(--good)',
+      severity: 'on track in most markets',
+      verdict: 'On track in most markets — some sequence risk remains.',
+    }
+  if (pct >= 60)
+    return { color: 'var(--warn)', severity: 'needs attention', verdict: 'Workable, but sequence risk is real here.' }
+  return { color: 'var(--bad)', severity: 'at risk', verdict: 'This plan depletes in many markets.' }
+}

package/src/planner/survivorAnalysis.ts

@@ -0,0 +1,277 @@
+/**
+ * Survivor-transition analysis for two-adult plans (survivor-widowhood-and-
+ * irmaa-relief, step 2).
+ *
+ * For each death-timing scenario (either spouse first, at a bounded set of
+ * ages), run the SAME deterministic ledger the Results page uses with a
+ * `deathAgeByPersonId` override and read the transition facts straight off the
+ * projection years: the filing-status timeline, the tax/MAGI shift around the
+ * death, the survivor's Social Security outcome, survivor spending coverage,
+ * the IRMAA difference with and without SSA-44 relief, and the pre-death
+ * Roth-conversion lever priced as an ordinary scenario patch. Nothing here is
+ * a separate model — every number must agree exactly with running the
+ * equivalent scenario by hand (guarded by tests).
+ */
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+import { applyScenarioPatch } from '@retiregolden/engine/scenarios/scenarios'
+import { summarizeProjection } from '@retiregolden/engine/projection/compare'
+import { simulatePlan } from '@retiregolden/engine/projection/simulate'
+import type { ProjectedFilingStatus, ProjectionResult, TaxCalculator } from '@retiregolden/engine/projection/types'
+
+export const SURVIVOR_DEATH_AGES = [70, 75, 80, 85, 90] as const
+
+export interface SurvivorAnalysisOptions {
+  startYear: number
+  taxCalculator: TaxCalculator
+  /** Death-age grid per first-to-die person; defaults to {@link SURVIVOR_DEATH_AGES}, clamped to plausible ages. */
+  deathAges?: number[]
+}
+
+/** One contiguous run of a filing status in the projection. */
+export interface FilingSegment {
+  fromYear: number
+  toYear: number
+  status: ProjectedFilingStatus
+}
+
+export interface SurvivorYearFacts {
+  year: number
+  magi: number
+  tax: number
+  filingStatus: ProjectedFilingStatus
+}
+
+export interface SurvivorIrmaaYear {
+  year: number
+  /** IRMAA tier / annual Medicare premiums under the plain two-year lookback. */
+  tierWithoutSsa44: number
+  premiumsWithoutSsa44: number
+  /** … and with SSA-44 survivor-year redetermination modeled. */
+  tierWithSsa44: number
+  premiumsWithSsa44: number
+}
+
+export interface SurvivorScenarioRow {
+  /** The first-to-die person this row models. */
+  deceasedPersonId: string
+  deathAge: number
+  deathYear: number
+  /** Compressed filing-status timeline of the whole projection. */
+  filingTimeline: FilingSegment[]
+  /** The last joint-filing year (the death year) vs the first survivor-filed year. */
+  lastJointYear: SurvivorYearFacts
+  firstSurvivorYear: SurvivorYearFacts
+  /** Household Social Security in the death year vs the first survivor year (nominal). */
+  ssBeforeDeath: number
+  ssAfterDeath: number
+  /** SSA-44 window years (death year + 1, + 2), premiums from two otherwise-identical runs. */
+  irmaaYears: SurvivorIrmaaYear[]
+  /** Total nominal Medicare premium saved by SSA-44 across all survivor years. */
+  ssa44PremiumSavings: number
+  /** Survivor years (after the death year) with any required-spending shortfall. */
+  survivorShortfallYears: number
+  /** Lowest end-of-year investable balance across survivor years (nominal). */
+  minSurvivorInvestable: number
+  /** Ending after-tax estate / lifetime tax for this death timing, at the plan's own settings (nominal). */
+  baseEndingAfterTaxEstate: number
+  baseLifetimeTax: number
+  /**
+   * The pre-death conversion lever: the same death timing with conversions
+   * filling the 12% bracket through the last joint year (the widows-penalty
+   * detector's preview patch), priced on the same ledger. Null when the patch
+   * fails validation (never expected).
+   */
+  conversionLever: {
+    endingAfterTaxEstate: number
+    lifetimeTax: number
+    estateDelta: number
+    lifetimeTaxDelta: number
+  } | null
+}
+
+export interface SurvivorAnalysis {
+  /** False for plans that are not a two-adult married-filing-jointly household. */
+  eligible: boolean
+  /** Whether the plan itself already models SSA-44 survivor relief. */
+  planUsesSsa44: boolean
+  rows: SurvivorScenarioRow[]
+  /** Death timings whose ledger runs threw and were skipped (0 = clean sweep). */
+  failedTimings: number
+  /** Set by the page when the whole sweep threw — render an error state, not tables. */
+  error?: boolean
+}
+
+function dobYearOf(plan: Plan, personId: string): number {
+  const p = plan.household.people.find((x) => x.id === personId)!
+  return Number(p.dob.slice(0, 4))
+}
+
+/** The plan with SSA-44 survivor relief forced on/off (other settings untouched). */
+function withSurvivorSsa44(plan: Plan, on: boolean): Plan {
+  return {
+    ...plan,
+    expenses: {
+      ...plan.expenses,
+      healthcare: {
+        ...plan.expenses.healthcare,
+        ssa44: { survivorYears: on, retirementYears: plan.expenses.healthcare.ssa44?.retirementYears ?? false },
+      },
+    },
+  }
+}
+
+function filingTimeline(result: ProjectionResult): FilingSegment[] {
+  const segments: FilingSegment[] = []
+  for (const y of result.years) {
+    const last = segments[segments.length - 1]
+    if (last && last.status === y.filingStatus) last.toYear = y.year
+    else segments.push({ fromYear: y.year, toYear: y.year, status: y.filingStatus })
+  }
+  return segments
+}
+
+/** The widows-penalty detector's conversion-acceleration patch for a given last joint year. */
+export function conversionLeverPatch(startYear: number, lastJointYear: number): Record<string, unknown> {
+  return {
+    strategies: {
+      rothConversion: {
+        mode: 'fillToTarget',
+        target: 'topOfBracket',
+        targetValue: 12,
+        startYear,
+        endYear: lastJointYear,
+      },
+    },
+  }
+}
+
+/**
+ * Death ages worth sweeping for a person: the default grid clamped to
+ * [current age, planning age), so every row is a genuine "dies earlier than
+ * planned" scenario. The current attained age is included — dying at the end
+ * of this year is a valid earlier-than-planned timing (`lastAliveYear =
+ * dobYear + deathAge ≥ startYear`). Empty when no grid age fits.
+ */
+export function candidateDeathAges(plan: Plan, personId: string, startYear: number, grid: number[]): number[] {
+  const person = plan.household.people.find((p) => p.id === personId)!
+  const currentAge = startYear - dobYearOf(plan, personId)
+  return grid.filter((a) => a >= currentAge && a < person.longevity.planningAge)
+}
+
+/**
+ * One death timing = three full ledger runs: the SSA-44 off/on pair (whichever
+ * matches the plan's own setting doubles as the base run — the field is
+ * engine-identical to absent when off, and summarize ignores it) plus the
+ * conversion-lever run. Returns null when the timing yields no survivor phase.
+ */
+function buildTimingRow(
+  plan: Plan,
+  opts: SurvivorAnalysisOptions,
+  personId: string,
+  deathAge: number,
+  planUsesSsa44: boolean,
+): SurvivorScenarioRow | null {
+  const deathYear = dobYearOf(plan, personId) + deathAge
+  const simOpts = { startYear: opts.startYear, taxCalculator: opts.taxCalculator, deathAgeByPersonId: { [personId]: deathAge } }
+
+  const without = simulatePlan(withSurvivorSsa44(plan, false), simOpts)
+  const withRelief = simulatePlan(withSurvivorSsa44(plan, true), simOpts)
+  const base = planUsesSsa44 ? withRelief : without
+  const baseSummary = summarizeProjection(plan, base)
+
+  const lastJoint = base.years.find((y) => y.year === deathYear)
+  const firstSurvivor = base.years.find((y) => y.year === deathYear + 1)
+  if (!lastJoint || !firstSurvivor) return null
+
+  const irmaaYears: SurvivorIrmaaYear[] = [deathYear + 1, deathYear + 2]
+    .map((year) => {
+      const off = without.years.find((y) => y.year === year)
+      const on = withRelief.years.find((y) => y.year === year)
+      if (!off || !on) return null
+      return {
+        year,
+        tierWithoutSsa44: off.irmaaTier,
+        premiumsWithoutSsa44: off.medicarePremiums,
+        tierWithSsa44: on.irmaaTier,
+        premiumsWithSsa44: on.medicarePremiums,
+      }
+    })
+    .filter((x): x is SurvivorIrmaaYear => x !== null)
+  let ssa44PremiumSavings = 0
+  for (const y of without.years) {
+    const on = withRelief.years.find((x) => x.year === y.year)
+    if (on) ssa44PremiumSavings += y.medicarePremiums - on.medicarePremiums
+  }
+
+  const survivorYears = base.years.filter((y) => y.year > deathYear && y.people.some((p) => p.alive))
+  const survivorShortfallYears = survivorYears.filter((y) => y.requiredShortfall > 0.005).length
+  const minSurvivorInvestable = survivorYears.length > 0 ? Math.min(...survivorYears.map((y) => y.investableTotal)) : 0
+
+  // The conversion lever, priced as an ordinary scenario patch on the same
+  // death timing (agrees exactly with adding the scenario by hand).
+  let conversionLever: SurvivorScenarioRow['conversionLever'] = null
+  const patched = applyScenarioPatch(plan, conversionLeverPatch(opts.startYear, deathYear))
+  if (patched.ok) {
+    const leverSummary = summarizeProjection(patched.plan, simulatePlan(patched.plan, simOpts))
+    conversionLever = {
+      endingAfterTaxEstate: leverSummary.endingAfterTaxEstate,
+      lifetimeTax: leverSummary.lifetimeTaxesAndPenalties,
+      estateDelta: leverSummary.endingAfterTaxEstate - baseSummary.endingAfterTaxEstate,
+      lifetimeTaxDelta: leverSummary.lifetimeTaxesAndPenalties - baseSummary.lifetimeTaxesAndPenalties,
+    }
+  }
+
+  return {
+    deceasedPersonId: personId,
+    deathAge,
+    deathYear,
+    filingTimeline: filingTimeline(base),
+    lastJointYear: { year: lastJoint.year, magi: lastJoint.magi, tax: lastJoint.tax, filingStatus: lastJoint.filingStatus },
+    firstSurvivorYear: {
+      year: firstSurvivor.year,
+      magi: firstSurvivor.magi,
+      tax: firstSurvivor.tax,
+      filingStatus: firstSurvivor.filingStatus,
+    },
+    ssBeforeDeath: lastJoint.incomes.socialSecurity,
+    ssAfterDeath: firstSurvivor.incomes.socialSecurity,
+    irmaaYears,
+    ssa44PremiumSavings,
+    survivorShortfallYears,
+    minSurvivorInvestable,
+    baseEndingAfterTaxEstate: baseSummary.endingAfterTaxEstate,
+    baseLifetimeTax: baseSummary.lifetimeTaxesAndPenalties,
+    conversionLever,
+  }
+}
+
+export function buildSurvivorAnalysis(plan: Plan, opts: SurvivorAnalysisOptions): SurvivorAnalysis {
+  const eligible = plan.household.filingStatus === 'marriedFilingJointly' && plan.household.people.length === 2
+  const planUsesSsa44 = plan.expenses.healthcare.ssa44?.survivorYears === true
+  if (!eligible) return { eligible, planUsesSsa44, rows: [], failedTimings: 0 }
+
+  const grid = opts.deathAges ?? [...SURVIVOR_DEATH_AGES]
+  const rows: SurvivorScenarioRow[] = []
+  let failedTimings = 0
+
+  for (const person of plan.household.people) {
+    const survivor = plan.household.people.find((p) => p.id !== person.id)!
+    const survivorLastYear = dobYearOf(plan, survivor.id) + survivor.longevity.planningAge
+    for (const deathAge of candidateDeathAges(plan, person.id, opts.startYear, grid)) {
+      const deathYear = dobYearOf(plan, person.id) + deathAge
+      // Only genuine first deaths: the survivor must outlive this timing.
+      if (deathYear >= survivorLastYear) continue
+      // A throwing timing is skipped (and counted) rather than sinking the
+      // whole sweep — the page reports partial results honestly.
+      try {
+        const row = buildTimingRow(plan, opts, person.id, deathAge, planUsesSsa44)
+        if (row) rows.push(row)
+      } catch {
+        failedTimings += 1
+      }
+    }
+  }
+
+  return { eligible, planUsesSsa44, rows, failedTimings }
+}

package/src/planner/usStates.ts

@@ -0,0 +1,19 @@
+export const US_STATES: ReadonlyArray<{ value: string; label: string }> = [
+  { value: 'AL', label: 'Alabama' }, { value: 'AK', label: 'Alaska' }, { value: 'AZ', label: 'Arizona' },
+  { value: 'AR', label: 'Arkansas' }, { value: 'CA', label: 'California' }, { value: 'CO', label: 'Colorado' },
+  { value: 'CT', label: 'Connecticut' }, { value: 'DE', label: 'Delaware' }, { value: 'DC', label: 'District of Columbia' },
+  { value: 'FL', label: 'Florida' }, { value: 'GA', label: 'Georgia' }, { value: 'HI', label: 'Hawaii' },
+  { value: 'ID', label: 'Idaho' }, { value: 'IL', label: 'Illinois' }, { value: 'IN', label: 'Indiana' },
+  { value: 'IA', label: 'Iowa' }, { value: 'KS', label: 'Kansas' }, { value: 'KY', label: 'Kentucky' },
+  { value: 'LA', label: 'Louisiana' }, { value: 'ME', label: 'Maine' }, { value: 'MD', label: 'Maryland' },
+  { value: 'MA', label: 'Massachusetts' }, { value: 'MI', label: 'Michigan' }, { value: 'MN', label: 'Minnesota' },
+  { value: 'MS', label: 'Mississippi' }, { value: 'MO', label: 'Missouri' }, { value: 'MT', label: 'Montana' },
+  { value: 'NE', label: 'Nebraska' }, { value: 'NV', label: 'Nevada' }, { value: 'NH', label: 'New Hampshire' },
+  { value: 'NJ', label: 'New Jersey' }, { value: 'NM', label: 'New Mexico' }, { value: 'NY', label: 'New York' },
+  { value: 'NC', label: 'North Carolina' }, { value: 'ND', label: 'North Dakota' }, { value: 'OH', label: 'Ohio' },
+  { value: 'OK', label: 'Oklahoma' }, { value: 'OR', label: 'Oregon' }, { value: 'PA', label: 'Pennsylvania' },
+  { value: 'RI', label: 'Rhode Island' }, { value: 'SC', label: 'South Carolina' }, { value: 'SD', label: 'South Dakota' },
+  { value: 'TN', label: 'Tennessee' }, { value: 'TX', label: 'Texas' }, { value: 'UT', label: 'Utah' },
+  { value: 'VT', label: 'Vermont' }, { value: 'VA', label: 'Virginia' }, { value: 'WA', label: 'Washington' },
+  { value: 'WV', label: 'West Virginia' }, { value: 'WI', label: 'Wisconsin' }, { value: 'WY', label: 'Wyoming' },
+]