@retiregolden/planner-ui 0.1.0

package/src/import/genericCsv.ts

@@ -0,0 +1,224 @@
+/**
+ * Generic spreadsheet / RPM CSV import (onboarding-import-and-migration step 4).
+ *
+ * For everything without a recognized export: the Bogleheads Retiree Portfolio
+ * Model saved as CSV, a homegrown net-worth spreadsheet, another tool's ad-hoc
+ * dump. Two-phase: `analyzeGenericCsv` finds the header row and guesses a role
+ * for each column; the wizard lets the user correct the roles; then
+ * `draftPlanFromGenericCsv` maps rows to accounts with the shared review
+ * checklist. Reuses the hardened CSV core from step 2.
+ */
+
+import type { Account, Plan } from '@retiregolden/engine/model/plan'
+import { createEmptyPlan, parsePlan } from '@retiregolden/engine/model/plan'
+import { parseCsv, parseMoney } from './csv'
+import { mapProjectionLabAccountType } from './projectionLab'
+import type { ImportReviewItem } from './reviewChecklist'
+
+export type ColumnRole = 'name' | 'type' | 'balance' | 'costBasis' | 'contribution' | 'ignore'
+
+export const COLUMN_ROLE_LABEL: Record<ColumnRole, string> = {
+  name: 'Account name',
+  type: 'Account type',
+  balance: 'Balance / value',
+  costBasis: 'Cost basis',
+  contribution: 'Annual contribution',
+  ignore: 'Ignore',
+}
+
+export interface GenericCsvAnalysis {
+  header: string[]
+  dataRows: string[][]
+  /** One guessed role per header column; the wizard lets the user override. */
+  guessedRoles: ColumnRole[]
+}
+
+export type GenericCsvAnalysisResult = { ok: true; analysis: GenericCsvAnalysis } | { ok: false; message: string }
+
+/** Guess a column's role from its header text. */
+export function guessColumnRole(headerCell: string): ColumnRole {
+  const h = headerCell.trim().toLowerCase()
+  if (h === '') return 'ignore'
+  if (/basis|cost/.test(h)) return 'costBasis'
+  if (/contribut|saving|deposit/.test(h)) return 'contribution'
+  if (/balance|value|amount|total|\$/.test(h)) return 'balance'
+  if (/type|class|category|tax treatment/.test(h)) return 'type'
+  if (/account|name|description|label|holding|asset/.test(h)) return 'name'
+  return 'ignore'
+}
+
+/** True when the cell reads as data (money) rather than a label. */
+function isMoneyish(cell: string): boolean {
+  return parseMoney(cell) !== null
+}
+
+/**
+ * Find the header row (the first row that is mostly non-numeric labels and is
+ * followed by at least one row with a money-ish cell) and guess column roles.
+ */
+export function analyzeGenericCsv(text: string): GenericCsvAnalysisResult {
+  const parsed = parseCsv(text)
+  if (!parsed.ok) return { ok: false, message: parsed.message }
+  const rows = parsed.rows
+
+  for (let r = 0; r < Math.min(rows.length, 30); r++) {
+    const cells = rows[r]!
+    const nonEmpty = cells.filter((c) => c.trim() !== '')
+    if (nonEmpty.length < 2) continue
+    if (nonEmpty.some(isMoneyish)) continue // data row, not a header
+    const dataRows = rows.slice(r + 1).filter((row) => row.some(isMoneyish))
+    if (dataRows.length === 0) continue
+    const guessedRoles = cells.map(guessColumnRole)
+    // A usable table needs at least a name-ish and a money-ish column somewhere;
+    // the user can still fix the guesses by hand.
+    return { ok: true, analysis: { header: cells, dataRows, guessedRoles } }
+  }
+  return {
+    ok: false,
+    message:
+      'No header row followed by rows with dollar values was found. Save the sheet as CSV with one row per account and a header row (e.g. "Account, Type, Balance").',
+  }
+}
+
+export interface GenericCsvDraft {
+  plan: Plan
+  review: ImportReviewItem[]
+}
+
+export type GenericCsvDraftResult = { ok: true } & GenericCsvDraft | { ok: false; message: string }
+
+/**
+ * Map data rows onto a draft plan using the (possibly user-corrected) column
+ * roles. Rows without a readable balance are reported and skipped; account
+ * types come from the type column when present, else from the name, else
+ * default to taxable with a review item.
+ */
+export function draftPlanFromGenericCsv(
+  analysis: GenericCsvAnalysis,
+  roles: ColumnRole[],
+  newId: () => string = () => crypto.randomUUID(),
+): GenericCsvDraftResult {
+  const nameCol = roles.indexOf('name')
+  const balanceCol = roles.indexOf('balance')
+  if (balanceCol === -1) {
+    return { ok: false, message: 'Assign one column as the balance/value before importing.' }
+  }
+  const typeCol = roles.indexOf('type')
+  const basisCol = roles.indexOf('costBasis')
+  const contributionCol = roles.indexOf('contribution')
+
+  const review: ImportReviewItem[] = []
+  const plan = createEmptyPlan({ newId, name: 'Imported from spreadsheet' })
+  const ownerId = plan.household.people[0]!.id
+
+  // Spreadsheet footers that re-state sums import as phantom accounts if kept.
+  const totalRowRe = /^(sub)?total\b|grand total/i
+  const loanLikeRe = /\bloan\b|debt|mortgage|heloc|liabilit|credit/i
+
+  for (let r = 0; r < analysis.dataRows.length; r++) {
+    const cells = analysis.dataRows[r]!
+    const name = (nameCol === -1 ? '' : (cells[nameCol] ?? '').trim()) || `Row ${r + 1}`
+    const typeText = typeCol === -1 ? '' : (cells[typeCol] ?? '').trim()
+    if (totalRowRe.test(name) || totalRowRe.test(typeText)) {
+      review.push({ status: 'skipped', source: name, detail: 'Summary/total row — counting it would double the money above it.' })
+      continue
+    }
+    const balance = parseMoney(cells[balanceCol])
+    // A negative balance on a loan-looking row is a liability written with a
+    // sign convention — import it as debt instead of dropping the row.
+    const negativeLiability = balance !== null && balance < 0 && loanLikeRe.test(`${name} ${typeText}`)
+    if ((balance === null || balance < 0) && !negativeLiability) {
+      review.push({ status: 'skipped', source: name, detail: 'Row had no readable non-negative balance.' })
+      continue
+    }
+    const guessSource = typeText !== '' ? typeText : name
+    const typeGuess = negativeLiability ? 'debt' : mapProjectionLabAccountType(typeText, name)
+    const mapped = typeGuess ?? 'taxable'
+    const amount = Math.abs(balance!)
+
+    const base = { id: newId(), name, annualReturnPct: null }
+    const contribution = contributionCol === -1 ? null : parseMoney(cells[contributionCol])
+    const annualContribution = contribution !== null && contribution > 0 ? contribution : 0
+
+    let account: Account
+    switch (mapped) {
+      case 'taxable': {
+        const basisRaw = basisCol === -1 ? null : parseMoney(cells[basisCol])
+        // A negative basis cell (adjustment lines, sign conventions) must not
+        // sink the whole import at validation — treat it like a missing basis.
+        const basis = basisRaw !== null && basisRaw >= 0 ? basisRaw : null
+        account = { ...base, type: 'taxable', ownerPersonId: null, balance: amount, costBasis: basis ?? amount, annualContribution }
+        if (basis === null) {
+          review.push({
+            status: 'defaulted',
+            source: name,
+            detail:
+              (basisRaw !== null && basisRaw < 0 ? 'The cost basis cell was negative, so it was ignored — ' : 'No cost basis column/value — ') +
+              'basis was set equal to the balance (no unrealized gain). Correct it on the Accounts screen.',
+          })
+        }
+        break
+      }
+      case 'traditional':
+      case 'roth':
+        account = {
+          ...base,
+          type: mapped,
+          ownerPersonId: ownerId,
+          kind: /401|403|457|tsp/i.test(guessSource) ? 'employer' : 'ira',
+          balance: amount,
+          annualContribution,
+        }
+        break
+      case 'hsa':
+        account = { ...base, type: 'hsa', ownerPersonId: ownerId, balance: amount, annualContribution }
+        break
+      case 'cash':
+        account = { ...base, type: 'cash', ownerPersonId: null, balance: amount, annualContribution }
+        break
+      case 'property':
+        account = { ...base, type: 'property', ownerPersonId: null, value: amount, plannedSaleYear: null, expectedNetProceeds: null }
+        break
+      case 'debt':
+        account = { ...base, type: 'debt', ownerPersonId: null, balance: amount, interestPct: 5, monthlyPayment: 0 }
+        if (negativeLiability) {
+          review.push({
+            status: 'defaulted',
+            source: name,
+            detail: `The negative balance looked like a liability sign convention — imported as a $${amount.toLocaleString('en-US', { maximumFractionDigits: 0 })} debt.`,
+          })
+        }
+        review.push({
+          status: 'defaulted',
+          source: name,
+          detail: 'Debts need an interest rate and monthly payment — defaults of 5% and $0/mo were used; set the real terms on the Accounts screen.',
+        })
+        break
+    }
+    plan.accounts.push(account)
+    review.push({
+      status: typeGuess === null ? 'defaulted' : 'mapped',
+      source: `${name}${typeText !== '' ? ` (${typeText})` : ''}`,
+      detail:
+        typeGuess === null
+          ? `No recognizable account type — imported as a taxable account with a $${amount.toLocaleString('en-US', { maximumFractionDigits: 0 })} balance. Change the type on the Accounts screen if that is wrong.`
+          : `Imported as a ${mapped} account with a $${amount.toLocaleString('en-US', { maximumFractionDigits: 0 })} balance.`,
+    })
+  }
+
+  if (plan.accounts.length === 0) {
+    return { ok: false, message: 'No rows with a readable balance were found with the current column assignment.' }
+  }
+
+  review.push({
+    status: 'unmapped',
+    source: 'Everything except accounts',
+    detail: 'Spreadsheet rows import as account balances only — enter household, income, spending, and Social Security in the planner sections.',
+  })
+
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) {
+    return { ok: false, message: `The mapped plan failed validation: ${parsed.issues.join('; ')}` }
+  }
+  return { ok: true, plan: parsed.plan, review }
+}

package/src/import/projectionLab.ts

@@ -0,0 +1,350 @@
+/**
+ * ProjectionLab data-export mapper (onboarding-import-and-migration step 3).
+ *
+ * ProjectionLab lets users export their data as JSON. This maps that file's
+ * documented, user-visible substance — current-finances accounts, income
+ * sources, expenses, and the retirement milestone — onto a draft RetireGolden
+ * plan through the normal validated plan route. The export is version-sniffed
+ * by shape (`currentFinances.accounts`); anything else is refused with a
+ * helpful message rather than guessed at, and every mapped, assumed, or
+ * unmappable item lands on the review checklist. No scraping, no network —
+ * the user's own exported file, parsed in the browser.
+ */
+
+import type { Account, Plan } from '@retiregolden/engine/model/plan'
+import { createEmptyPlan, parsePlan } from '@retiregolden/engine/model/plan'
+import { MAX_REASONABLE_DOLLARS, parseMoney } from './csv'
+import type { ImportReviewItem } from './reviewChecklist'
+
+export const MAX_IMPORT_JSON_CHARS = 10_000_000
+
+export type ProjectionLabImportResult =
+  | { ok: true; plan: Plan; review: ImportReviewItem[] }
+  | { ok: false; message: string }
+
+const UNRECOGNIZED_MESSAGE =
+  'This file does not match a ProjectionLab data export we recognize (expected a "currentFinances" section with accounts). ' +
+  'ProjectionLab may have changed its format — you can still bring balances over with the broker CSV or spreadsheet import.'
+
+function asRecord(v: unknown): Record<string, unknown> | null {
+  return typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null
+}
+
+function asArray(v: unknown): unknown[] | null {
+  return Array.isArray(v) ? v : null
+}
+
+/**
+ * A finite, sane, non-negative dollar amount — anything else is null. Numeric
+ * strings ("350000", "$4,500") are accepted through the strict money parser,
+ * since JSON exports sometimes stringify amounts; junk still fails.
+ */
+function asDollars(v: unknown): number | null {
+  if (typeof v === 'string') {
+    const parsed = parseMoney(v)
+    return parsed !== null && parsed >= 0 ? parsed : null
+  }
+  if (typeof v !== 'number' || !Number.isFinite(v)) return null
+  if (v < 0 || v > MAX_REASONABLE_DOLLARS) return null
+  return v
+}
+
+function asString(v: unknown): string | null {
+  return typeof v === 'string' && v.trim() !== '' ? v.trim() : null
+}
+
+function firstString(rec: Record<string, unknown>, ...keys: string[]): string | null {
+  for (const k of keys) {
+    const s = asString(rec[k])
+    if (s !== null) return s
+  }
+  return null
+}
+
+function firstDollars(rec: Record<string, unknown>, ...keys: string[]): number | null {
+  for (const k of keys) {
+    const n = asDollars(rec[k])
+    if (n !== null) return n
+  }
+  return null
+}
+
+type MappedType = 'cash' | 'taxable' | 'traditional' | 'roth' | 'hsa' | 'property' | 'debt'
+
+/**
+ * Keyword-match a ProjectionLab account type/name onto a RetireGolden account
+ * class. Loan/debt keywords are checked first so "401k loan" or "IRA loan" is
+ * a liability, never a retirement asset.
+ */
+export function mapProjectionLabAccountType(type: string, name: string): MappedType | null {
+  const t = `${type} ${name}`.toLowerCase()
+  if (/mortgage|debt|\bloan\b|liabilit|heloc/.test(t)) return 'debt'
+  if (/\broth\b/.test(t)) return 'roth'
+  if (/\bhsa\b|health savings/.test(t)) return 'hsa'
+  if (/401|403|457\b|\bira\b|pretax|pre-tax|traditional|\btsp\b|rollover|sep\b|simple\b/.test(t)) return 'traditional'
+  if (/real.?estate|property|\bhome\b|house/.test(t)) return 'property'
+  if (/taxable|brokerage|investment/.test(t)) return 'taxable'
+  if (/cash|checking|savings|money market|emergency/.test(t)) return 'cash'
+  return null
+}
+
+export function mapProjectionLabExport(
+  json: string,
+  newId: () => string = () => crypto.randomUUID(),
+): ProjectionLabImportResult {
+  if (json.length > MAX_IMPORT_JSON_CHARS) {
+    return { ok: false, message: 'File is too large to be a ProjectionLab export.' }
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(json)
+  } catch {
+    return { ok: false, message: 'This file is not valid JSON.' }
+  }
+  const root = asRecord(raw)
+  if (!root) return { ok: false, message: UNRECOGNIZED_MESSAGE }
+
+  const currentFinances = asRecord(root['currentFinances'])
+  const rawAccounts = currentFinances ? asArray(currentFinances['accounts']) : null
+  if (!currentFinances || !rawAccounts) return { ok: false, message: UNRECOGNIZED_MESSAGE }
+
+  const review: ImportReviewItem[] = []
+  const plan = createEmptyPlan({ newId, name: 'Imported from ProjectionLab' })
+  const person = plan.household.people[0]!
+
+  // --- Household ------------------------------------------------------------
+  const user = asRecord(root['user']) ?? asRecord(root['profile'])
+  const birthYearRaw = user?.['birthYear']
+  const birthYear =
+    typeof birthYearRaw === 'number' && Number.isInteger(birthYearRaw) && birthYearRaw > 1900 && birthYearRaw < 2100
+      ? birthYearRaw
+      : null
+  if (birthYear !== null) {
+    person.dob = `${birthYear}-07-01`
+    review.push({
+      status: 'defaulted',
+      source: `Birth year ${birthYear}`,
+      detail: 'Date of birth set to July 1 of your ProjectionLab birth year — set the exact date on the Household screen.',
+    })
+  } else {
+    review.push({
+      status: 'unmapped',
+      source: 'Date of birth',
+      detail: 'The export carried no readable birth year — set your date of birth on the Household screen.',
+    })
+  }
+  review.push({
+    status: 'defaulted',
+    source: 'Filing status & state',
+    detail: `Filing status defaulted to single and state to ${plan.household.state} — ProjectionLab exports do not carry them. Set both on the Household screen.`,
+  })
+
+  // Retirement milestone age, when present on the first plan.
+  const firstPlan = asArray(root['plans'])?.map(asRecord).find((p) => p !== null) ?? null
+  const milestones = firstPlan ? (asArray(firstPlan['milestones']) ?? []) : []
+  for (const m of milestones) {
+    const rec = asRecord(m)
+    if (!rec) continue
+    const name = (firstString(rec, 'name', 'label') ?? '').toLowerCase()
+    const age = rec['age']
+    if (name.includes('retire') && typeof age === 'number' && age >= 30 && age <= 80) {
+      person.retirementAge = age
+      review.push({ status: 'mapped', source: `Milestone "${firstString(rec, 'name', 'label')!}"`, detail: `Retirement age set to ${age}.` })
+      break
+    }
+  }
+
+  // --- Accounts ---------------------------------------------------------------
+  for (const entry of rawAccounts) {
+    const rec = asRecord(entry)
+    if (!rec) continue
+    const name = firstString(rec, 'name', 'label') ?? 'Imported account'
+    const typeStr = firstString(rec, 'type', 'accountType', 'category') ?? ''
+    const balance = firstDollars(rec, 'balance', 'value', 'currentBalance', 'amount')
+    if (balance === null) {
+      review.push({ status: 'skipped', source: name, detail: 'Account had no readable balance.' })
+      continue
+    }
+    const mapped = mapProjectionLabAccountType(typeStr, name)
+    if (mapped === null) {
+      review.push({
+        status: 'unmapped',
+        source: `${name} (${typeStr || 'unknown type'}, $${balance.toLocaleString('en-US', { maximumFractionDigits: 0 })})`,
+        detail: 'Account type has no RetireGolden equivalent mapping — add it by hand on the Accounts screen.',
+      })
+      continue
+    }
+
+    const base = { id: newId(), name, annualReturnPct: null }
+    let account: Account
+    switch (mapped) {
+      case 'taxable': {
+        const costBasis = firstDollars(rec, 'costBasis', 'basis')
+        account = {
+          ...base,
+          type: 'taxable',
+          ownerPersonId: null,
+          balance,
+          costBasis: costBasis ?? balance,
+          annualContribution: 0,
+        }
+        if (costBasis === null) {
+          review.push({
+            status: 'defaulted',
+            source: name,
+            detail: 'No cost basis in the export — basis was set equal to the balance (no unrealized gain). Correct it on the Accounts screen.',
+          })
+        }
+        break
+      }
+      case 'traditional':
+        account = {
+          ...base,
+          type: 'traditional',
+          ownerPersonId: person.id,
+          kind: /401|403|457|tsp/i.test(`${typeStr} ${name}`) ? 'employer' : 'ira',
+          balance,
+          annualContribution: 0,
+        }
+        break
+      case 'roth':
+        account = {
+          ...base,
+          type: 'roth',
+          ownerPersonId: person.id,
+          kind: /401|403|457|tsp/i.test(`${typeStr} ${name}`) ? 'employer' : 'ira',
+          balance,
+          annualContribution: 0,
+        }
+        break
+      case 'hsa':
+        account = { ...base, type: 'hsa', ownerPersonId: person.id, balance, annualContribution: 0 }
+        break
+      case 'cash':
+        account = { ...base, type: 'cash', ownerPersonId: null, balance, annualContribution: 0 }
+        break
+      case 'property':
+        account = { ...base, type: 'property', ownerPersonId: null, value: balance, plannedSaleYear: null, expectedNetProceeds: null }
+        break
+      case 'debt': {
+        const interestRaw = rec['interestRate']
+        const payment = firstDollars(rec, 'payment', 'monthlyPayment')
+        // Nothing imports silently: an unreadable rate falls back to 5% with a
+        // review item, and a fraction-looking rate (0.035) is scaled with one.
+        let interestPct = 5
+        let interestNote: string | null = 'No readable interest rate in the export — 5% was assumed. Set the real rate on the Accounts screen.'
+        if (typeof interestRaw === 'number' && Number.isFinite(interestRaw) && interestRaw >= 0 && interestRaw < 100) {
+          if (interestRaw > 0 && interestRaw < 1) {
+            interestPct = Math.round(interestRaw * 100 * 10000) / 10000
+            interestNote = `The export's interest rate of ${interestRaw} looked like a fraction — imported as ${interestPct}%. Check it on the Accounts screen.`
+          } else {
+            interestPct = interestRaw
+            interestNote = null
+          }
+        }
+        account = {
+          ...base,
+          type: 'debt',
+          ownerPersonId: null,
+          balance,
+          interestPct,
+          monthlyPayment: payment ?? 0,
+        }
+        if (interestNote !== null) {
+          review.push({ status: 'defaulted', source: name, detail: interestNote })
+        }
+        if (payment === null) {
+          review.push({
+            status: 'defaulted',
+            source: name,
+            detail: 'No monthly payment in the export — set the real payment on the Accounts screen.',
+          })
+        }
+        break
+      }
+    }
+    plan.accounts.push(account)
+    review.push({
+      status: 'mapped',
+      source: `${name} (${typeStr || 'type from name'})`,
+      detail: `Imported as a ${mapped} account with a $${balance.toLocaleString('en-US', { maximumFractionDigits: 0 })} balance.`,
+    })
+  }
+
+  // --- Income sources ---------------------------------------------------------
+  const rawIncomes = asArray(currentFinances['incomeSources']) ?? asArray(currentFinances['incomes']) ?? []
+  for (const entry of rawIncomes) {
+    const rec = asRecord(entry)
+    if (!rec) continue
+    const name = firstString(rec, 'name', 'label') ?? 'Income'
+    const annual = firstDollars(rec, 'annualAmount', 'annual', 'amount')
+    if (annual === null) {
+      review.push({ status: 'skipped', source: name, detail: 'Income source had no readable annual amount.' })
+      continue
+    }
+    const typeStr = (firstString(rec, 'type', 'category') ?? '').toLowerCase()
+    const looksLikeWages = /employment|salary|wage|job|work/.test(`${typeStr} ${name.toLowerCase()}`)
+    if (looksLikeWages) {
+      plan.incomes.push({ type: 'wages', id: newId(), personId: person.id, annualGross: annual, endAge: null, realGrowthPct: 0 })
+      review.push({ status: 'mapped', source: name, detail: `Imported as wages of $${annual.toLocaleString('en-US')} /yr until retirement.` })
+    } else if (/social security|\bss\b|ssa/.test(`${typeStr} ${name.toLowerCase()}`)) {
+      review.push({
+        status: 'unmapped',
+        source: name,
+        detail: 'Social Security needs a claim age and benefit basis — set it up on the Social Security screen (you can import your SSA statement there).',
+      })
+    } else {
+      plan.incomes.push({
+        type: 'recurring',
+        id: newId(),
+        label: name,
+        annualAmount: annual,
+        startYear: null,
+        endYear: null,
+        inflationAdjusted: true,
+        taxTreatment: 'ordinary',
+      })
+      review.push({
+        status: 'defaulted',
+        source: name,
+        detail: `Imported as recurring ordinary income of $${annual.toLocaleString('en-US')} /yr with no end year — set dates and tax treatment on the Income screen.`,
+      })
+    }
+  }
+
+  // --- Expenses ----------------------------------------------------------------
+  const rawExpenses = asArray(currentFinances['expenses']) ?? []
+  let expenseTotal = 0
+  const expenseNames: string[] = []
+  for (const entry of rawExpenses) {
+    const rec = asRecord(entry)
+    if (!rec) continue
+    const annual = firstDollars(rec, 'annualAmount', 'annual', 'amount')
+    if (annual === null) continue
+    expenseTotal += annual
+    const name = firstString(rec, 'name', 'label')
+    if (name) expenseNames.push(name)
+  }
+  if (expenseTotal > 0) {
+    plan.expenses.baseAnnual = expenseTotal
+    review.push({
+      status: 'defaulted',
+      source: expenseNames.length > 0 ? expenseNames.join(', ') : 'Expenses',
+      detail: `Baseline annual spending set to the $${expenseTotal.toLocaleString('en-US')} sum of your ProjectionLab expenses — RetireGolden models one baseline plus phases/goals, so re-shape it on the Spending screen (healthcare is modeled separately).`,
+    })
+  } else {
+    review.push({ status: 'unmapped', source: 'Spending', detail: 'No readable expenses in the export — set baseline spending on the Spending screen.' })
+  }
+
+  review.push({
+    status: 'unmapped',
+    source: 'Strategies, assumptions & scenarios',
+    detail: 'Withdrawal strategy, Roth conversions, market assumptions, and scenarios do not transfer between tools — review the Strategy and Assumptions screens.',
+  })
+
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) {
+    return { ok: false, message: `The mapped plan failed validation: ${parsed.issues.join('; ')}` }
+  }
+  return { ok: true, plan: parsed.plan, review }
+}

package/src/import/reviewChecklist.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared review-checklist model for every import mapper
+ * (onboarding-import-and-migration). The rule that keeps mapping honest:
+ * nothing imports silently — every value that lands in a draft plan, every
+ * default the mapper had to invent, and every source item it could NOT map
+ * becomes a visible review item.
+ */
+
+export type ImportItemStatus = 'mapped' | 'defaulted' | 'unmapped' | 'skipped'
+
+export interface ImportReviewItem {
+  status: ImportItemStatus
+  /** Where in the source this came from (file row, export field, 1040 line). */
+  source: string
+  /** What happened in the draft plan — or why nothing did and what to do instead. */
+  detail: string
+}
+
+export const IMPORT_STATUS_LABEL: Record<ImportItemStatus, string> = {
+  mapped: 'Imported',
+  defaulted: 'Assumed — review',
+  unmapped: 'Not imported — add by hand',
+  skipped: 'Skipped',
+}
+
+/** Display order: what needs the user's eyes first. */
+export const IMPORT_STATUS_ORDER: ImportItemStatus[] = ['unmapped', 'defaulted', 'mapped', 'skipped']
+
+export function countByStatus(items: ImportReviewItem[]): Record<ImportItemStatus, number> {
+  const counts: Record<ImportItemStatus, number> = { mapped: 0, defaulted: 0, unmapped: 0, skipped: 0 }
+  for (const item of items) counts[item.status]++
+  return counts
+}