@retiregolden/planner-ui 0.1.0

package/src/socialSecurity/ssaStatementXml.ts

@@ -0,0 +1,156 @@
+/**
+ * Parse mySSA "Online Social Security Statement" XML (OSSS schema 2.0).
+ * @see http://ssa.gov/osss/schemas/2.0
+ */
+
+import type { YearEarning } from '@retiregolden/engine/socialSecurity/piaFromEarnings'
+
+export const OSSS_NS = 'http://ssa.gov/osss/schemas/2.0'
+
+export type SsaStatementXmlOk = {
+  ok: true
+  dob: string
+  rows: YearEarning[]
+  /** SSA statement name field (PII); optional display only. */
+  statementName?: string
+  /** XML FileCreationDate text if present; display only. */
+  fileCreationDate?: string
+  /** When endYear > startYear on an Earnings element, only startYear was applied. */
+  yearRangeWarnings: string[]
+}
+
+export type SsaStatementXmlFail = {
+  ok: false
+  message: string
+}
+
+export type SsaStatementXmlResult = SsaStatementXmlOk | SsaStatementXmlFail
+
+function textContentNs(parent: Element, localName: string): string {
+  const NS = OSSS_NS
+  const kids = parent.getElementsByTagNameNS(NS, localName)
+  return kids[0]?.textContent?.trim() ?? ''
+}
+
+function parseNonNegInt(s: string | null | undefined): number | null {
+  if (s == null || s === '') return null
+  const n = Number.parseInt(String(s).trim(), 10)
+  if (!Number.isFinite(n) || n < 0) return null
+  return n
+}
+
+function parseNonNegAmount(s: string | null | undefined): number {
+  if (s == null || s === '') return 0
+  const n = Number.parseFloat(String(s).trim())
+  if (!Number.isFinite(n) || n < 0) return 0
+  return n
+}
+
+function isValidDobIso(s: string): boolean {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s.trim())
+  if (!m) return false
+  const y = Number(m[1])
+  const mo = Number(m[2])
+  const d = Number(m[3])
+  return !!(y && mo >= 1 && mo <= 12 && d >= 1 && d <= 31)
+}
+
+/**
+ * Serialize earnings rows for `earningsPaste` / `parseEarningsLines`.
+ */
+export function yearEarningsToPaste(rows: YearEarning[]): string {
+  const sorted = [...rows].sort((a, b) => a.year - b.year)
+  return sorted.map((r) => `${r.year} ${r.amount}`).join('\n')
+}
+
+/**
+ * Parse OSSS 2.0 statement XML (browser or Vitest jsdom).
+ */
+export function parseSsaStatementXml(xmlText: string): SsaStatementXmlResult {
+  if (typeof DOMParser === 'undefined') {
+    return { ok: false, message: 'XML parsing is not available in this environment.' }
+  }
+
+  const doc = new DOMParser().parseFromString(xmlText, 'application/xml')
+  const root = doc.documentElement
+  if (!root) {
+    return { ok: false, message: 'Empty or invalid XML document.' }
+  }
+
+  const pe = doc.getElementsByTagName('parsererror')
+  if (pe.length > 0) {
+    const hint = pe[0]?.textContent?.trim().slice(0, 200)
+    return {
+      ok: false,
+      message: hint ? `XML parse error: ${hint}` : 'XML parse error.',
+    }
+  }
+
+  if (root.namespaceURI !== OSSS_NS || root.localName !== 'OnlineSocialSecurityStatementData') {
+    return {
+      ok: false,
+      message:
+        'Not a recognized SSA online statement export (expected OnlineSocialSecurityStatementData in the official SSA namespace).',
+    }
+  }
+
+  const dobRaw = textContentNs(root, 'DateOfBirth')
+  if (!isValidDobIso(dobRaw)) {
+    return { ok: false, message: 'Statement XML is missing a valid DateOfBirth (YYYY-MM-DD).' }
+  }
+
+  const nameRaw = textContentNs(root, 'Name')
+  const fileDateRaw = textContentNs(root, 'FileCreationDate')
+
+  const yearRangeWarnings: string[] = []
+  const byYear = new Map<number, number>()
+
+  const earningsNodes = root.getElementsByTagNameNS(OSSS_NS, 'Earnings')
+  for (let i = 0; i < earningsNodes.length; i++) {
+    const el = earningsNodes[i]!
+    const startY = parseNonNegInt(el.getAttribute('startYear'))
+    if (startY === null || startY < 1951 || startY > 2100) continue
+
+    const endYRaw = el.getAttribute('endYear')
+    const endY = endYRaw != null && endYRaw !== '' ? parseNonNegInt(endYRaw) : startY
+    const end = endY === null ? startY : endY
+
+    if (end > startY) {
+      yearRangeWarnings.push(
+        `Earnings element with startYear=${startY} and endYear=${end}: using start year only (same as SSA row granularity in exports).`,
+      )
+    }
+
+    const fica = parseNonNegAmount(textContentNs(el, 'FicaEarnings'))
+    const y = startY
+    const prev = byYear.get(y) ?? 0
+    byYear.set(y, prev + fica)
+  }
+
+  const rows: YearEarning[] = []
+  for (const [year, amount] of byYear) {
+    rows.push({ year, amount })
+  }
+
+  return {
+    ok: true,
+    dob: dobRaw.trim(),
+    rows,
+    statementName: nameRaw || undefined,
+    fileCreationDate: fileDateRaw || undefined,
+    yearRangeWarnings,
+  }
+}
+
+/** Latest year with positive FICA earnings; if none, latest year in rows. */
+export function defaultLastEarningsYearFromRows(rows: YearEarning[]): number | null {
+  if (rows.length === 0) return null
+  let maxAny = rows[0]!.year
+  let maxPositive = -Infinity
+  for (const r of rows) {
+    if (r.year > maxAny) maxAny = r.year
+    if (r.amount > 0 && r.year > maxPositive) maxPositive = r.year
+  }
+  if (Number.isFinite(maxPositive)) return maxPositive
+  return maxAny
+}

package/src/socialSecurity/storage.ts

@@ -0,0 +1,69 @@
+import { readLocal, STORAGE_KEYS, writeLocal } from '../data/localStore'
+import { parseSsPersistedLoose } from './persistedSsGuard'
+
+export const SS_STORAGE_KEY = STORAGE_KEYS.socialSecurityForm
+
+export type PiaSourceMode = 'quick' | 'earnings'
+
+/** Household scope for Social Security workbench (M6). */
+export type HouseholdMode = 'single' | 'couple'
+
+/** How the quick-mode PIA number should be interpreted (for disclosure only). */
+export type QuickPiaKind = 'authoritative' | 'ssa_estimate'
+
+export interface SsFormSnapshot {
+  /** When `couple`, partner fields apply and analysis uses household strategies. */
+  householdMode?: HouseholdMode
+  dob: string
+  /** Default `quick`: enter PIA manually. `earnings`: derive PIA from pasted earnings. */
+  piaSource?: PiaSourceMode
+  piaMonthly: number
+  /** Meaning of the quick-mode PIA figure; optional for backward compatibility. */
+  quickPiaKind?: QuickPiaKind
+  /** When `quickPiaKind` is `ssa_estimate`, optional age through which SSA assumed work. */
+  ssaEstimateWorkThroughAge?: number | null
+  /** Lines of `year amount` for earnings mode; see `parseEarningsLines`. */
+  earningsPaste?: string
+  /** Last calendar year with covered earnings (earnings mode); omit to use last base year. */
+  lastEarningsYear?: number | null
+  claimAges: number[]
+  /** Partner (second earner) — used when `householdMode === 'couple'`. */
+  partnerDob?: string
+  partnerPiaSource?: PiaSourceMode
+  partnerPiaMonthly?: number
+  partnerQuickPiaKind?: QuickPiaKind
+  partnerSsaEstimateWorkThroughAge?: number | null
+  partnerEarningsPaste?: string
+  partnerLastEarningsYear?: number | null
+  partnerClaimAges?: number[]
+  /** When true, household cumulative uses illustrative death ages (see below). */
+  survivorOverlayEnabled?: boolean
+  /** Completed age through which primary receives benefits (inclusive). */
+  survivorPrimaryDeathAge?: number | null
+  /** Completed age through which partner receives benefits (inclusive). */
+  survivorPartnerDeathAge?: number | null
+  endAge: number
+  colaPercent: number
+  discountPercent: number
+}
+
+export interface SsPersisted {
+  version: 1
+  form: SsFormSnapshot
+  updatedAt: string
+}
+
+export function loadSs(): SsPersisted | null {
+  try {
+    const raw = readLocal(SS_STORAGE_KEY)
+    if (!raw) return null
+    return parseSsPersistedLoose(JSON.parse(raw) as unknown)
+  } catch {
+    return null
+  }
+}
+
+export function saveSs(form: SsFormSnapshot): void {
+  const data: SsPersisted = { version: 1, form, updatedAt: new Date().toISOString() }
+  writeLocal(SS_STORAGE_KEY, JSON.stringify(data))
+}

package/src/socialSecurity/survivorSwitching.ts

@@ -0,0 +1,153 @@
+/**
+ * Survivor ↔ personal switching (V7 phase 3). A widow(er) can hold two benefits
+ * on different records and switch between them: take the survivor benefit early
+ * and let their own retirement benefit grow to 70, or take their own early and
+ * switch to survivor later. Only one benefit is paid at a time (the larger of
+ * those claimed), so the value is in the *sequencing*.
+ *
+ * Why it matters: survivor benefits earn no delayed credits (they top out at the
+ * survivor's FRA), while own benefits grow ~8%/yr to 70. So a common pattern is
+ * survivor-first then own-at-70 when the deceased's benefit is the smaller of the
+ * two, or own-first then survivor when own is smaller.
+ *
+ * Survivor precision (cited in DOCS/domain/domain-rules-reference.md §4): the
+ * early-claim widow(er) reduction (up to 28.5% at 60, measured against the
+ * **survivor** FRA — a separate, earlier schedule than the worker FRA) and the
+ * **RIB-LIM / widow's-limit** cap (`max(deceased's actual benefit, 82.5% × PIA)`)
+ * are computed by the shared `survivorBenefitMonthly` helper, identical to the
+ * projection ledger so the PV view and the ledger can't drift. Illustrative, not
+ * a filing tool.
+ *
+ * @see DOCS/features/social-security.md
+ */
+
+import { claimFactor } from '@retiregolden/engine/socialSecurity/claimFactor'
+import { survivalCurve } from './expectedPv'
+import type { Sex } from '@retiregolden/engine/longevity/types'
+import { effectiveBirthYear, fraForBirthYear, fraTotalMonths, survivorFraForBirthYear } from '@retiregolden/engine/socialSecurity/nra'
+import { survivorBenefitMonthly, survivorReductionFactor, SURVIVOR_EARLIEST_AGE } from '@retiregolden/engine/socialSecurity/survivorBenefit'
+
+// Re-exported for back-compat (callers that previously imported them from here).
+export { survivorReductionFactor, SURVIVOR_EARLIEST_AGE }
+
+export interface SwitchingInput {
+  dob: { year: number; month: number; day: number }
+  sex: Sex
+  /** Whole age today (PV reference, t=0). */
+  currentAge: number
+  /** The claimant's own monthly PIA. */
+  ownPiaMonthly: number
+  /**
+   * The deceased spouse's actual monthly benefit (claim-age-adjusted, including
+   * delayed credits) — the survivor base before RIB-LIM.
+   */
+  survivorMonthly: number
+  /**
+   * The deceased's monthly PIA. When omitted, defaults to `survivorMonthly`
+   * (i.e. the deceased claimed at FRA: actual = PIA), so the RIB-LIM floor
+   * (82.5% × PIA) never binds and behavior matches the pre-precision model.
+   * Provide it separately when the deceased claimed early (actual < PIA) so the
+   * widow's-limit cap is applied.
+   */
+  deceasedPiaMonthly?: number
+  /** Scales SSA remaining-years (longevity questionnaire); default 1. */
+  longevityMultiplier?: number
+}
+
+export interface SwitchStrategy {
+  /** Age the survivor benefit starts (≥60), or null to never take survivor. */
+  survivorClaimAge: number | null
+  /** Age the own retirement benefit starts (62–70), or null to never take own. */
+  ownClaimAge: number | null
+}
+
+export interface SwitchResult {
+  strategy: SwitchStrategy
+  expectedPv: number
+  /** Plain-language description, e.g. "Survivor at 60, switch to own at 70". */
+  label: string
+}
+
+function strategyLabel(s: SwitchStrategy): string {
+  if (s.survivorClaimAge !== null && s.ownClaimAge !== null) {
+    if (s.survivorClaimAge <= s.ownClaimAge) return `Survivor at ${s.survivorClaimAge}, switch to own at ${s.ownClaimAge}`
+    return `Own at ${s.ownClaimAge}, switch to survivor at ${s.survivorClaimAge}`
+  }
+  if (s.survivorClaimAge !== null) return `Survivor only, at ${s.survivorClaimAge}`
+  if (s.ownClaimAge !== null) return `Own only, at ${s.ownClaimAge}`
+  return 'Claim nothing'
+}
+
+export interface SwitchingOptions {
+  discountRate: number
+  maxAge?: number
+}
+
+/** Expected PV of a single switching strategy: survival-weighted, discounted to today. */
+export function expectedPvSwitch(input: SwitchingInput, strategy: SwitchStrategy, opts: SwitchingOptions): number {
+  const maxAge = opts.maxAge ?? 119
+  const curve = survivalCurve(input.sex, input.longevityMultiplier)
+  const survivorFraMonths = fraTotalMonths(
+    survivorFraForBirthYear(effectiveBirthYear(input.dob.year, input.dob.month, input.dob.day)),
+  )
+
+  const deceasedPia = input.deceasedPiaMonthly ?? input.survivorMonthly
+  const survivorAnnual =
+    strategy.survivorClaimAge !== null
+      ? survivorBenefitMonthly({
+          deceasedPiaMonthly: deceasedPia,
+          deceasedActualMonthly: input.survivorMonthly,
+          survivorClaimAge: { years: strategy.survivorClaimAge, months: 0 },
+          survivorFraMonths,
+        }) * 12
+      : 0
+  const ownAnnual =
+    strategy.ownClaimAge !== null
+      ? input.ownPiaMonthly * 12 * claimFactor(input.dob.year, input.dob.month, input.dob.day, { years: strategy.ownClaimAge, months: 0 })
+      : 0
+
+  let pv = 0
+  for (let age = input.currentAge; age <= maxAge; age++) {
+    const survivorOn = strategy.survivorClaimAge !== null && age >= strategy.survivorClaimAge
+    const ownOn = strategy.ownClaimAge !== null && age >= strategy.ownClaimAge
+    const benefit = Math.max(survivorOn ? survivorAnnual : 0, ownOn ? ownAnnual : 0)
+    if (benefit > 0) {
+      const t = age - input.currentAge
+      pv += curve.survival(input.currentAge, age) * benefit * Math.pow(1 + opts.discountRate, -t)
+    }
+  }
+  return pv
+}
+
+/**
+ * Rank candidate switching strategies by expected PV (descending). Sweeps
+ * survivor claim ages 60→FRA and own claim ages 62→70, plus the single-benefit
+ * options, never claiming before the claimant's current age.
+ */
+export function rankSwitchStrategies(input: SwitchingInput, opts: SwitchingOptions): SwitchResult[] {
+  const effY = effectiveBirthYear(input.dob.year, input.dob.month, input.dob.day)
+  const survivorFraYears = survivorFraForBirthYear(effY).years
+  const ownFraYears = fraForBirthYear(effY).years
+  // Always include "claim now" so users already past the earliest age can still
+  // take a benefit immediately (e.g. a 63-year-old widow bridging to own at 70).
+  const survivorNow = Math.max(input.currentAge, SURVIVOR_EARLIEST_AGE)
+  const survivorAges = [...new Set([survivorNow, Math.max(survivorNow, survivorFraYears)])]
+  const ownNow = Math.min(70, Math.max(input.currentAge, 62))
+  const ownAges = [...new Set([ownNow, ownFraYears, 70].filter((a) => a >= ownNow && a <= 70))]
+
+  const strategies: SwitchStrategy[] = []
+  for (const s of survivorAges) for (const o of ownAges) strategies.push({ survivorClaimAge: s, ownClaimAge: o })
+  for (const s of survivorAges) strategies.push({ survivorClaimAge: s, ownClaimAge: null })
+  for (const o of ownAges) strategies.push({ survivorClaimAge: null, ownClaimAge: o })
+
+  // De-dupe identical (survivor/own age) pairs that survive the filters.
+  const seen = new Set<string>()
+  const results: SwitchResult[] = []
+  for (const strategy of strategies) {
+    const key = `${strategy.survivorClaimAge ?? 'x'}-${strategy.ownClaimAge ?? 'x'}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    results.push({ strategy, expectedPv: expectedPvSwitch(input, strategy, opts), label: strategyLabel(strategy) })
+  }
+  return results.sort((a, b) => b.expectedPv - a.expectedPv)
+}

package/src/testSupport/samplePlan.ts

@@ -0,0 +1,2 @@
+/** @deprecated Use the example library registry — kept for tests importing createSamplePlan. */
+export { buildExampleCouple as createSamplePlan } from '../planner/examples/buildExampleCouple'

package/src/workers/run.ts

@@ -0,0 +1,45 @@
+/**
+ * Generic Web Worker request/response runner shared by the Monte Carlo pool
+ * (src/mc/pool.ts) and the optimizer/spending solvers (src/optimize/). Spawns
+ * a worker, posts one request, resolves on the interpreted done-message,
+ * rejects on an error message or worker error, and always terminates the
+ * worker once settled.
+ */
+
+export type WorkerMessageOutcome<TResult> =
+  | { kind: 'done'; result: TResult }
+  | { kind: 'error'; message: string }
+  /** Keep listening (e.g. progress messages). */
+  | { kind: 'progress' }
+
+export function runWorkerRequest<TReq, TMsg, TResult>(options: {
+  request: TReq
+  /**
+   * Call sites keep the literal `new Worker(new URL('./x.worker.ts',
+   * import.meta.url), ...)` so the bundler can still see and split the chunk.
+   */
+  createWorker: () => Worker
+  interpret: (msg: TMsg) => WorkerMessageOutcome<TResult>
+  /** Fallback error text when the worker fails without a message. */
+  errorLabel: string
+  /** Observe the spawned worker (e.g. so a pool can terminate siblings). */
+  onSpawn?: (worker: Worker) => void
+}): Promise<TResult> {
+  const { request, createWorker, interpret, errorLabel, onSpawn } = options
+  return new Promise((resolve, reject) => {
+    const worker = createWorker()
+    onSpawn?.(worker)
+    worker.onmessage = (event: MessageEvent<TMsg>) => {
+      const outcome = interpret(event.data)
+      if (outcome.kind === 'progress') return
+      worker.terminate()
+      if (outcome.kind === 'done') resolve(outcome.result)
+      else reject(new Error(outcome.message))
+    }
+    worker.onerror = (event) => {
+      worker.terminate()
+      reject(new Error(event.message || errorLabel))
+    }
+    worker.postMessage(request)
+  })
+}