@retiregolden/planner-ui 0.1.0

package/src/mc/messages.ts

@@ -0,0 +1,118 @@
+/**
+ * Wire types between the Monte Carlo pool and its workers (roadmap V4).
+ * Everything here must survive structured clone: plain objects, arrays, and
+ * Float64Array only.
+ */
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+import type { AnnuitizationSweep } from '@retiregolden/engine/decisions/annuitization'
+import type { StochasticFrontierPoint } from '@retiregolden/engine/montecarlo/frontiers'
+import type { HistoricalStressSuiteKind } from '@retiregolden/engine/montecarlo/historicalSuites'
+import type { LtcShockParams } from '@retiregolden/engine/montecarlo/ltcShock'
+import type { MarketModelConfig } from '@retiregolden/engine/montecarlo/marketModels'
+import type { RiskBasedGuardrailSolution } from '@retiregolden/engine/montecarlo/riskBasedGuardrails'
+import type { MonteCarloPathsResult } from '@retiregolden/engine/montecarlo/run'
+
+export interface McWorkerRequest {
+  kind: 'monteCarlo'
+  plan: Plan
+  startYear: number
+  seed: number
+  model: MarketModelConfig
+  pathCount: number
+  /** Global index of this worker's first path (keeps seeding partition-independent). */
+  firstPathIndex: number
+  /** Post a progress message every N completed paths. */
+  progressEvery: number
+  /** Sample lifespans from the mortality table per path (roadmap V6). */
+  stochasticLongevity?: boolean
+  /** Probabilistic LTC care episode per path (roadmap V6); omitted/null = off. */
+  ltcShock?: LtcShockParams | null
+}
+
+export interface FrontierWorkerRequest {
+  kind: 'frontiers'
+  plan: Plan
+  startYear: number
+  seed: number
+  model: MarketModelConfig
+  pathCount: number
+  stochasticLongevity?: boolean
+  ltcShock?: LtcShockParams | null
+}
+
+export interface FrontierWorkerResult {
+  spending: StochasticFrontierPoint[]
+  retirement: StochasticFrontierPoint[]
+  /** Annuitization sweep (annuity-pension-and-home-equity, step 2). */
+  annuitization: AnnuitizationSweep
+}
+
+export interface RiskBasedWorkerRequest {
+  kind: 'riskBasedGuardrails'
+  plan: Plan
+  startYear: number
+  seed: number
+  model: MarketModelConfig
+  pathCount: number
+  stochasticLongevity?: boolean
+  ltcShock?: LtcShockParams | null
+}
+
+export interface HistoricalWorkerRequest {
+  kind: 'historicalSuites'
+  plan: Plan
+  startYear: number
+  equityWeightPct: number
+  classShocks?: boolean
+  worstWindowCount?: number
+}
+
+export interface HistoricalStressWindowView {
+  suite: HistoricalStressSuiteKind
+  label: string
+  startHistoricalYear: number
+  endHistoricalYear: number
+  reversed: boolean
+  success: boolean
+  projection: { depletionYear: number | null }
+  summary: { endingAfterTaxEstate: number }
+  totalShortfall: number
+  totalRequiredShortfall: number
+  totalTargetShortfall: number
+}
+
+export interface HistoricalStressSuiteView {
+  kind: HistoricalStressSuiteKind
+  name: string
+  windowLengthYears: number
+  worstByEndingAfterTaxEstate: HistoricalStressWindowView[]
+  worstByTotalShortfall: HistoricalStressWindowView[]
+}
+
+export interface HistoricalStressSuiteViewResult {
+  windowLengthYears: number
+  suites: HistoricalStressSuiteView[]
+}
+
+export type WorkerRequest = McWorkerRequest | FrontierWorkerRequest | HistoricalWorkerRequest | RiskBasedWorkerRequest
+
+export type McWorkerResponse =
+  | { type: 'progress'; completed: number }
+  | { type: 'done'; result: MonteCarloPathsResult }
+  | { type: 'error'; message: string }
+
+export type FrontierWorkerResponse =
+  | { type: 'frontiersDone'; result: FrontierWorkerResult }
+  | { type: 'error'; message: string }
+
+export type HistoricalWorkerResponse =
+  | { type: 'historicalSuitesDone'; result: HistoricalStressSuiteViewResult }
+  | { type: 'error'; message: string }
+
+export type RiskBasedWorkerResponse =
+  | { type: 'progress'; completed: number }
+  | { type: 'riskBasedDone'; result: RiskBasedGuardrailSolution }
+  | { type: 'error'; message: string }
+
+export type WorkerResponse = McWorkerResponse | FrontierWorkerResponse | HistoricalWorkerResponse | RiskBasedWorkerResponse

package/src/mc/monteCarlo.worker.ts

@@ -0,0 +1,44 @@
+/**
+ * Web Worker entry for Monte Carlo paths (roadmap V4). One request per
+ * worker run: simulate the assigned slice of paths, stream progress, post
+ * the reduced per-path results back (Float64Array buffers transferred, not
+ * copied).
+ */
+
+import type { WorkerRequest, WorkerResponse } from './messages'
+import {
+  runFrontierRequest,
+  runHistoricalStressSuiteRequest,
+  runMcRequest,
+  runRiskBasedGuardrailRequest,
+} from './runRequest'
+
+const post = (msg: WorkerResponse, transfer: Transferable[] = []) =>
+  (self as unknown as Worker).postMessage(msg, transfer)
+
+self.onmessage = (event: MessageEvent<WorkerRequest>) => {
+  const req = event.data
+  try {
+    if (req.kind === 'frontiers') {
+      post({ type: 'frontiersDone', result: runFrontierRequest(req) })
+      return
+    }
+    if (req.kind === 'historicalSuites') {
+      post({ type: 'historicalSuitesDone', result: runHistoricalStressSuiteRequest(req) })
+      return
+    }
+    if (req.kind === 'riskBasedGuardrails') {
+      post({ type: 'riskBasedDone', result: runRiskBasedGuardrailRequest(req, (completed) => post({ type: 'progress', completed })) })
+      return
+    }
+    const result = runMcRequest(req, (completed) => {
+      if (completed % req.progressEvery === 0) post({ type: 'progress', completed })
+    })
+    post(
+      { type: 'done', result },
+      result.paths.map((p) => p.investableByYear.buffer),
+    )
+  } catch (err) {
+    post({ type: 'error', message: err instanceof Error ? err.message : String(err) })
+  }
+}

package/src/mc/pool.ts

@@ -0,0 +1,267 @@
+/**
+ * Worker-pool Monte Carlo runner (roadmap V4, feature catalog §11).
+ *
+ * Splits the requested paths across a pool of Web Workers (one per core by
+ * default, capped at 8) and merges the results. Per-path seeds derive from
+ * (seed, globalPathIndex) inside the engine, so the outcome is identical for
+ * any worker count — including the synchronous fallback used where Worker is
+ * unavailable (tests, very old browsers).
+ */
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+import type { LtcShockParams } from '@retiregolden/engine/montecarlo/ltcShock'
+import type { MarketModelConfig } from '@retiregolden/engine/montecarlo/marketModels'
+import {
+  aggregateMonteCarlo,
+  mergePathResults,
+  type MonteCarloPathsResult,
+  type MonteCarloSummary,
+} from '@retiregolden/engine/montecarlo/run'
+import type { RiskBasedGuardrailSolution } from '@retiregolden/engine/montecarlo/riskBasedGuardrails'
+import type {
+  FrontierWorkerRequest,
+  FrontierWorkerResponse,
+  FrontierWorkerResult,
+  HistoricalStressSuiteViewResult,
+  HistoricalWorkerRequest,
+  HistoricalWorkerResponse,
+  McWorkerRequest,
+  McWorkerResponse,
+  RiskBasedWorkerRequest,
+  RiskBasedWorkerResponse,
+} from './messages'
+import {
+  runFrontierRequest,
+  runHistoricalStressSuiteRequest,
+  runMcRequest,
+  runRiskBasedGuardrailRequest,
+} from './runRequest'
+import { runWorkerRequest } from '../workers/run'
+
+export interface MonteCarloRunOptions {
+  startYear: number
+  /** 1,000 default; 10,000 on demand. */
+  pathCount: number
+  seed: number
+  model: MarketModelConfig
+  /** Default: hardwareConcurrency − 1, clamped to [1, 8]. */
+  workerCount?: number
+  /** Sample lifespans from the mortality table per path (roadmap V6). */
+  stochasticLongevity?: boolean
+  /** Probabilistic LTC care episode per path (roadmap V6); omitted/null = off. */
+  ltcShock?: LtcShockParams | null
+  onProgress?: (completedPaths: number, totalPaths: number) => void
+}
+
+export const DEFAULT_PATH_COUNT = 1000
+export const ON_DEMAND_PATH_COUNT = 10_000
+
+function defaultWorkerCount(): number {
+  const cores = typeof navigator !== 'undefined' ? (navigator.hardwareConcurrency ?? 4) : 4
+  return Math.max(1, Math.min(8, cores - 1))
+}
+
+function makeRequest(plan: Plan, opts: MonteCarloRunOptions, firstPathIndex: number, pathCount: number): McWorkerRequest {
+  return {
+    kind: 'monteCarlo',
+    plan,
+    startYear: opts.startYear,
+    seed: opts.seed,
+    model: opts.model,
+    pathCount,
+    firstPathIndex,
+    progressEvery: Math.max(1, Math.floor(opts.pathCount / 100)),
+    stochasticLongevity: opts.stochasticLongevity,
+    ltcShock: opts.ltcShock,
+  }
+}
+
+export interface StochasticFrontierRunOptions {
+  startYear: number
+  pathCount: number
+  seed: number
+  model: MarketModelConfig
+  stochasticLongevity?: boolean
+  ltcShock?: LtcShockParams | null
+}
+
+export interface HistoricalStressSuiteRunOptions {
+  startYear: number
+  equityWeightPct: number
+  classShocks?: boolean
+  worstWindowCount?: number
+}
+
+export type { HistoricalStressSuiteViewResult } from './messages'
+
+function runInWorker(
+  req: McWorkerRequest,
+  onProgress: (workerCompleted: number) => void,
+  onSpawn?: (worker: Worker) => void,
+): Promise<MonteCarloPathsResult> {
+  return runWorkerRequest<McWorkerRequest, McWorkerResponse, MonteCarloPathsResult>({
+    request: req,
+    createWorker: () => new Worker(new URL('./monteCarlo.worker.ts', import.meta.url), { type: 'module' }),
+    interpret: (msg) => {
+      if (msg.type === 'progress') {
+        onProgress(msg.completed)
+        return { kind: 'progress' }
+      }
+      if (msg.type === 'done') return { kind: 'done', result: msg.result }
+      return { kind: 'error', message: msg.message }
+    },
+    errorLabel: 'Monte Carlo worker failed',
+    onSpawn,
+  })
+}
+
+function runFrontiersInWorker(req: FrontierWorkerRequest): Promise<FrontierWorkerResult> {
+  return runWorkerRequest<FrontierWorkerRequest, FrontierWorkerResponse, FrontierWorkerResult>({
+    request: req,
+    createWorker: () => new Worker(new URL('./monteCarlo.worker.ts', import.meta.url), { type: 'module' }),
+    interpret: (msg) =>
+      msg.type === 'frontiersDone' ? { kind: 'done', result: msg.result } : { kind: 'error', message: msg.message },
+    errorLabel: 'Frontier worker failed',
+  })
+}
+
+function runHistoricalSuitesInWorker(req: HistoricalWorkerRequest): Promise<HistoricalStressSuiteViewResult> {
+  return runWorkerRequest<HistoricalWorkerRequest, HistoricalWorkerResponse, HistoricalStressSuiteViewResult>({
+    request: req,
+    createWorker: () => new Worker(new URL('./monteCarlo.worker.ts', import.meta.url), { type: 'module' }),
+    interpret: (msg) =>
+      msg.type === 'historicalSuitesDone'
+        ? { kind: 'done', result: msg.result }
+        : { kind: 'error', message: msg.message },
+    errorLabel: 'Historical stress worker failed',
+  })
+}
+
+/** Run the full Monte Carlo and aggregate it. Reproducible per (plan, seed, model). */
+export async function runMonteCarlo(plan: Plan, opts: MonteCarloRunOptions): Promise<MonteCarloSummary> {
+  const total = opts.pathCount
+  if (typeof Worker === 'undefined') {
+    const result = runMcRequest(makeRequest(plan, opts, 0, total), (completed) => opts.onProgress?.(completed, total))
+    return aggregateMonteCarlo(result)
+  }
+
+  const workerCount = Math.max(1, Math.min(opts.workerCount ?? defaultWorkerCount(), total))
+  const base = Math.floor(total / workerCount)
+  const extra = total % workerCount
+  const completedByWorker = new Array<number>(workerCount).fill(0)
+  const reportProgress = () => {
+    opts.onProgress?.(
+      completedByWorker.reduce((a, b) => a + b, 0),
+      total,
+    )
+  }
+
+  const jobs: Promise<MonteCarloPathsResult>[] = []
+  const liveWorkers: Worker[] = []
+  let firstPathIndex = 0
+  for (let w = 0; w < workerCount; w++) {
+    const slice = base + (w < extra ? 1 : 0)
+    const req = makeRequest(plan, opts, firstPathIndex, slice)
+    firstPathIndex += slice
+    const workerIndex = w
+    jobs.push(
+      runInWorker(
+        req,
+        (completed) => {
+          completedByWorker[workerIndex] = completed
+          reportProgress()
+        },
+        (worker) => liveWorkers.push(worker),
+      ),
+    )
+  }
+  let parts: MonteCarloPathsResult[]
+  try {
+    parts = await Promise.all(jobs)
+  } catch (error) {
+    // One job failed: stop the siblings instead of letting them burn CPU on a
+    // run whose result will be discarded (terminate is a no-op once settled).
+    for (const worker of liveWorkers) worker.terminate()
+    // The killed siblings' promises still reject (their onerror fires after
+    // terminate); swallow those so only this rethrow surfaces.
+    for (const job of jobs) job.catch(() => {})
+    throw error
+  }
+  opts.onProgress?.(total, total)
+  return aggregateMonteCarlo(mergePathResults(parts))
+}
+
+export interface RiskBasedGuardrailRunOptions {
+  startYear: number
+  pathCount: number
+  seed: number
+  model: MarketModelConfig
+  stochasticLongevity?: boolean
+  ltcShock?: LtcShockParams | null
+}
+
+/**
+ * Solve the risk-based guardrail thresholds (dollar balance levels matching the
+ * plan's target success band) on a single worker. Deterministic per
+ * (plan, seed, model, pathCount).
+ */
+export async function runRiskBasedGuardrailSolve(
+  plan: Plan,
+  opts: RiskBasedGuardrailRunOptions,
+): Promise<RiskBasedGuardrailSolution> {
+  const req: RiskBasedWorkerRequest = {
+    kind: 'riskBasedGuardrails',
+    plan,
+    startYear: opts.startYear,
+    seed: opts.seed,
+    model: opts.model,
+    pathCount: opts.pathCount,
+    stochasticLongevity: opts.stochasticLongevity,
+    ltcShock: opts.ltcShock,
+  }
+  if (typeof Worker === 'undefined') return runRiskBasedGuardrailRequest(req)
+  return runWorkerRequest<RiskBasedWorkerRequest, RiskBasedWorkerResponse, RiskBasedGuardrailSolution>({
+    request: req,
+    createWorker: () => new Worker(new URL('./monteCarlo.worker.ts', import.meta.url), { type: 'module' }),
+    interpret: (msg) => {
+      if (msg.type === 'progress') return { kind: 'progress' }
+      if (msg.type === 'riskBasedDone') return { kind: 'done', result: msg.result }
+      return { kind: 'error', message: msg.message }
+    },
+    errorLabel: 'Risk-based guardrail solver failed',
+  })
+}
+
+export async function runStochasticFrontiers(
+  plan: Plan,
+  opts: StochasticFrontierRunOptions,
+): Promise<FrontierWorkerResult> {
+  const req: FrontierWorkerRequest = {
+    kind: 'frontiers',
+    plan,
+    startYear: opts.startYear,
+    seed: opts.seed,
+    model: opts.model,
+    pathCount: opts.pathCount,
+    stochasticLongevity: opts.stochasticLongevity,
+    ltcShock: opts.ltcShock,
+  }
+  if (typeof Worker === 'undefined') return runFrontierRequest(req)
+  return runFrontiersInWorker(req)
+}
+
+export async function runHistoricalStressSuiteViews(
+  plan: Plan,
+  opts: HistoricalStressSuiteRunOptions,
+): Promise<HistoricalStressSuiteViewResult> {
+  const req: HistoricalWorkerRequest = {
+    kind: 'historicalSuites',
+    plan,
+    startYear: opts.startYear,
+    equityWeightPct: opts.equityWeightPct,
+    classShocks: opts.classShocks,
+    worstWindowCount: opts.worstWindowCount,
+  }
+  if (typeof Worker === 'undefined') return runHistoricalStressSuiteRequest(req)
+  return runHistoricalSuitesInWorker(req)
+}

package/src/mc/runRequest.ts

@@ -0,0 +1,125 @@
+/**
+ * Executes one Monte Carlo work unit. Shared by the Web Worker entry and the
+ * pool's synchronous fallback so both paths run the identical tax stack:
+ * the federal engine plus the per-state engine (with the plan's flat rate as
+ * an override).
+ */
+
+import type { Plan } from '@retiregolden/engine/model/plan'
+import { buildAnnuitizationSweep } from '@retiregolden/engine/decisions/annuitization'
+import { buildRetirementAgeSuccessFrontier, buildSpendingSuccessFrontier } from '@retiregolden/engine/montecarlo/frontiers'
+import {
+  runHistoricalStressSuites,
+  type HistoricalStressWindow,
+} from '@retiregolden/engine/montecarlo/historicalSuites'
+import { createMarketModel } from '@retiregolden/engine/montecarlo/marketModels'
+import {
+  solveRiskBasedGuardrails,
+  type RiskBasedGuardrailSolution,
+} from '@retiregolden/engine/montecarlo/riskBasedGuardrails'
+import { runMonteCarloPaths, type MonteCarloPathsResult } from '@retiregolden/engine/montecarlo/run'
+import { combineTaxCalculators, createFederalTaxCalculator } from '@retiregolden/engine/tax/federalTax'
+import { createStateTaxCalculator } from '@retiregolden/engine/tax/stateTax'
+import type {
+  FrontierWorkerRequest,
+  FrontierWorkerResult,
+  HistoricalStressSuiteViewResult,
+  HistoricalStressWindowView,
+  HistoricalWorkerRequest,
+  McWorkerRequest,
+  RiskBasedWorkerRequest,
+} from './messages'
+
+function taxCalculatorForPlan(plan: Plan) {
+  return combineTaxCalculators(
+    createFederalTaxCalculator(),
+    createStateTaxCalculator({
+      overridePct: plan.assumptions.stateEffectiveTaxPct,
+      localPct: plan.assumptions.localIncomeTaxPct,
+    }),
+  )
+}
+
+export function runMcRequest(req: McWorkerRequest, onPathDone?: (completed: number) => void): MonteCarloPathsResult {
+  const taxCalculator = taxCalculatorForPlan(req.plan)
+  return runMonteCarloPaths(req.plan, {
+    startYear: req.startYear,
+    taxCalculator,
+    model: createMarketModel(req.model),
+    seed: req.seed,
+    pathCount: req.pathCount,
+    firstPathIndex: req.firstPathIndex,
+    stochasticLongevity: req.stochasticLongevity,
+    ltcShock: req.ltcShock,
+    onPathDone,
+  })
+}
+
+export function runRiskBasedGuardrailRequest(
+  req: RiskBasedWorkerRequest,
+  onProbeDone?: (completed: number, total: number) => void,
+): RiskBasedGuardrailSolution {
+  return solveRiskBasedGuardrails(req.plan, {
+    startYear: req.startYear,
+    taxCalculator: taxCalculatorForPlan(req.plan),
+    model: req.model,
+    pathCount: req.pathCount,
+    seed: req.seed,
+    stochasticLongevity: req.stochasticLongevity,
+    ltcShock: req.ltcShock,
+    onProbeDone,
+  })
+}
+
+export function runFrontierRequest(req: FrontierWorkerRequest): FrontierWorkerResult {
+  const opts = {
+    startYear: req.startYear,
+    taxCalculator: taxCalculatorForPlan(req.plan),
+    model: req.model,
+    pathCount: req.pathCount,
+    seed: req.seed,
+    stochasticLongevity: req.stochasticLongevity,
+    ltcShock: req.ltcShock,
+  }
+  return {
+    spending: buildSpendingSuccessFrontier(req.plan, opts),
+    retirement: buildRetirementAgeSuccessFrontier(req.plan, opts),
+    annuitization: buildAnnuitizationSweep(req.plan, opts),
+  }
+}
+
+function windowView(window: HistoricalStressWindow): HistoricalStressWindowView {
+  return {
+    suite: window.suite,
+    label: window.label,
+    startHistoricalYear: window.startHistoricalYear,
+    endHistoricalYear: window.endHistoricalYear,
+    reversed: window.reversed,
+    success: window.success,
+    projection: { depletionYear: window.projection.depletionYear },
+    summary: { endingAfterTaxEstate: window.summary.endingAfterTaxEstate },
+    totalShortfall: window.totalShortfall,
+    totalRequiredShortfall: window.totalRequiredShortfall,
+    totalTargetShortfall: window.totalTargetShortfall,
+  }
+}
+
+export function runHistoricalStressSuiteRequest(req: HistoricalWorkerRequest): HistoricalStressSuiteViewResult {
+  const result = runHistoricalStressSuites(req.plan, {
+    startYear: req.startYear,
+    taxCalculator: taxCalculatorForPlan(req.plan),
+    equityWeightPct: req.equityWeightPct,
+    classShocks: req.classShocks,
+    worstWindowCount: req.worstWindowCount,
+  })
+  return {
+    windowLengthYears: result.windowLengthYears,
+    suites: result.suites.map((suite) => ({
+      kind: suite.kind,
+      name: suite.name,
+      windowLengthYears: suite.windowLengthYears,
+      worstByEndingAfterTaxEstate: suite.worstByEndingAfterTaxEstate.map(windowView),
+      worstByTotalShortfall: suite.worstByTotalShortfall.map(windowView),
+    })),
+  }
+}

package/src/optimize/messages.ts

@@ -0,0 +1,84 @@
+/**
+ * Wire types between the Optimize UI and its worker (roadmap V8). Everything
+ * here must survive structured clone — note the tax calculator is NOT passed
+ * (it's a closure); the worker rebuilds the standard stack from the plan, just
+ * like the Monte Carlo worker (see src/mc/runRequest.ts).
+ */
+
+import type { ObjectivePolicyId } from '@retiregolden/engine/decisions'
+import type { Plan } from '@retiregolden/engine/model/plan'
+import type {
+  ClaimAgeCoOptimization,
+  ExactLedgerConvergenceDiagnostics,
+  ExactLedgerRecommendationSchedule,
+  ExactLedgerScheduleAdjustment,
+  ExactLedgerTournament,
+  ExactLedgerValidation,
+} from '@retiregolden/engine/projection/optimizePlan'
+import type { OptimizedSchedule } from '@retiregolden/engine/strategies/optimizer'
+
+export interface OptimizeRequest {
+  plan: Plan
+  startYear: number
+  /** Haircut on leftover traditional; defaults to the plan's heirTaxRatePct. */
+  liquidationRatePct?: number
+  /** HiGHS time limit (seconds). */
+  timeLimitSec?: number
+  /**
+   * Exact-ledger local-search budget for refining winning schedules. Omitted =
+   * default 96 simulations. This is a PER-SEED budget: search refines the top
+   * two candidates (and a winning MILP schedule), so total search simulations
+   * can reach ~2–3× this value. 0 or negative disables search.
+   */
+  searchSimulationBudget?: number
+  /**
+   * Objective policy the tournament ranks by. Omitted = `max-after-tax-estate`
+   * (the original behavior). Floor-style policies pick up the plan's bequest
+   * target inside the worker (`objectivePolicyForPlan`).
+   */
+  objectivePolicyId?: ObjectivePolicyId
+  /**
+   * Exact-ledger convergence-loop iteration cap (optimizer-exact-ledger-convergence Track 1, Step 1).
+   * Omitted = worker default; `≤ 1` disables the loop (single solve = the
+   * pre-convergence schedule).
+   */
+  convergenceIterations?: number
+  /**
+   * Co-optimize the SS claim age with the conversion optimum
+   * (optimizer-exact-ledger-convergence Track 1, Step 5). Off by default: it runs a bounded alternate-minimization over the
+   * claim grid (a small multiple of a single optimize) and can recommend a claim
+   * change alongside the schedule, so the caller must surface `claimAge` when on.
+   */
+  coOptimizeClaimAge?: boolean
+}
+
+export interface OptimizeResult {
+  schedule: OptimizedSchedule
+  postProcessed: OptimizePostProcessing | null
+  /** Bounded simple-candidate tournament; contains no ProjectionResult, so it is structured-clone safe as-is. */
+  tournament: ExactLedgerTournament
+  /** Convergence-loop diagnostics (Step 1); plain scalars, structured-clone safe. */
+  convergence: ExactLedgerConvergenceDiagnostics
+  /**
+   * Claim-age co-optimization diagnostics (Step 5); null unless requested. The
+   * `winningClaimPatch` (a plain incomes array) is structured-clone safe.
+   */
+  claimAge: ClaimAgeCoOptimization | null
+}
+
+export interface OptimizePostProcessing {
+  rawSchedule: OptimizedSchedule
+  cleanedSchedule: OptimizedSchedule
+  rawValidation: ExactLedgerValidation
+  cleanedValidation: ExactLedgerValidation
+  adjustments: ExactLedgerScheduleAdjustment[]
+  stabilized: boolean
+  iterationCount: number
+  pruneIterationCount: number
+  recommendationSchedule: ExactLedgerRecommendationSchedule
+  cleanedExecutionByYear: { year: number; rothConversion: number }[]
+}
+
+export type OptimizeResponse =
+  | { type: 'done'; result: OptimizeResult }
+  | { type: 'error'; message: string }

package/src/optimize/optimize.worker.ts

@@ -0,0 +1,29 @@
+/**
+ * Web Worker entry for the V8 optimizer (roadmap V8). One request per run:
+ * solve the plan's conversion MILP off the main thread and post the schedule
+ * back. HiGHS-WASM is loaded lazily inside the worker — the ~3 MB wasm is
+ * emitted as a separate Vite asset (`?url`) and only fetched when Optimize is
+ * actually invoked, never in the main bundle.
+ */
+
+// `highs/runtime` is the package's exported alias for build/highs.wasm; `?url`
+// makes Vite emit it as a separate asset fetched lazily by the worker.
+import wasmUrl from 'highs/runtime?url'
+import type { OptimizeRequest, OptimizeResponse } from './messages'
+import { runOptimizeRequest } from './runOptimize'
+
+// Deployment marker: keeps the hashed worker asset moving when worker-level
+// serving headers need to be refreshed through immutable CDN caches.
+;(self as unknown as { __retiregoldenOptimizerWorkerBuild?: string }).__retiregoldenOptimizerWorkerBuild =
+  'optimizer-worker-csp-2026-06-25'
+
+const post = (msg: OptimizeResponse) => (self as unknown as Worker).postMessage(msg)
+
+self.onmessage = async (event: MessageEvent<OptimizeRequest>) => {
+  try {
+    const result = await runOptimizeRequest(event.data, () => wasmUrl)
+    post({ type: 'done', result })
+  } catch (err) {
+    post({ type: 'error', message: err instanceof Error ? err.message : String(err) })
+  }
+}