@retiregolden/planner-ui 0.1.0

package/src/optimize/runOptimize.ts

@@ -0,0 +1,92 @@
+/**
+ * Executes one optimize request. Shared by the Web Worker entry and the
+ * synchronous fallback (tests / no-Worker environments) so both run the
+ * identical tax stack — federal engine + per-state engine with the plan's flat
+ * rate as an override, matching src/mc/runRequest.ts.
+ */
+
+import { objectivePolicyForPlan } from '@retiregolden/engine/decisions'
+import {
+  optimizePlan,
+  optimizePlanCoOptimizingClaimAge,
+  type ExactLedgerPostProcessing,
+  type OptimizePlanOptions,
+} from '@retiregolden/engine/projection/optimizePlan'
+import { combineTaxCalculators, createFederalTaxCalculator } from '@retiregolden/engine/tax/federalTax'
+import { createStateTaxCalculator } from '@retiregolden/engine/tax/stateTax'
+import type { OptimizePostProcessing, OptimizeRequest, OptimizeResult } from './messages'
+
+function summarizePostProcessing(postProcessed: ExactLedgerPostProcessing | null): OptimizePostProcessing | null {
+  if (!postProcessed) return null
+  return {
+    rawSchedule: postProcessed.rawSchedule,
+    cleanedSchedule: postProcessed.cleanedSchedule,
+    rawValidation: postProcessed.rawValidation,
+    cleanedValidation: postProcessed.cleanedValidation,
+    adjustments: postProcessed.adjustments,
+    stabilized: postProcessed.stabilized,
+    iterationCount: postProcessed.iterationCount,
+    pruneIterationCount: postProcessed.pruneIterationCount,
+    recommendationSchedule: postProcessed.recommendationSchedule,
+    cleanedExecutionByYear: postProcessed.cleanedResult.years.map((year) => ({
+      year: year.year,
+      rothConversion: year.rothConversion,
+    })),
+  }
+}
+
+/**
+ * Production defaults for the optimize pipeline. Exported so the dev-only Owl
+ * parity harness (src/cases/owlParity.ts) measures exactly what the worker
+ * ships — a retune here automatically retunes the parity gate.
+ */
+export const DEFAULT_OPTIMIZE_SEARCH_BUDGET = 96
+export const DEFAULT_OPTIMIZE_CONVERGENCE_ITERATIONS = 6
+
+export async function runOptimizeRequest(
+  req: OptimizeRequest,
+  locateFile?: (file: string) => string,
+): Promise<OptimizeResult> {
+  const taxCalculator = combineTaxCalculators(
+    createFederalTaxCalculator(),
+    createStateTaxCalculator({
+      overridePct: req.plan.assumptions.stateEffectiveTaxPct,
+      localPct: req.plan.assumptions.localIncomeTaxPct,
+    }),
+  )
+  // Phase 4 local search: refine the winning schedules on the exact ledger
+  // under a bounded, deterministic per-seed simulation budget (enough for the
+  // coarse+fine sweeps to also explore the bounded taper-extension years past
+  // the seed schedule); zero or negative disables search entirely (the seed
+  // evaluation would otherwise still cost one simulation).
+  const searchBudget = req.searchSimulationBudget ?? DEFAULT_OPTIMIZE_SEARCH_BUDGET
+  // Exact-ledger convergence loop (Step 1): re-solve against exogenous inputs
+  // recaptured from the incumbent schedule so the recommendation is optimal on
+  // the real projection to tolerance. Bounded iteration cap; the tournament
+  // still prices and gates whatever the loop produces. `≤ 1` disables it.
+  const convergenceIterations = req.convergenceIterations ?? DEFAULT_OPTIMIZE_CONVERGENCE_ITERATIONS
+  const planOptions: OptimizePlanOptions = {
+    startYear: req.startYear,
+    taxCalculator,
+    liquidationRatePct: req.liquidationRatePct,
+    solver: { timeLimitSec: req.timeLimitSec, locateFile },
+    search: searchBudget > 0 ? { maxSimulations: searchBudget } : false,
+    convergence: convergenceIterations > 1 ? { maxIterations: convergenceIterations } : false,
+    // Resolved here (not passed as a function) so the policy survives the
+    // structured-clone worker boundary; floor policies read the plan's bequest target.
+    policy: req.objectivePolicyId ? objectivePolicyForPlan(req.objectivePolicyId, req.plan) : undefined,
+  }
+
+  // Step 5: co-optimize the SS claim age when requested (opt-in; bounded grid).
+  // The returned schedule may assume a claim change reported in `claimAge`.
+  if (req.coOptimizeClaimAge) {
+    const { schedule, postProcessed, tournament, convergence, claimAge } = await optimizePlanCoOptimizingClaimAge(
+      req.plan,
+      planOptions,
+    )
+    return { schedule, postProcessed: summarizePostProcessing(postProcessed), tournament, convergence, claimAge }
+  }
+
+  const { schedule, postProcessed, tournament, convergence } = await optimizePlan(req.plan, planOptions)
+  return { schedule, postProcessed: summarizePostProcessing(postProcessed), tournament, convergence, claimAge: null }
+}

package/src/optimize/runSpendingSolve.ts

@@ -0,0 +1,47 @@
+/**
+ * Executes one sustainable-spending solve. Shared by the Web Worker entry and
+ * the synchronous fallback (tests / no-Worker environments) so both run the
+ * identical tax stack — federal engine + per-state engine with the plan's flat
+ * rate as an override, matching ./runOptimize.ts.
+ */
+
+import { createDecisionContext, solveMaxSustainableSpending, SPENDING_SOLVER_UI_BUDGET } from '@retiregolden/engine/decisions'
+import { combineTaxCalculators, createFederalTaxCalculator } from '@retiregolden/engine/tax/federalTax'
+import { createStateTaxCalculator } from '@retiregolden/engine/tax/stateTax'
+import type { SpendingSolveRequest, SpendingSolveResult } from './spendingMessages'
+
+export function runSpendingSolveRequest(req: SpendingSolveRequest): SpendingSolveResult {
+  const taxCalculator = combineTaxCalculators(
+    createFederalTaxCalculator(),
+    createStateTaxCalculator({
+      overridePct: req.plan.assumptions.stateEffectiveTaxPct,
+      localPct: req.plan.assumptions.localIncomeTaxPct,
+    }),
+  )
+  const ctx = createDecisionContext(req.plan, { startYear: req.startYear, taxCalculator })
+  const estateFloorTodayDollars = req.plan.expenses.bequestTargetDollars ?? 0
+  const solved = solveMaxSustainableSpending(ctx, {
+    maxSimulations: req.maxSimulations ?? SPENDING_SOLVER_UI_BUDGET,
+    estateFloorTodayDollars,
+  })
+  const summary = solved.bestEvaluation?.candidateSummary ?? null
+  return {
+    maxBaseAnnual: solved.maxBaseAnnual,
+    spendingSlackDollars: solved.spendingSlackDollars,
+    currentBaseAnnual: req.plan.expenses.baseAnnual,
+    estateFloorTodayDollars,
+    converged: solved.converged,
+    limitingConstraint: solved.limitingConstraint,
+    simulationCount: solved.simulationCount,
+    diagnostics: solved.diagnostics,
+    evidence: summary
+      ? {
+          endingAfterTaxEstate: summary.endingAfterTaxEstate,
+          endingNetWorth: summary.endingNetWorth,
+          lifetimeTaxesAndPenalties: summary.lifetimeTaxesAndPenalties,
+          depletionYear: solved.bestEvaluation!.candidateResult.depletionYear,
+          endYear: solved.bestEvaluation!.candidateResult.endYear,
+        }
+      : null,
+  }
+}

package/src/optimize/runner.ts

@@ -0,0 +1,21 @@
+/**
+ * Spawns the optimizer in a Web Worker (lazy-loaded only here, so the wasm
+ * chunk is fetched only when Optimize is invoked) and resolves the schedule.
+ * Falls back to a synchronous in-process solve where Worker is unavailable
+ * (tests, very old browsers), mirroring src/mc/pool.ts.
+ */
+
+import type { OptimizeRequest, OptimizeResponse, OptimizeResult } from './messages'
+import { runOptimizeRequest } from './runOptimize'
+import { runWorkerRequest } from '../workers/run'
+
+export function runOptimize(req: OptimizeRequest): Promise<OptimizeResult> {
+  if (typeof Worker === 'undefined') return runOptimizeRequest(req)
+  return runWorkerRequest<OptimizeRequest, OptimizeResponse, OptimizeResult>({
+    request: req,
+    createWorker: () => new Worker(new URL('./optimize.worker.ts', import.meta.url), { type: 'module' }),
+    interpret: (msg) =>
+      msg.type === 'done' ? { kind: 'done', result: msg.result } : { kind: 'error', message: msg.message },
+    errorLabel: 'Optimizer worker failed',
+  })
+}

package/src/optimize/spendingMessages.ts

@@ -0,0 +1,44 @@
+/**
+ * Wire types between the "How much can I spend?" surface and its worker
+ * (sustainable-spending plan, Step 4). Same rules as ./messages.ts: everything
+ * must survive structured clone, so the solver's `bestEvaluation` (which holds
+ * a full ProjectionResult) is summarized into `evidence` before posting.
+ */
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+
+export interface SpendingSolveRequest {
+  plan: Plan
+  startYear: number
+  /** Exact-ledger simulation budget; defaults to SPENDING_SOLVER_UI_BUDGET. */
+  maxSimulations?: number
+}
+
+/** Exact-ledger evidence for the plan run at the solved spending level. */
+export interface SpendingSolveEvidence {
+  endingAfterTaxEstate: number
+  endingNetWorth: number
+  lifetimeTaxesAndPenalties: number
+  depletionYear: number | null
+  endYear: number
+}
+
+export interface SpendingSolveResult {
+  /** Highest feasible annual base spending (today's dollars), or null. */
+  maxBaseAnnual: number | null
+  /** maxBaseAnnual − current base spending (negative ⇒ overspending today). */
+  spendingSlackDollars: number | null
+  /** The plan's own base spending the slack is measured against. */
+  currentBaseAnnual: number
+  /** The bequest target the solve enforced (today's dollars; 0 = none). */
+  estateFloorTodayDollars: number
+  converged: boolean
+  limitingConstraint: 'depletion' | 'estate-floor' | null
+  simulationCount: number
+  diagnostics: string[]
+  evidence: SpendingSolveEvidence | null
+}
+
+export type SpendingSolveResponse =
+  | { type: 'done'; result: SpendingSolveResult }
+  | { type: 'error'; message: string }

package/src/optimize/spendingRunner.ts

@@ -0,0 +1,21 @@
+/**
+ * Spawns the sustainable-spending solver in a Web Worker (lazy-loaded only
+ * here) and resolves the summarized result. Falls back to a synchronous
+ * in-process solve where Worker is unavailable (tests, very old browsers),
+ * mirroring ./runner.ts.
+ */
+
+import type { SpendingSolveRequest, SpendingSolveResponse, SpendingSolveResult } from './spendingMessages'
+import { runSpendingSolveRequest } from './runSpendingSolve'
+import { runWorkerRequest } from '../workers/run'
+
+export function runSpendingSolve(req: SpendingSolveRequest): Promise<SpendingSolveResult> {
+  if (typeof Worker === 'undefined') return Promise.resolve(runSpendingSolveRequest(req))
+  return runWorkerRequest<SpendingSolveRequest, SpendingSolveResponse, SpendingSolveResult>({
+    request: req,
+    createWorker: () => new Worker(new URL('./spendingSolve.worker.ts', import.meta.url), { type: 'module' }),
+    interpret: (msg) =>
+      msg.type === 'done' ? { kind: 'done', result: msg.result } : { kind: 'error', message: msg.message },
+    errorLabel: 'Spending solver worker failed',
+  })
+}

package/src/optimize/spendingSolve.worker.ts

@@ -0,0 +1,18 @@
+/**
+ * Web Worker entry for the sustainable-spending solver: one request per run,
+ * ~25 exact-ledger simulations off the main thread, summarized result posted
+ * back. No wasm — the solver is pure `simulatePlan` bisection.
+ */
+
+import type { SpendingSolveRequest, SpendingSolveResponse } from './spendingMessages'
+import { runSpendingSolveRequest } from './runSpendingSolve'
+
+const post = (msg: SpendingSolveResponse) => (self as unknown as Worker).postMessage(msg)
+
+self.onmessage = (event: MessageEvent<SpendingSolveRequest>) => {
+  try {
+    post({ type: 'done', result: runSpendingSolveRequest(event.data) })
+  } catch (err) {
+    post({ type: 'error', message: err instanceof Error ? err.message : String(err) })
+  }
+}

package/src/planner/AssumptionsCardPage.tsx

@@ -0,0 +1,136 @@
+/**
+ * "Your assumptions" card (trust-and-transparency-layer, step 1): one screen
+ * enumerating every live assumption behind this plan's numbers — economy,
+ * account returns, longevity, law toggles, and the parameter pack — each
+ * tagged user-set / app default / published source, with a copy-export so the
+ * run can be replicated in another tool. This is the direct answer to "why do
+ * different planners give different answers?": they differ here.
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Link } from 'react-router-dom'
+
+import { PARAMETER_PROVENANCE } from '@retiregolden/engine/params'
+import { usePlan } from './planContextCore'
+import { currentStartYear } from './useProjection'
+import {
+  assumptionsExportJson,
+  assumptionsExportText,
+  buildAssumptionsSnapshot,
+  type AssumptionProvenance,
+} from './assumptionsExport'
+
+const PROVENANCE_CHIP: Record<AssumptionProvenance, { label: string; title: string }> = {
+  'user-set': { label: 'You set this', title: 'Entered or changed by you — other tools need this value to match your run.' },
+  'app-default': { label: 'App default', title: "RetireGolden's shipped default — you have not changed it." },
+  'published-source': { label: 'Published source', title: 'Comes from a cited publication (statute, agency figure, or documented dataset).' },
+}
+
+function CopyButton({ label, copiedLabel, text }: { label: string; copiedLabel: string; text: () => string }) {
+  const [state, setState] = useState<'idle' | 'copied' | 'failed'>('idle')
+  const resetTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  useEffect(() => () => clearTimeout(resetTimer.current), [])
+  const flash = (next: 'copied' | 'failed') => {
+    setState(next)
+    clearTimeout(resetTimer.current)
+    resetTimer.current = setTimeout(() => setState('idle'), 2500)
+  }
+  const copy = () => {
+    // The Clipboard API is absent in insecure contexts and some browsers; say
+    // so instead of throwing (or faking success).
+    if (typeof navigator === 'undefined' || !navigator.clipboard?.writeText) {
+      flash('failed')
+      return
+    }
+    navigator.clipboard
+      .writeText(text())
+      .then(() => flash('copied'))
+      .catch(() => flash('failed'))
+  }
+  return (
+    <button type="button" className="btn btn-secondary btn-small" onClick={copy}>
+      {state === 'copied' ? copiedLabel : state === 'failed' ? 'Clipboard unavailable — copy manually' : label}
+    </button>
+  )
+}
+
+export function AssumptionsCardPage() {
+  const { plan } = usePlan()
+  const startYear = currentStartYear()
+  const snapshot = useMemo(() => buildAssumptionsSnapshot(plan, startYear), [plan, startYear])
+  const sourceById = useMemo(() => new Map(PARAMETER_PROVENANCE.map((s) => [s.id, s])), [])
+
+  return (
+    <section>
+      <div className="card">
+        <h2>Your assumptions, on one card</h2>
+        <p className="card-hint">
+          Every number RetireGolden shows follows from the assumptions below — the same plan run through tools with
+          different assumptions (or hidden ones) will disagree. Each value is tagged with where it comes from, and the
+          copy buttons export the whole card so you can hand your exact assumptions to another tool or a professional
+          and see where the inputs differ. (The rest of the plan — incomes, expenses, goals — travels in a plan backup
+          from the planner home.)
+        </p>
+        <div style={{ display: 'flex', gap: '0.75rem', flexWrap: 'wrap' }}>
+          <CopyButton label="Copy as text" copiedLabel="Copied ✓" text={() => assumptionsExportText(snapshot)} />
+          <CopyButton label="Copy as JSON" copiedLabel="Copied ✓" text={() => assumptionsExportJson(snapshot)} />
+        </div>
+        <p className="field-hint" style={{ marginTop: '0.5rem' }}>
+          Applies to the {snapshot.packYear} tax year · parameter figures compiled {snapshot.dataAsOf} ·{' '}
+          <Link to="/disclaimer">full source list</Link> · <Link to="/how-tested">how RetireGolden is tested</Link>
+        </p>
+      </div>
+
+      {snapshot.groups.map((group) => (
+        <div className="card" key={group.id}>
+          <h3 style={{ marginTop: 0 }}>{group.label}</h3>
+          <table className="provenance-table">
+            <thead>
+              <tr>
+                <th scope="col">Assumption</th>
+                <th scope="col">Where it comes from</th>
+              </tr>
+            </thead>
+            <tbody>
+              {group.rows.map((row) => {
+                const source = row.sourceId ? sourceById.get(row.sourceId) : undefined
+                const chip = PROVENANCE_CHIP[row.provenance]
+                return (
+                  <tr key={row.id}>
+                    <th scope="row">
+                      <span className="provenance-label">{row.label}</span>
+                      <span className="provenance-figures muted small">{row.value}</span>
+                    </th>
+                    <td>
+                      <span className="muted small" title={chip.title}>
+                        {chip.label}
+                      </span>
+                      {source ? (
+                        <>
+                          {' · '}
+                          <a href={source.url} target="_blank" rel="noopener noreferrer">
+                            {source.publisher} ↗
+                          </a>
+                        </>
+                      ) : null}
+                    </td>
+                  </tr>
+                )
+              })}
+            </tbody>
+          </table>
+        </div>
+      ))}
+
+      <div className="card">
+        <p className="field-hint" style={{ margin: 0 }}>
+          Monte Carlo results also depend on the market model, path count, and seed chosen on the{' '}
+          <Link to={`/plan/${plan.id}/monte-carlo`}>Monte Carlo page</Link> — your expected returns and inflation above
+          stay the center of every model's distribution. To change anything on this card, use{' '}
+          <Link to={`/plan/${plan.id}/assumptions`}>Assumptions</Link>, <Link to={`/plan/${plan.id}/accounts`}>Accounts</Link>,
+          or <Link to={`/plan/${plan.id}/household`}>Household</Link>.
+        </p>
+      </div>
+    </section>
+  )
+}

package/src/planner/BucketLensCard.tsx

@@ -0,0 +1,114 @@
+/**
+ * Bucket reporting lens card (spending-paths & SWR-lenses plan, Goal 5): an
+ * opt-in re-reading of the same ledger balances as time-segmented buckets —
+ * "the next N years of net spending", then growth. Reporting only: nothing
+ * feeds back into the engine, and the honest evidence note stays attached
+ * because the bucket literature (Estrada; Kitces) finds no systematic benefit
+ * over total-return investing — the comfort is the product, not extra return.
+ */
+
+import { useMemo, useState } from 'react'
+import {
+  Area,
+  AreaChart,
+  CartesianGrid,
+  Legend,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts'
+
+import type { ProjectionResult } from '@retiregolden/engine/projection/types'
+import { bucketLens, BUCKET_PRESETS } from './bucketLens'
+import { chartTooltipStyle } from './chartStyle'
+import { frameH } from './chartFrame'
+import { fmtMoney, fmtMoneyCompact } from './format'
+import { SelectField } from './fields'
+
+const BUCKET_COLORS = ['var(--chart-5)', 'var(--chart-2)', 'var(--chart-1)']
+
+export function BucketLensCard({
+  result,
+  adj,
+}: {
+  result: ProjectionResult
+  /** Dollar-mode adapter from ResultsPage: (year, nominal) → displayed dollars. */
+  adj: (year: number, v: number) => number
+}) {
+  const [presetId, setPresetId] = useState<'off' | 'three' | 'two'>('off')
+  const preset = BUCKET_PRESETS.find((p) => p.id === presetId) ?? null
+
+  const rows = useMemo(() => {
+    if (!preset) return []
+    return bucketLens(result, preset.spans).map((row) => ({
+      year: row.year,
+      ...Object.fromEntries(row.buckets.map((b, i) => [`b${i}`, adj(row.year, b)])),
+    }))
+  }, [result, preset, adj])
+
+  return (
+    <div className="chart-card">
+      <h2>Bucket view (a reporting lens)</h2>
+      <p className="card-hint">
+        Many retirees think in buckets: a couple of years of spending in cash, several more in stable assets, the
+        rest invested for growth. This view reads the same projected balances that way — bucket 1 holds the next
+        years of <em>net</em> spending (spending plus taxes, minus that year&apos;s income), and so on — without
+        changing how the plan is invested or simulated. The buckets sum exactly to the investable total every year.
+      </p>
+      <div className="form-grid">
+        <SelectField
+          label="Bucket definition"
+          help="Purely presentational: pick how the projected balances are segmented. Bucket studies (Estrada; Kitces) find no systematic return or safety benefit from actually managing money as buckets versus a rebalanced total-return portfolio — the value is legibility, so RetireGolden reports buckets but never invests by them."
+          value={presetId}
+          options={[
+            { value: 'off', label: 'Off' },
+            ...BUCKET_PRESETS.map((p) => ({ value: p.id, label: p.label })),
+          ]}
+          onCommit={(v) => setPresetId(v as 'off' | 'three' | 'two')}
+        />
+      </div>
+      {preset ? (
+        <>
+          <div className="chart-frame" style={frameH(280)}>
+            <ResponsiveContainer width="100%" height="100%">
+              <AreaChart
+                data={rows}
+                margin={{ left: 12, right: 8, top: 8 }}
+                aria-label="Bucket view: projected balances segmented into spending buckets, year by year"
+              >
+                <CartesianGrid stroke="var(--border)" strokeDasharray="3 3" />
+                <XAxis dataKey="year" interval="equidistantPreserveStart" tick={{ fill: 'var(--muted)', fontSize: 12 }} />
+                <YAxis tickFormatter={fmtMoneyCompact} tick={{ fill: 'var(--muted)', fontSize: 12 }} width={70} />
+                <Legend />
+                {preset.bucketLabels.map((label, i) => (
+                  <Area
+                    key={label}
+                    dataKey={`b${i}`}
+                    stackId="buckets"
+                    name={label}
+                    stroke={BUCKET_COLORS[i % BUCKET_COLORS.length]}
+                    fill={BUCKET_COLORS[i % BUCKET_COLORS.length]}
+                    fillOpacity={0.55}
+                  />
+                ))}
+                <Tooltip
+                  formatter={(v: unknown) => fmtMoney(Number(v))}
+                  contentStyle={chartTooltipStyle}
+                  wrapperStyle={{ zIndex: 2 }}
+                />
+              </AreaChart>
+            </ResponsiveContainer>
+          </div>
+          <p className="field-hint" style={{ marginTop: '0.5rem' }}>
+            Honest labeling: the research record (Estrada&apos;s bucket studies; Kitces) finds bucket{' '}
+            <em>management</em> adds no systematic benefit over a rebalanced total-return portfolio — refilling rules
+            are market-timing in disguise. RetireGolden therefore simulates your plan total-return and offers buckets
+            only as this view. Years where income covers spending show an empty bucket 1; near the end of the plan
+            the leading buckets drain because fewer spending years remain.
+          </p>
+        </>
+      ) : null}
+    </div>
+  )
+}