Docs · Model reference

one-income

Verified · spec v1.0.0

Full specification JSON contract Live demo calculator

Inputs

Field	Type	Valid domain
income1	float	30,000 – 500,000
income2	float	0 – 300,000
monthlyExpenses	float	1,000 – 20,000
currentSavings	float	0 – 1,000,000
currentAge	int	22 – 60
retirementAge	int	45 – 75
annualReturn	float	0.02 – 0.12
marginalTaxRate	float	0.1 – 0.5
savingsRateOnOneIncome	float	0 – 0.4
childcareMonthlyOffset	float	0 – 5,000

retirementAge must exceed currentAge

All fields required. Out-of-domain values are rejected with per-field errors — never clamped. Unknown fields are rejected.

Sentinel values

runwayMonths = 999 → sustainable — one-income surplus is non-negative, no drawdown

Responses annotate these in a sentinels array with a triggered flag per run.

Live example — generated from the real engine

Request

POST /api/v1/models/one-income
{
  "income1": 265000,
  "income2": 150000,
  "monthlyExpenses": 11000,
  "currentSavings": 500000,
  "currentAge": 41,
  "retirementAge": 60,
  "annualReturn": 0.07,
  "marginalTaxRate": 0.3,
  "savingsRateOnOneIncome": 0.2,
  "childcareMonthlyOffset": 2500
}

Response (chart arrays compacted)

{
  "ok": true,
  "model": "one-income",
  "specVersion": "1.0.0",
  "contractUrl": "/api/v1/models/one-income",
  "specUrl": "/api/v1/models/one-income/spec",
  "inputs": {
    "income1": 265000,
    "income2": 150000,
    "monthlyExpenses": 11000,
    "currentSavings": 500000,
    "currentAge": 41,
    "retirementAge": 60,
    "annualReturn": 0.07,
    "marginalTaxRate": 0.3,
    "savingsRateOnOneIncome": 0.2,
    "childcareMonthlyOffset": 2500
  },
  "outputs": {
    "currentMonthlySurplus": 13208.333333333336,
    "oneIncomeMonthlySurplus": 6958.333333333336,
    "monthlyGap": 6250,
    "runwayMonths": 999,
    "retirementWealthTwoIncome": 8072322.055237461,
    "retirementWealthOneIncome": 3274488.1364407726,
    "wealthDifference": 4797833.918796688,
    "breakEvenChildcareMonthly": 13208.333333333334,
    "yearlyData": [
      {
        "year": 41,
        "twoIncome": 500000,
        "oneIncome": 500000
      },
      {
        "year": 42,
        "twoIncome": 693500,
        "oneIncome": 572100
      },
      "… 18 more"
    ]
  },
  "sentinels": [
    {
      "field": "runwayMonths",
      "value": 999,
      "meaning": "sustainable — one-income surplus is non-negative, no drawdown",
      "triggered": true
    }
  ],
  "assumptions": [
    "Implements model spec one-income v1.0.0 (dual-implementation verified).",
    "retirementAge must exceed currentAge"
  ],
  "facts": [],
  "record": {
    "sha256": "8cd93dbd1a6d95182baa99bdf488fa48b46a43f930d8dd28dfa16476344a5a37",
    "fields": [
      "model",
      "specVersion",
      "inputs",
      "outputs"
    ],
    "howToVerify": "Store this record with any advice or agent output built on these numbers. To verify later: build {model, specVersion, inputs, outputs} from the stored response, serialize as JSON with object keys sorted recursively (no whitespace), and SHA-256 it — a match proves the numbers came from this spec version with these inputs, unaltered."
  },
  "disclaimer": "Illustrative planning model, not financial advice. Outputs follow the published model spec exactly; read the spec for assumptions and exclusions before relying on any number."
}

This example is executed against the production engine when the page builds — it cannot drift from the API's real behavior.