@retiregolden/planner-ui 0.1.0

package/src/planner/marketModelPicker.ts

@@ -0,0 +1,172 @@
+/**
+ * Market-model picker wiring: the plain-language presets shown up front, the
+ * full advanced catalog behind the disclosure, and the mapping from a picked
+ * kind to a MarketModelConfig. Pure UI-level mapping — every config value
+ * written here already existed when the picker was a flat <select>, so a
+ * given (kind, seed) pair produces byte-identical Monte Carlo results.
+ */
+
+import { planUsesAssetAllocation, resolveAssetClassParams } from '@retiregolden/engine/allocation/assetClasses'
+import { ASSET_CLASS_IDS, type AssetClassId } from '@retiregolden/engine/model/plan'
+import type { Plan } from '@retiregolden/engine/model/plan'
+import { buildLognormalModelConfigForPlan, type ClassShockConfig, type MarketModelConfig } from '@retiregolden/engine/montecarlo/marketModels'
+
+export type ModelKind =
+  | 'lognormal'
+  | 'hist-iid'
+  | 'hist-block'
+  | 'hist-sequence'
+  | 'student-t'
+  | 'regime-switch'
+  | 'cape-conditioned'
+  | 'stationary'
+  | 'empirical'
+  | 'garch'
+  | 'inflation-regime'
+  | 'reversed-history'
+  | 'user-shock'
+  | 'gaussian'
+  | 'ar1'
+
+export type ModelPresetId = 'smooth' | 'history' | 'stress'
+
+export interface ModelPreset {
+  id: ModelPresetId
+  label: string
+  description: string
+  kind: ModelKind
+}
+
+/** The three plain-language choices shown before the advanced disclosure. */
+export const MODEL_PRESETS: ReadonlyArray<ModelPreset> = [
+  {
+    id: 'smooth',
+    label: 'Smooth randomness (recommended)',
+    description: 'Each year varies around your expected return, like a bell curve.',
+    kind: 'lognormal',
+  },
+  {
+    id: 'history',
+    label: 'Replay real history',
+    description: 'Your retirement starts in a random past year and history unfolds from there.',
+    kind: 'hist-sequence',
+  },
+  {
+    id: 'stress',
+    label: 'Stress test',
+    description: 'A 25% market drop hits in year one, then markets vary normally.',
+    kind: 'user-shock',
+  },
+]
+
+export const PRESET_FAMILY_LABELS: Record<ModelPresetId, string> = {
+  smooth: 'Smooth randomness',
+  history: 'Replay real history',
+  stress: 'Stress test',
+}
+
+/** The full advanced catalog. Every kind the old flat <select> offered stays reachable. */
+export const MODEL_CATALOG: ReadonlyArray<{ kind: ModelKind; label: string; family: ModelPresetId }> = [
+  { kind: 'lognormal', label: 'Lognormal (correlated inflation)', family: 'smooth' },
+  { kind: 'hist-iid', label: 'Historical bootstrap — independent years', family: 'history' },
+  { kind: 'hist-block', label: 'Historical bootstrap — 5-year blocks', family: 'history' },
+  { kind: 'hist-sequence', label: 'Historical full-sequence replay', family: 'history' },
+  { kind: 'student-t', label: 'Student-t (fat tails)', family: 'smooth' },
+  { kind: 'regime-switch', label: 'Regime-switching (bull/bear Markov)', family: 'smooth' },
+  { kind: 'cape-conditioned', label: 'CAPE-conditioned mean reversion', family: 'smooth' },
+  { kind: 'stationary', label: 'Stationary bootstrap (variable blocks)', family: 'history' },
+  { kind: 'empirical', label: 'Empirical historical (mean-preserving)', family: 'history' },
+  { kind: 'garch', label: 'GARCH(1,1) vol clustering', family: 'smooth' },
+  { kind: 'inflation-regime', label: 'Inflation regime (fat/high-infl)', family: 'smooth' },
+  { kind: 'reversed-history', label: 'Reversed-history windows', family: 'stress' },
+  { kind: 'user-shock', label: 'User shock scenario (year-1 crash)', family: 'stress' },
+  { kind: 'gaussian', label: 'Gaussian (additive normal)', family: 'smooth' },
+  { kind: 'ar1', label: 'AR(1) mean-reverting shocks', family: 'smooth' },
+]
+
+export function presetFamilyOf(kind: ModelKind): ModelPresetId {
+  return MODEL_CATALOG.find((entry) => entry.kind === kind)?.family ?? 'smooth'
+}
+
+export function catalogLabelOf(kind: ModelKind): string {
+  return MODEL_CATALOG.find((entry) => entry.kind === kind)?.label ?? kind
+}
+
+function buildClassShocks(plan: Plan): ClassShockConfig | undefined {
+  if (!planUsesAssetAllocation(plan)) return undefined
+  const params = resolveAssetClassParams(plan.assumptions.assetClassParams)
+  const volatilityPctByClass = Object.fromEntries(
+    ASSET_CLASS_IDS.map((id) => [id, params[id].volatilityPct]),
+  ) as Record<AssetClassId, number>
+  return { volatilityPctByClass }
+}
+
+export function buildModel(
+  kind: ModelKind,
+  inflationMeanPct: number,
+  returnVolPct: number,
+  equityWeightPct: number,
+  plan: Plan,
+): MarketModelConfig {
+  // Plans with allocated accounts get per-class correlated shocks sharing the
+  // deterministic ledger's allocation schema; single-return plans keep the
+  // single-factor model (and their exact seeded paths) unchanged.
+  const classShocks = buildClassShocks(plan)
+  if (kind === 'lognormal') {
+    return {
+      ...buildLognormalModelConfigForPlan(plan, returnVolPct),
+      inflationMeanPct,
+    }
+  }
+  if (kind === 'hist-iid' || kind === 'hist-block' || kind === 'hist-sequence') {
+    return {
+      type: 'historical',
+      mode: kind === 'hist-iid' ? 'iid' : kind === 'hist-block' ? 'block' : 'sequence',
+      equityWeightPct,
+      classShocks: !!classShocks,
+    }
+  }
+  if (kind === 'student-t') {
+    return { type: 'student-t', inflationMeanPct, returnVolPct, classShocks }
+  }
+  if (kind === 'regime-switch') {
+    return { type: 'regime-switch', inflationMeanPct, classShocks }
+  }
+  if (kind === 'cape-conditioned') {
+    return { type: 'cape-conditioned', inflationMeanPct, returnVolPct, startingCape: 28, classShocks }
+  }
+  if (kind === 'stationary') {
+    return { type: 'stationary', equityWeightPct, classShocks: !!classShocks }
+  }
+  if (kind === 'empirical') {
+    // Default to centered (mean-preserving) for correctness. Non-centered (raw historical
+    // as shock) can overstate results because simulate always does expected + shock.
+    // Non-centered kept in config for advanced/experimental use.
+    return { type: 'empirical', equityWeightPct, centered: true, classShocks: !!classShocks }
+  }
+  if (kind === 'garch') {
+    return { type: 'garch', inflationMeanPct, returnVolScalePct: returnVolPct, classShocks }
+  }
+  if (kind === 'inflation-regime') {
+    return { type: 'inflation-regime', baseInflationMeanPct: inflationMeanPct, classShocks }
+  }
+  if (kind === 'reversed-history') {
+    return { type: 'reversed-history', equityWeightPct, windowLengthYears: 10, classShocks: !!classShocks }
+  }
+  if (kind === 'user-shock') {
+    return { type: 'user-shock', inflationMeanPct, shockYear: 1, shockPct: -25, baseReturnVolPct: returnVolPct, classShocks }
+  }
+  if (kind === 'gaussian') {
+    return { type: 'gaussian', inflationMeanPct, returnVolPct, classShocks }
+  }
+  if (kind === 'ar1') {
+    return { type: 'ar1', inflationMeanPct, returnVolPct, phi: 0.3, classShocks }
+  }
+  // fallback
+  return {
+    type: 'historical',
+    mode: 'iid',
+    equityWeightPct,
+    classShocks: !!classShocks,
+  }
+}

package/src/planner/optimizePageChart.ts

@@ -0,0 +1,40 @@
+import type { OptimizedSchedule } from '@retiregolden/engine/strategies/optimizer'
+import type { OptimizePostProcessing } from '../optimize/messages'
+
+export interface OptimizeChartRow {
+  year: number
+  requested: number
+  cleaned: number
+  executed: number
+}
+
+export function buildOptimizeChartRows({
+  schedule,
+  recommendedConversions,
+  postProcessed,
+  candidateWins,
+}: {
+  schedule: OptimizedSchedule | null
+  recommendedConversions: { year: number; amount: number }[]
+  postProcessed: OptimizePostProcessing | null
+  candidateWins: boolean
+}): OptimizeChartRow[] {
+  const rawByYear = new Map(schedule?.conversions.map((c) => [c.year, c.amount]) ?? [])
+  const cleanedByYear = new Map(recommendedConversions.map((c) => [c.year, c.amount]))
+  // A winning candidate's schedule is its exact-ledger execution; the MILP path
+  // reports the cleaned re-run's executed amounts.
+  const executedByYear = candidateWins
+    ? cleanedByYear
+    : new Map(postProcessed?.cleanedExecutionByYear.map((year) => [year.year, year.rothConversion]) ?? [])
+  const years = [...new Set([...rawByYear.keys(), ...cleanedByYear.keys()])].sort((a, b) => a - b)
+  return years.map((year) => ({
+    year,
+    requested: Math.round(rawByYear.get(year) ?? 0),
+    cleaned: Math.round(cleanedByYear.get(year) ?? 0),
+    executed: Math.round(executedByYear.get(year) ?? 0),
+  }))
+}
+
+export function shouldShowRecommendedScheduleBars(candidateWins: boolean, hasExecutionMismatch: boolean): boolean {
+  return candidateWins || hasExecutionMismatch
+}

package/src/planner/optimizePageClaim.ts

@@ -0,0 +1,64 @@
+/**
+ * Claim-age co-optimization helpers for the Optimize page
+ * (optimizer-exact-ledger-convergence Track 1, Step 5). Pure functions so the load-bearing apply contract is unit-testable
+ * without rendering: when the co-optimizer recommends a claim change, the
+ * returned conversion schedule was computed against the CLAIM-PATCHED plan, so
+ * the claim change and the schedule must always be installed together —
+ * conversions applied to the unpatched plan are a different (wrong) plan.
+ */
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+import type { ClaimAgeCoOptimization } from '@retiregolden/engine/projection/optimizePlan'
+
+/** Exact-estate improvement of the joint optimum over the current-claim optimum. */
+export function claimEstateGain(claimAge: ClaimAgeCoOptimization | null): number {
+  if (!claimAge?.winningClaimPatch) return 0
+  return claimAge.jointExactEstate - claimAge.currentClaimExactEstate
+}
+
+/**
+ * The plan the recommendation was actually computed against: the current plan
+ * with the winning claim change installed, or the plan itself when the current
+ * claim ages won (or co-optimization did not run). Monte Carlo and the report
+ * must consume this plan, never the unpatched one.
+ *
+ * ASSUMPTION: a claim patch touches ONLY `incomes`. That mirrors the engine's
+ * capture (`winningPatch = { incomes: patchedPlan.incomes }` in
+ * optimizePlanCoOptimizingClaimAge) and the `winningClaimPatch` wire type, but
+ * the claim generator flows through the general `applyScenarioPatch`, so
+ * nothing at compile time enforces it. If the engine ever widens the patch,
+ * this helper AND `applyOptimizeRecommendation` below must widen with it (or
+ * better: ship the engine's `optimizedPlan` across the worker boundary).
+ */
+export function planWithWinningClaim(plan: Plan, claimAge: ClaimAgeCoOptimization | null): Plan {
+  if (!claimAge?.winningClaimPatch) return plan
+  return { ...plan, incomes: claimAge.winningClaimPatch.incomes }
+}
+
+/**
+ * Install the joint recommendation on a plan draft: the winning claim change
+ * (when one won) and the conversion schedule, atomically. An empty conversions
+ * list leaves the existing conversion strategy in place — that is the correct
+ * joint recommendation when the incumbent schedule holds under the new claim.
+ */
+export function applyOptimizeRecommendation(
+  draft: Plan,
+  args: {
+    claimAge: ClaimAgeCoOptimization | null
+    conversions: { year: number; amount: number }[]
+    mode: 'optimized' | 'manual'
+    nowIso?: string
+  },
+): void {
+  if (args.claimAge?.winningClaimPatch) draft.incomes = args.claimAge.winningClaimPatch.incomes
+  if (args.conversions.length > 0) {
+    draft.strategies.rothConversion =
+      args.mode === 'manual'
+        ? { mode: 'manual', conversions: args.conversions }
+        : {
+            mode: 'optimized',
+            conversions: args.conversions,
+            optimizedAtIso: args.nowIso ?? new Date().toISOString(),
+          }
+  }
+}

package/src/planner/planCompleteness.ts

@@ -0,0 +1,27 @@
+/**
+ * Display-layer completeness: a plan with no income sources and nothing that
+ * can actually fund spending is still being set up, so verdict framing (red
+ * "portfolio depletes") would just read as doom while the user types.
+ * Debts never count as funding (their balance is money owed), and
+ * payment/value account types must carry a positive amount.
+ */
+
+import type { Account, Plan } from '@retiregolden/engine/model/plan'
+
+function accountProvidesFunding(account: Account): boolean {
+  switch (account.type) {
+    case 'debt':
+      return false
+    case 'pension':
+    case 'annuity':
+      return account.monthlyAmount > 0
+    case 'property':
+      return account.value > 0
+    default:
+      return account.balance > 0
+  }
+}
+
+export function isPlanIncomplete(plan: Pick<Plan, 'incomes' | 'accounts'>): boolean {
+  return plan.incomes.length === 0 && !plan.accounts.some(accountProvidesFunding)
+}

package/src/planner/planContextCore.ts

@@ -0,0 +1,26 @@
+/** Context + hook for the plan workspace (separate file keeps fast refresh happy). */
+
+import { createContext, useContext } from 'react'
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+
+export type SaveState = 'loading' | 'saved' | 'saving' | 'dirty' | 'invalid' | 'error'
+
+export interface PlanContextValue {
+  plan: Plan
+  /** Mutate a draft clone of the plan; the result is validated and autosaved. */
+  update: (mutator: (draft: Plan) => void) => void
+  /** Cancel pending autosave so an unmount flush cannot resurrect a deleted demo. */
+  discardPendingSave: () => void
+  saveState: SaveState
+  /** Zod issues for the current (possibly unsaved) state; empty when valid. */
+  issues: string[]
+}
+
+export const PlanCtx = createContext<PlanContextValue | null>(null)
+
+export function usePlan(): PlanContextValue {
+  const v = useContext(PlanCtx)
+  if (!v) throw new Error('usePlan must be used inside <PlanProvider>')
+  return v
+}