The household engine
One document. Projected, simulated, coordinated.
A household — members, accounts by tax wrapper, incomes, liabilities, expenses — as a single versioned document, and every computation the platform runs on it: a deterministic year-by-year projection, a seeded longevity-aware Monte Carlo, and 9 coordination strategies that answer together. This page is the engine described whole; the planning and household-management pages are what products build from it.
The document, and what runs on it
A versioned record with optimistic concurrency
Create it whole, then evolve it with PATCH deltas; every write is versioned, so concurrent updates conflict loudly instead of silently overwriting. The document is the single source the projections, simulations, and strategies all read.
Deterministic projection, honest simulation
The projection is exact arithmetic, year by year, per wrapper. The Monte Carlo is seeded — the same inputs reproduce the same bands — and longevity-aware, drawing horizons from SSA life tables rather than a fixed age. Assumptions are the caller's, or labeled illustrative defaults.
Migration with a dry run
Batches of up to 200 households, a dry-run mode that returns the complete per-row, per-field error worklist with zero writes, and idempotent re-runs keyed by your own import key. Aggregator adapters (Plaid, Akoya, MX shapes) feed live account data.
Signed webhooks, drift included
computed, updated, archived, decision — and drift, which fires when a stored plan's numbers move because a rate, rule, or balance did. Payloads are signed so your systems can trust the sender.
The 9 strategies
Decisions across accounts, not within one.
Each strategy returns ranked alternatives with a computed dollar delta against the baseline — every option shown, never just a winner — and each decision carries its own evidence record.
Withdrawal sequencing
Taxable, traditional, and Roth ordering with bracket management — which account to draw first, and what the ordering is worth in dollars.
Roth conversion ladders
Multi-year conversion schedules against bracket boundaries and IRMAA cliffs — how much to convert, when, and when to stop.
Social Security claiming
Claiming ages evaluated on the household's own projection, spousal coordination included.
Asset location
Wrapper-aware placement across taxable, traditional, and Roth accounts, with the annual tax-drag delta and constraints for locked accounts.
Tax-loss harvesting
Policy-level harvesting rules that emit policies and intents — the engine never trades.
Annual gifting
Gifting schedules under the annual exclusion, computed against the household's projection — the shipped seed of the estate & legacy roadmap.
Pension elections
Single-life vs. joint-and-survivor vs. lump sum, ranked on joint outcomes rather than sticker amounts.
Bracket-fill conversions
Roth conversions sized each year to the top of a chosen bracket from the household's own projected income, run through the projection and ranked net of IRMAA.
Charitable bunching and QCDs
The same gifts given every year, bunched into one year, or sent from the IRA as qualified charitable distributions, with the 2026 charitable rules applied.
POST /api/v1/households/{id}/decisions
{"strategy": "withdrawal-sequencing"}Where it surfaces
The live demo
The engine end to end on a labeled fictional household — projection, Monte Carlo bands, and the decisions on the table.
The reference build
The white-label evaluation surface: the same household through the component kit, with a theme switcher and a lite/advisor toggle.
The docs
Schemas, endpoints, webhooks, import, tenant configuration, and the MCP tools an AI assistant uses to do all of the above.