Docs · Model reference

relocation

Verified · spec v1.0.0

Full specification JSON contract Live demo calculator

Inputs

Field	Type	Valid domain
currentSalary	float	30,000 – 300,000
newSalary	float	30,000 – 300,000
currentMonthlyExpenses	float	1,000 – 15,000
newMonthlyExpenses	float	1,000 – 15,000
movingCosts	float	0 – 50,000
currentSavings	float	0 – 500,000
annualReturn	float	0.02 – 0.12
yearsHorizon	int	1 – 30

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

Sentinel values

breakEvenMonths = 9999 → never breaks even (monthlyNetDelta ≤ 0)

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/relocation
{
  "currentSalary": 165000,
  "newSalary": 165000,
  "currentMonthlyExpenses": 8000,
  "newMonthlyExpenses": 8000,
  "movingCosts": 25000,
  "currentSavings": 250000,
  "annualReturn": 0.07,
  "yearsHorizon": 16
}

Response (chart arrays compacted)

{
  "ok": true,
  "model": "relocation",
  "specVersion": "1.0.0",
  "contractUrl": "/api/v1/models/relocation",
  "specUrl": "/api/v1/models/relocation/spec",
  "inputs": {
    "currentSalary": 165000,
    "newSalary": 165000,
    "currentMonthlyExpenses": 8000,
    "newMonthlyExpenses": 8000,
    "movingCosts": 25000,
    "currentSavings": 250000,
    "annualReturn": 0.07,
    "yearsHorizon": 16
  },
  "outputs": {
    "annualSalaryDelta": 0,
    "annualExpenseDelta": 0,
    "annualNetDelta": 0,
    "movingCostRecoveryMonths": 9999,
    "breakEvenMonths": 9999,
    "wealthAtHorizonStay": 2662316.6321558263,
    "wealthAtHorizonMove": 2588512.538441691,
    "netWealthGain": -73804.09371413523,
    "yearlyData": [
      {
        "year": 0,
        "stay": 250000,
        "move": 225000
      },
      {
        "year": 1,
        "stay": 336500,
        "move": 309750
      },
      "… 15 more"
    ]
  },
  "sentinels": [
    {
      "field": "breakEvenMonths",
      "value": 9999,
      "meaning": "never breaks even (monthlyNetDelta ≤ 0)",
      "triggered": true
    }
  ],
  "assumptions": [
    "Implements model spec relocation v1.0.0 (dual-implementation verified)."
  ],
  "facts": [],
  "record": {
    "sha256": "7247d12f1e287249ee84b6aa1488ebce4d2f70a96cc89a1d73015414a54ef8e8",
    "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.