@retiregolden/planner-ui 0.1.0

package/src/socialSecurity/breakEven.ts

@@ -0,0 +1,107 @@
+/**
+ * Social Security break-even education (V7 phase 2). Pure cumulative-benefit math
+ * for a single person's own retirement benefit across a few claim ages, with COLA
+ * and an optional investment-growth assumption. This is the simple pedagogical
+ * lens; the whole-plan claiming sweep (ssAnalysis) is the more complete answer.
+ *
+ * Models one person's benefit only — spousal/survivor interactions are out of
+ * scope here (the sweep handles those). COLA accrues from age 62 for every claim
+ * age (SSA applies COLAs from 62 even before you claim). With a growth rate, each
+ * year's benefit compounds to the comparison age, so a higher return lets the
+ * early claimant's head start hold longer and pushes break-even later.
+ *
+ * @see DOCS/features/social-security.md §3.2
+ */
+
+import { claimFactor } from '@retiregolden/engine/socialSecurity/claimFactor'
+
+export interface BreakEvenInput {
+  dob: { year: number; month: number; day: number }
+  /** Monthly PIA at full retirement age, today's dollars. */
+  piaMonthly: number
+  /** Whole-year claim ages to compare (e.g. [62, fra, 70]). */
+  claimAges: number[]
+  /** Annual cost-of-living adjustment, percent. */
+  colaPct: number
+  /** Annual investment return on benefits received, percent. 0 = straight cumulative. */
+  growthPct: number
+  /** Highest age to chart (e.g. planning age). */
+  throughAge: number
+}
+
+export interface BreakEvenPoint {
+  age: number
+  /** Cumulative value at this age, keyed by claim age. */
+  cumulative: Record<number, number>
+}
+
+export interface BreakEvenCrossing {
+  early: number
+  late: number
+  /** Age (to 0.1yr) the later claim's cumulative overtakes the earlier; null if not within throughAge. */
+  age: number | null
+}
+
+export interface BreakEvenResult {
+  series: BreakEvenPoint[]
+  crossings: BreakEvenCrossing[]
+  /** Benefit as a fraction of PIA, by claim age. */
+  factors: Record<number, number>
+}
+
+const FIRST_AGE = 62
+
+export function computeBreakEven(input: BreakEvenInput): BreakEvenResult {
+  const { dob, piaMonthly, claimAges, colaPct, growthPct, throughAge } = input
+  const cola = colaPct / 100
+  const g = growthPct / 100
+
+  const factors: Record<number, number> = {}
+  for (const a of claimAges) {
+    factors[a] = claimFactor(dob.year, dob.month, dob.day, { years: a, months: 0 })
+  }
+
+  /** Annual benefit received at `age` for a person who claimed at `a` (0 before claim). */
+  const annualBenefit = (a: number, age: number): number =>
+    age < a ? 0 : piaMonthly * factors[a]! * 12 * Math.pow(1 + cola, age - FIRST_AGE)
+
+  const series: BreakEvenPoint[] = []
+  const balance: Record<number, number> = {}
+  for (const a of claimAges) balance[a] = 0
+
+  for (let age = FIRST_AGE; age <= throughAge; age++) {
+    const cumulative: Record<number, number> = {}
+    for (const a of claimAges) {
+      balance[a] = balance[a]! * (1 + g) + annualBenefit(a, age)
+      cumulative[a] = Math.round(balance[a]!)
+    }
+    series.push({ age, cumulative })
+  }
+
+  const sorted = [...claimAges].sort((x, y) => x - y)
+  const crossings: BreakEvenCrossing[] = []
+  for (let i = 0; i < sorted.length; i++) {
+    for (let j = i + 1; j < sorted.length; j++) {
+      const early = sorted[i]!
+      const late = sorted[j]!
+      let crossAge: number | null = null
+      let prevDiff: number | null = null
+      for (const pt of series) {
+        // Before the earlier claim begins, both are $0 — nothing to compare yet.
+        if (pt.cumulative[early]! <= 0) continue
+        const diff = pt.cumulative[late]! - pt.cumulative[early]!
+        if (diff >= 0) {
+          crossAge =
+            prevDiff !== null && prevDiff < 0
+              ? pt.age - 1 + -prevDiff / (diff - prevDiff)
+              : pt.age
+          break
+        }
+        prevDiff = diff
+      }
+      crossings.push({ early, late, age: crossAge === null ? null : Math.round(crossAge * 10) / 10 })
+    }
+  }
+
+  return { series, crossings, factors }
+}

package/src/socialSecurity/expectedPv.ts

@@ -0,0 +1,164 @@
+/**
+ * Mortality-weighted expected present value of a Social Security claiming
+ * strategy — the "benefits only" actuarial view: weight each future year's
+ * benefit by the probability of being
+ * alive to receive it, and discount at a real rate (benefits are CPI-indexed,
+ * so working in today's dollars with a real rate makes COLA and inflation
+ * cancel).
+ *
+ * Survival curve: the repo's SSA period table stores remaining-life-expectancy
+ * e(x), not death probabilities, so we recover one-year survival from the
+ * standard identity p(x) = l(x+1)/l(x) = (e(x) − 0.5) / (e(x+1) + 0.5)
+ * (half-year-of-life convention). This avoids transcribing a second large
+ * q(x) table and matches the SSA e(x) data already used by the longevity
+ * model. An optional multiplier scales e(x) to reflect a person's longevity
+ * questionnaire result (approximate).
+ *
+ * Simplifications: annual (not monthly) cashflows; claim months ignored
+ * (whole-year claim ages, matching the analysis grid); couples assume
+ * independent lifetimes; spousal top-up and survivor step-up mirror the
+ * projection engine. See DOCS/features/social-security.md.
+ */
+
+import { FEMALE, MALE } from '@retiregolden/engine/longevity/ssaPeriod2022'
+import type { Sex } from '@retiregolden/engine/longevity/types'
+import { claimFactor, spousalBenefitFactor, type ClaimAge } from '@retiregolden/engine/socialSecurity/claimFactor'
+
+function table(sex: Sex): readonly number[] {
+  return sex === 'male' ? MALE : sex === 'female' ? FEMALE : MALE // 'average' handled in remainingYears
+}
+
+/** Remaining life expectancy e(x) at integer age, optionally scaled by a longevity multiplier. */
+function remainingYears(age: number, sex: Sex, multiplier: number): number {
+  const i = Math.max(0, Math.min(Math.round(age), MALE.length - 1))
+  const raw = sex === 'average' ? (MALE[i]! + FEMALE[i]!) / 2 : table(sex)[i]!
+  return raw * multiplier
+}
+
+/** One-year survival probability p(age) = P(alive at age+1 | alive at age). */
+function oneYearSurvival(age: number, sex: Sex, multiplier: number): number {
+  const ex = remainingYears(age, sex, multiplier)
+  const exNext = remainingYears(age + 1, sex, multiplier)
+  const p = (ex - 0.5) / (exNext + 0.5)
+  return Math.max(0, Math.min(1, p))
+}
+
+export interface SurvivalCurve {
+  /** P(alive at integer `toAge` | alive at integer `fromAge`). 1 when toAge ≤ fromAge. */
+  survival(fromAge: number, toAge: number): number
+}
+
+export function survivalCurve(sex: Sex, longevityMultiplier = 1): SurvivalCurve {
+  const m = longevityMultiplier > 0 ? longevityMultiplier : 1
+  // Precompute cumulative survival from age 0 so survival(a,b) = S(b)/S(a).
+  const cum: number[] = [1]
+  for (let age = 0; age < MALE.length; age++) {
+    cum.push(cum[age]! * oneYearSurvival(age, sex, m))
+  }
+  return {
+    survival(fromAge: number, toAge: number): number {
+      if (toAge <= fromAge) return 1
+      const a = Math.max(0, Math.min(Math.round(fromAge), cum.length - 1))
+      const b = Math.max(0, Math.min(Math.round(toAge), cum.length - 1))
+      if (cum[a]! <= 0) return 0
+      return cum[b]! / cum[a]!
+    },
+  }
+}
+
+export interface ClaimantInput {
+  /** Whole age today (the present value's t=0 reference). */
+  currentAge: number
+  dob: { year: number; month: number; day: number }
+  sex: Sex
+  piaMonthly: number
+  claimAge: ClaimAge
+  /** Scales SSA remaining-years (e.g. from the longevity questionnaire); default 1. */
+  longevityMultiplier?: number
+  /**
+   * Optional monthly benefit floor the claimant receives instead of their own
+   * once claimed, if larger — e.g. a divorced-spousal benefit on an ex's record.
+   * Already reduced for the claim age by the caller.
+   */
+  benefitFloorMonthly?: number
+}
+
+export interface ExpectedPvOptions {
+  /** Real annual discount rate, e.g. 0.02 for ~2% (≈ long TIPS yield). */
+  discountRate: number
+  /** Highest age to sum benefits through; defaults to the table's top. */
+  maxAge?: number
+}
+
+/** Annual benefit (today's dollars) once claimed, ignoring claim months. */
+function annualBenefit(c: ClaimantInput): number {
+  const factor = claimFactor(c.dob.year, c.dob.month, c.dob.day, { years: c.claimAge.years, months: 0 })
+  const own = c.piaMonthly * factor
+  return Math.max(own, c.benefitFloorMonthly ?? 0) * 12
+}
+
+/** Expected PV of one person's own retirement benefit. */
+export function expectedPvSingle(c: ClaimantInput, opts: ExpectedPvOptions): number {
+  const maxAge = opts.maxAge ?? MALE.length - 1
+  const curve = survivalCurve(c.sex, c.longevityMultiplier)
+  const benefit = annualBenefit(c)
+  const startAge = Math.max(c.currentAge, c.claimAge.years)
+  let pv = 0
+  for (let age = startAge; age <= maxAge; age++) {
+    const t = age - c.currentAge
+    const discount = Math.pow(1 + opts.discountRate, -t)
+    pv += curve.survival(c.currentAge, age) * benefit * discount
+  }
+  return pv
+}
+
+/**
+ * Expected PV of a couple's combined benefits under a claiming strategy,
+ * including the spousal top-up (lower earner lifted to 50% of the higher PIA
+ * while both alive and both claimed) and the survivor step-up (survivor keeps
+ * the larger of the two benefits). Lifetimes assumed independent.
+ */
+export function expectedPvCouple(a: ClaimantInput, b: ClaimantInput, opts: ExpectedPvOptions): number {
+  const maxAge = opts.maxAge ?? MALE.length - 1
+  const curveA = survivalCurve(a.sex, a.longevityMultiplier)
+  const curveB = survivalCurve(b.sex, b.longevityMultiplier)
+  const benefitA = annualBenefit(a)
+  const benefitB = annualBenefit(b)
+  const lowerIsA = a.piaMonthly < b.piaMonthly
+  const higher = lowerIsA ? b : a
+  const lower = lowerIsA ? a : b
+  // Spousal benefit (50% of higher PIA) reduced for the lower earner's own claim age.
+  const spousalAnnual =
+    0.5 * higher.piaMonthly * spousalBenefitFactor(lower.dob.year, lower.dob.month, lower.dob.day, lower.claimAge) * 12
+
+  let pv = 0
+  // Step over calendar years from now until both spouses are past the table.
+  for (let t = 0; ; t++) {
+    const ageA = a.currentAge + t
+    const ageB = b.currentAge + t
+    if (ageA > maxAge && ageB > maxAge) break
+    const sA = curveA.survival(a.currentAge, ageA)
+    const sB = curveB.survival(b.currentAge, ageB)
+
+    const aClaimed = ageA >= a.claimAge.years
+    const bClaimed = ageB >= b.claimAge.years
+    const ownA = aClaimed ? benefitA : 0
+    const ownB = bClaimed ? benefitB : 0
+
+    // Both alive: spousal top-up lifts the lower earner once both have claimed.
+    let bothAlive = ownA + ownB
+    if (aClaimed && bClaimed) {
+      const lowerOwn = lowerIsA ? ownA : ownB
+      const otherOwn = lowerIsA ? ownB : ownA
+      bothAlive = otherOwn + Math.max(lowerOwn, spousalAnnual)
+    }
+
+    // One survivor: keeps the larger of the two claimed benefits.
+    const survivorBenefit = Math.max(ownA, ownB)
+
+    const expected =
+      sA * sB * bothAlive + sA * (1 - sB) * survivorBenefit + sB * (1 - sA) * survivorBenefit
+    pv += expected * Math.pow(1 + opts.discountRate, -t)
+  }
+  return pv
+}

package/src/socialSecurity/explain.ts

@@ -0,0 +1,92 @@
+/**
+ * Social Security explainer helpers (V7 phase 1). Pure functions that turn the
+ * earnings-mode PIA computation into teaching points: which bend-point tier the
+ * next dollar lands in, how many zero years drag down the average, the marginal
+ * value of replacing a zero year, and a rough credits-of-coverage eligibility
+ * estimate. No engine behavior depends on these — they only feed copy.
+ *
+ * @see DOCS/features/social-security.md §3.1
+ * @see DOCS/features/social-security.md
+ */
+
+import type { PiaFromEarningsResult, YearEarning } from '@retiregolden/engine/socialSecurity/piaFromEarnings'
+import { bendPointsForEligibilityYearOrLatest } from '@retiregolden/engine/socialSecurity/ssaWageData'
+
+/**
+ * SSA quarter-of-coverage ("credit") earnings amount — 2025 figure. One credit
+ * is earned per this much in covered wages, up to 4 per year. Used only to
+ * estimate eligibility for the warning; the user can override the credit count.
+ * @see https://www.ssa.gov/oact/cola/QC.html
+ */
+export const CREDIT_EARNINGS = 1_810
+export const CREDITS_FOR_ELIGIBILITY = 40
+
+export interface BendTier {
+  /** Replacement rate applied to the next dollar of AIME. */
+  label: '90%' | '32%' | '15%'
+  marginalRate: number
+  first: number
+  second: number
+}
+
+/** Which bend-point tier the next dollar of AIME falls into for this eligibility year. */
+export function bendTierForAime(aime: number, eligibilityYear: number): BendTier {
+  const bp = bendPointsForEligibilityYearOrLatest(eligibilityYear)
+  if (aime < bp.first) return { label: '90%', marginalRate: 0.9, first: bp.first, second: bp.second }
+  if (aime < bp.second) return { label: '32%', marginalRate: 0.32, first: bp.first, second: bp.second }
+  return { label: '15%', marginalRate: 0.15, first: bp.first, second: bp.second }
+}
+
+export interface ComputationSummary {
+  /** Years averaged into AIME (the top 35, or fewer if the history is short). */
+  computationYearCount: number
+  /** How many of those averaged years are $0 — each is a "replace a zero year" opportunity. */
+  zeroYearsInAime: number
+  /** AIME divisor in months (12 × computationYearCount). */
+  divisorMonths: number
+}
+
+export function summarizeComputation(result: PiaFromEarningsResult): ComputationSummary {
+  const zeroYearsInAime = result.yearsUsedInAime.filter((v) => v === 0).length
+  return {
+    computationYearCount: result.computationYearCount,
+    zeroYearsInAime,
+    divisorMonths: 12 * result.computationYearCount,
+  }
+}
+
+/**
+ * Marginal monthly-PIA gain from replacing one $0 computation year with a year
+ * of `indexedAnnual` covered earnings: AIME rises by indexedAnnual / divisor,
+ * then the next-dollar bend rate applies. A rough teaching estimate, not the
+ * exact recomputation (which would re-sort the top 35).
+ */
+export function replaceZeroYearGain(result: PiaFromEarningsResult, indexedAnnual: number): number {
+  if (indexedAnnual <= 0 || result.computationYearCount <= 0) return 0
+  const aimeDelta = indexedAnnual / (12 * result.computationYearCount)
+  return aimeDelta * bendTierForAime(result.aime, result.eligibilityYear).marginalRate
+}
+
+export interface CreditEstimate {
+  credits: number
+  eligible: boolean
+  /** True when derived from earnings rather than a user-entered count. */
+  estimated: boolean
+}
+
+/**
+ * Estimate covered-work credits (max 40). An explicit `override` wins; otherwise
+ * count up to 4 credits per year with covered earnings, using the current credit
+ * threshold (conservative for low-wage older years — the user can override).
+ */
+export function estimateCredits(earnings: YearEarning[], override: number | null | undefined): CreditEstimate {
+  if (override != null) {
+    return { credits: override, eligible: override >= CREDITS_FOR_ELIGIBILITY, estimated: false }
+  }
+  let credits = 0
+  for (const e of earnings) {
+    if (e.amount > 0) credits += Math.min(4, Math.floor(e.amount / CREDIT_EARNINGS))
+  }
+  credits = Math.min(CREDITS_FOR_ELIGIBILITY, credits)
+  return { credits, eligible: credits >= CREDITS_FOR_ELIGIBILITY, estimated: true }
+}

package/src/socialSecurity/ficaReturn.ts

@@ -0,0 +1,81 @@
+/**
+ * "What you paid in vs. what you get back" — a pure education/context readout
+ * for Social Security, NOT a working-years tax inside the projection (the engine
+ * never taxes pre-retirement wages; this is an analysis helper called from the SS
+ * analysis panel). Cited in DOCS/domain/domain-rules-reference.md §4.
+ *
+ * - **Paid in** = the OASDI (Social Security portion) payroll tax over the
+ *   entered earnings history, capped at each year's taxable wage base. Employee
+ *   share = 6.2%; self-employed = 12.4% (employee + employer combined). The 1.45%
+ *   Medicare HI is intentionally excluded (the "get back" side is the SS
+ *   benefit, not Medicare). The employer's 6.2% is returned as optional context.
+ * - **Get back** reuses the tested `expectedPvSingle` path (mortality-weighted
+ *   expected PV at the chosen claim age), so the "return" is the survival-
+ *   weighted PV of lifetime benefits in today's dollars.
+ *
+ * Documented simplifications: the OASDI rate is applied uniformly over the
+ * career (historical rates were slightly lower pre-1990); the self-employed
+ * half-deductibility of SE tax is ignored; the figure is an individual-level
+ * illustration, not the program's actuarial return, and excludes disability and
+ * survivor insurance value, spousal benefits, and the Medicare portion.
+ */
+
+import { WAGE_BASE_BY_YEAR } from '@retiregolden/engine/socialSecurity/ssaWageData'
+
+export interface FicaPaidInResult {
+  /** Employee (or self-employed total) OASDI paid over the earnings history, today's $. */
+  paidIn: number
+  /** Employer-side OASDI (context only; 0 for self-employed since it's in paidIn). */
+  employerPaid: number
+}
+
+export interface FicaPaidInOptions {
+  /** Employee-side OASDI rate as a percent (e.g. 6.2). From the parameter pack. */
+  oasdiEmployeeRatePct: number
+  /** Self-employed ⇒ paidIn doubles (employee + employer combined = 12.4%). */
+  selfEmployed: boolean
+  /**
+   * Per-year OASDI taxable wage base. Defaults to the SSA historical series
+   * (`WAGE_BASE_BY_YEAR`); the caller may override (e.g., a grown future cap).
+   */
+  wageBaseByYear?: Readonly<Record<number, number>>
+  /** Wage base for earnings years beyond the table (defaults to the latest known). */
+  wageBaseFallback?: number
+}
+
+/**
+ * Sum the OASDI payroll tax over an earnings history (employee or self-employed),
+ * capped at each year's taxable wage base. Today's dollars (nominal history; no
+ * indexing — this is "what you literally paid," not wage-indexed like AIME).
+ */
+export function ficaOasdiPaidIn(
+  earnings: ReadonlyArray<{ year: number; amount: number }>,
+  opts: FicaPaidInOptions,
+): FicaPaidInResult {
+  const table = opts.wageBaseByYear ?? WAGE_BASE_BY_YEAR
+  const fallback = opts.wageBaseFallback ?? latestWageBase(table)
+  const rate = opts.oasdiEmployeeRatePct / 100
+  let employee = 0
+  let employer = 0
+  for (const { year, amount } of earnings) {
+    if (amount <= 0) continue
+    const cap = table[year] ?? fallback
+    const capped = cap > 0 ? Math.min(amount, cap) : amount
+    if (opts.selfEmployed) {
+      employee += capped * rate * 2 // 12.4% total (employee + employer)
+    } else {
+      employee += capped * rate // 6.2% employee
+      employer += capped * rate // 6.2% employer (context)
+    }
+  }
+  return { paidIn: employee, employerPaid: opts.selfEmployed ? 0 : employer }
+}
+
+function latestWageBase(table: Readonly<Record<number, number>>): number {
+  let latest = 0
+  for (const y of Object.keys(table)) {
+    const year = Number(y)
+    if (Number.isFinite(year) && table[year]! > latest) latest = table[year]!
+  }
+  return latest
+}

package/src/socialSecurity/persistedSsGuard.ts

@@ -0,0 +1,138 @@
+import type { HouseholdMode, PiaSourceMode, QuickPiaKind, SsFormSnapshot, SsPersisted } from './storage'
+
+function isRecord(x: unknown): x is Record<string, unknown> {
+  return typeof x === 'object' && x !== null && !Array.isArray(x)
+}
+
+function num(x: unknown): number | null {
+  return typeof x === 'number' && Number.isFinite(x) ? x : null
+}
+
+function str(x: unknown): string | null {
+  return typeof x === 'string' ? x : null
+}
+
+function oneOf<T extends string>(x: unknown, allowed: readonly T[]): T | undefined {
+  if (x === undefined) return undefined
+  return typeof x === 'string' && (allowed as readonly string[]).includes(x) ? (x as T) : undefined
+}
+
+function claimAgesList(x: unknown): number[] | null {
+  if (!Array.isArray(x)) return null
+  const out: number[] = []
+  for (const a of x) {
+    const n = num(a)
+    if (n == null || n < 62 || n > 70) return null
+    out.push(n)
+  }
+  return out.length >= 2 ? out : null
+}
+
+function partnerClaimAgesList(x: unknown): number[] | null {
+  if (!Array.isArray(x)) return null
+  const out: number[] = []
+  for (const a of x) {
+    const n = num(a)
+    if (n == null || n < 62 || n > 70) return null
+    out.push(n)
+  }
+  return out.length >= 1 ? out : null
+}
+
+/** Returns null if JSON shape does not match v1 SS persisted form (schema drift / corruption). */
+export function parseSsPersistedLoose(raw: unknown): SsPersisted | null {
+  if (!isRecord(raw)) return null
+  if (raw.version !== 1) return null
+  const formRaw = raw.form
+  if (!isRecord(formRaw)) return null
+
+  const dob = str(formRaw.dob)
+  const piaMonthly = num(formRaw.piaMonthly)
+  const claimAges = claimAgesList(formRaw.claimAges)
+  const endAge = num(formRaw.endAge)
+  const colaPercent = num(formRaw.colaPercent)
+  const discountPercent = num(formRaw.discountPercent)
+  if (!dob || piaMonthly == null || !claimAges || endAge == null || colaPercent == null || discountPercent == null) {
+    return null
+  }
+  if (endAge < 63 || endAge > 110) return null
+
+  let partnerClaimAges: number[] | undefined
+  if (formRaw.partnerClaimAges !== undefined) {
+    const pa = partnerClaimAgesList(formRaw.partnerClaimAges)
+    if (pa == null) return null
+    partnerClaimAges = pa
+  }
+
+  const householdMode = oneOf<HouseholdMode>(formRaw.householdMode, ['single', 'couple'])
+  const piaSource = oneOf<PiaSourceMode>(formRaw.piaSource, ['quick', 'earnings'])
+  const partnerPiaSource = oneOf<PiaSourceMode>(formRaw.partnerPiaSource, ['quick', 'earnings'])
+  const quickPiaKind = oneOf<QuickPiaKind>(formRaw.quickPiaKind, ['authoritative', 'ssa_estimate'])
+  const partnerQuickPiaKind = oneOf<QuickPiaKind>(formRaw.partnerQuickPiaKind, [
+    'authoritative',
+    'ssa_estimate',
+  ])
+
+  const form: SsFormSnapshot = {
+    householdMode,
+    dob,
+    piaSource,
+    piaMonthly,
+    quickPiaKind,
+    ssaEstimateWorkThroughAge:
+      formRaw.ssaEstimateWorkThroughAge === undefined
+        ? undefined
+        : formRaw.ssaEstimateWorkThroughAge === null
+          ? null
+          : num(formRaw.ssaEstimateWorkThroughAge),
+    earningsPaste: typeof formRaw.earningsPaste === 'string' ? formRaw.earningsPaste : undefined,
+    lastEarningsYear:
+      formRaw.lastEarningsYear === undefined
+        ? undefined
+        : formRaw.lastEarningsYear === null
+          ? null
+          : num(formRaw.lastEarningsYear),
+    claimAges,
+    partnerDob: typeof formRaw.partnerDob === 'string' ? formRaw.partnerDob : undefined,
+    partnerPiaSource,
+    partnerPiaMonthly:
+      formRaw.partnerPiaMonthly === undefined ? undefined : num(formRaw.partnerPiaMonthly) ?? undefined,
+    partnerQuickPiaKind,
+    partnerSsaEstimateWorkThroughAge:
+      formRaw.partnerSsaEstimateWorkThroughAge === undefined
+        ? undefined
+        : formRaw.partnerSsaEstimateWorkThroughAge === null
+          ? null
+          : num(formRaw.partnerSsaEstimateWorkThroughAge),
+    partnerEarningsPaste:
+      typeof formRaw.partnerEarningsPaste === 'string' ? formRaw.partnerEarningsPaste : undefined,
+    partnerLastEarningsYear:
+      formRaw.partnerLastEarningsYear === undefined
+        ? undefined
+        : formRaw.partnerLastEarningsYear === null
+          ? null
+          : num(formRaw.partnerLastEarningsYear),
+    partnerClaimAges,
+    survivorOverlayEnabled:
+      typeof formRaw.survivorOverlayEnabled === 'boolean' ? formRaw.survivorOverlayEnabled : undefined,
+    survivorPrimaryDeathAge:
+      formRaw.survivorPrimaryDeathAge === undefined
+        ? undefined
+        : formRaw.survivorPrimaryDeathAge === null
+          ? null
+          : num(formRaw.survivorPrimaryDeathAge),
+    survivorPartnerDeathAge:
+      formRaw.survivorPartnerDeathAge === undefined
+        ? undefined
+        : formRaw.survivorPartnerDeathAge === null
+          ? null
+          : num(formRaw.survivorPartnerDeathAge),
+    endAge,
+    colaPercent,
+    discountPercent,
+  }
+
+  const updatedAt = str(raw.updatedAt)
+  if (!updatedAt) return null
+  return { version: 1, form, updatedAt }
+}

package/src/socialSecurity/ssFormUtils.ts

@@ -0,0 +1,48 @@
+import { loadLongevity } from '../longevity/storage'
+import { loadSs, type SsFormSnapshot } from './storage'
+
+export const CLAIM_OPTIONS = [62, 63, 64, 65, 66, 67, 68, 69, 70] as const
+
+export function parseDob(iso: string): { y: number; m: number; d: number } | null {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso.trim())
+  if (!m) return null
+  const y = Number(m[1])
+  const mo = Number(m[2])
+  const d = Number(m[3])
+  if (!y || mo < 1 || mo > 12 || d < 1 || d > 31) return null
+  return { y, m: mo, d }
+}
+
+export const SS_CHART_LINE_COLORS = [
+  '#0d9488',
+  '#6366f1',
+  '#a855f7',
+  '#ea580c',
+  '#0891b2',
+  '#16a34a',
+  '#ca8a04',
+  '#dc2626',
+  '#db2777',
+]
+
+export function defaultEndAge(): number {
+  const L = loadLongevity()
+  if (L?.result?.illustrativePlanningAge) return L.result.illustrativePlanningAge
+  return 90
+}
+
+export function initialSsForm(): SsFormSnapshot {
+  const saved = loadSs()
+  if (saved?.form) return saved.form
+  return {
+    householdMode: 'single',
+    dob: '1962-06-15',
+    piaSource: 'quick',
+    quickPiaKind: 'authoritative',
+    piaMonthly: 3200,
+    claimAges: [62, 67, 70],
+    endAge: defaultEndAge(),
+    colaPercent: 0,
+    discountPercent: 0,
+  }
+}