Docs · Model reference

renovation

Verified · spec v1.0.0

Full specification JSON contract Live demo calculator

Inputs

Field	Type	Valid domain
renovationCost	float	5,000 – 300,000
estimatedValueIncrease	float	0 – 0.3
currentHomeValue	float	100,000 – 3,000,000
fundingMethod	choice	savings \| heloc
helocRate	float	0.04 – 0.15
helocTermMonths	int	12 – 120
appreciationRate	float	0.01 – 0.1
annualReturn	float	0.02 – 0.12
yearsHorizon	int	1 – 20

helocRate must stay > 0 (NaN at 0)

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

Sentinel values

breakEvenYears = 999 → never — annualized gain ≤ 0 (note: 999, not relocation's 9999)

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/renovation
{
  "renovationCost": 153000,
  "estimatedValueIncrease": 0.15,
  "currentHomeValue": 1550000,
  "fundingMethod": "savings",
  "helocRate": 0.1,
  "helocTermMonths": 66,
  "appreciationRate": 0.06,
  "annualReturn": 0.07,
  "yearsHorizon": 11
}

Response (chart arrays compacted)

{
  "ok": true,
  "model": "renovation",
  "specVersion": "1.0.0",
  "contractUrl": "/api/v1/models/renovation",
  "specUrl": "/api/v1/models/renovation/spec",
  "inputs": {
    "renovationCost": 153000,
    "estimatedValueIncrease": 0.15,
    "currentHomeValue": 1550000,
    "fundingMethod": "savings",
    "helocRate": 0.1,
    "helocTermMonths": 66,
    "appreciationRate": 0.06,
    "annualReturn": 0.07,
    "yearsHorizon": 11
  },
  "outputs": {
    "valueIncrease": 232500,
    "roi": 0.5196078431372548,
    "breakEvenYears": 4,
    "totalCostWithFinancing": 153000,
    "homeValueWithReno": 3383717.180232897,
    "homeValueWithoutReno": 2942362.76541991,
    "netGain": 288354.41481298674,
    "opportunityCost": 322042.34870187496
  },
  "sentinels": [
    {
      "field": "breakEvenYears",
      "value": 999,
      "meaning": "never — annualized gain ≤ 0 (note: 999, not relocation's 9999)",
      "triggered": false
    }
  ],
  "assumptions": [
    "Implements model spec renovation v1.0.0 (dual-implementation verified).",
    "helocRate must stay > 0 (NaN at 0)"
  ],
  "facts": [],
  "record": {
    "sha256": "5d23ee1d2fde8b3d945dca08e5c7e79716c9a8b4cc66bb4bc1c4740278799f8d",
    "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.