retirement-income-cliffs

POST /api/v1/models/retirement-income-cliffs
{
  "filingStatus": "single",
  "ssAnnualBenefit": 60000,
  "otherOrdinaryIncome": 500000,
  "taxExemptInterest": 100000,
  "additionalIncome": 250000,
  "healthCoverage": "medicare",
  "householdSize": 5,
  "benchmarkMonthlyPremium": 2500
}

{
  "ok": true,
  "model": "retirement-income-cliffs",
  "specVersion": "1.0.0",
  "contractUrl": "/api/v1/models/retirement-income-cliffs",
  "specUrl": "/api/v1/models/retirement-income-cliffs/spec",
  "inputs": {
    "filingStatus": "single",
    "ssAnnualBenefit": 60000,
    "otherOrdinaryIncome": 500000,
    "taxExemptInterest": 100000,
    "additionalIncome": 250000,
    "healthCoverage": "medicare",
    "householdSize": 5,
    "benchmarkMonthlyPremium": 2500
  },
  "outputs": {
    "taxableSsBase": 51000,
    "taxableSsWithAddition": 51000,
    "federalTaxBase": 161619.25,
    "federalTaxDelta": 90708,
    "irmaaTier": 5,
    "irmaaAnnualBase": 6936,
    "irmaaAnnualWithAddition": 6936,
    "irmaaDelta": 0,
    "fplPercent": 0,
    "acaSubsidyBase": 0,
    "acaSubsidyWithAddition": 0,
    "acaSubsidyLost": 0,
    "totalCostOfAddition": 90708,
    "trueMarginalRate": 0.362832,
    "dollarsToNextIrmaaTier": -1,
    "dollarsToAcaCliff": -1,
    "dollarsToNextSsTier": -1
  },
  "sentinels": [
    {
      "field": "dollarsToNextIrmaaTier",
      "value": -1,
      "meaning": "top IRMAA tier, or not on Medicare",
      "triggered": true
    },
    {
      "field": "dollarsToAcaCliff",
      "value": -1,
      "meaning": "past the 400% cliff, below the 100% floor, or not on ACA coverage",
      "triggered": true
    },
    {
      "field": "dollarsToNextSsTier",
      "value": -1,
      "meaning": "provisional income already past the adjusted base amount",
      "triggered": true
    }
  ],
  "assumptions": [
    "Implements model spec retirement-income-cliffs v1.0.0 (Concordance-tested: independently reimplemented from the spec).",
    "additionalIncome is ordinary in character. Taxable income and IRMAA-MAGI use a deduction-free proxy; IRMAA's two-year lookback is reported, not simulated; ACA uses the 48-state FPL with tax-family = coverage-family (spec exclusions)."
  ],
  "facts": [
    {
      "id": "irs.ss-taxation.base.single",
      "label": "SS taxation base amount, single (§86(c)(1))",
      "value": 25000,
      "period": "statutory (not indexed)",
      "source": "IRC §86(c)(1)"
    },
    {
      "id": "irs.ss-taxation.base.mfj",
      "label": "SS taxation base amount, married filing jointly (§86(c)(1)(B))",
      "value": 32000,
      "period": "statutory (not indexed)",
      "source": "IRC §86(c)(1)(B)"
    },
    {
      "id": "irs.ss-taxation.adjusted-base.single",
      "label": "SS taxation adjusted base amount, single (§86(c)(2))",
      "value": 34000,
      "period": "statutory (not indexed)",
      "source": "IRC §86(c)(2)"
    },
    {
      "id": "irs.ss-taxation.adjusted-base.mfj",
      "label": "SS taxation adjusted base amount, married filing jointly (§86(c)(2)(B))",
      "value": 44000,
      "period": "statutory (not indexed)",
      "source": "IRC §86(c)(2)(B)"
    },
    {
      "id": "irs.ss-taxation.inclusion.tier1",
      "label": "SS benefit inclusion rate between base and adjusted base (§86(a)(1))",
      "value": 0.5,
      "period": "statutory (not indexed)",
      "source": "IRC §86(a)(1)"
    },
    {
      "id": "irs.ss-taxation.inclusion.tier2",
      "label": "SS benefit maximum inclusion rate above the adjusted base (§86(a)(2))",
      "value": 0.85,
      "period": "statutory (not indexed)",
      "source": "IRC §86(a)(2)"
    },
    {
      "id": "cms.irmaa.tier1-threshold.single.2026",
      "label": "IRMAA first-tier MAGI boundary, single (2026)",
      "value": 109000,
      "period": "CY2026",
      "source": "CMS fact sheet: 2026 Medicare Parts A & B Premiums and Deductibles (2025-11-14)"
    },
    {
      "id": "cms.irmaa.tier1-threshold.mfj.2026",
      "label": "IRMAA first-tier MAGI boundary, married filing jointly (2026)",
      "value": 218000,
      "period": "CY2026",
      "source": "CMS fact sheet: 2026 Medicare Parts A & B Premiums and Deductibles (2025-11-14)"
    },
    {
      "id": "cms.irmaa.partb.top-surcharge.2026",
      "label": "IRMAA Part B top-tier monthly surcharge (2026)",
      "value": 487,
      "period": "CY2026",
      "source": "CMS fact sheet: 2026 Medicare Parts A & B Premiums and Deductibles (2025-11-14)"
    },
    {
      "id": "cms.irmaa.partd.top-surcharge.2026",
      "label": "IRMAA Part D top-tier monthly surcharge (2026)",
      "value": 91,
      "period": "CY2026",
      "source": "CMS fact sheet: 2026 Medicare Parts A & B Premiums and Deductibles (2025-11-14)"
    },
    {
      "id": "irs.aca.applicable-pct.floor.2026",
      "label": "ACA applicable percentage, bottom of the table (< 133% FPL), TY2026",
      "value": 0.021,
      "period": "TY2026",
      "source": "IRS Rev. Proc. 2025-25, §3.01 Applicable Percentage Table for 2026"
    },
    {
      "id": "irs.aca.applicable-pct.cap.2026",
      "label": "ACA applicable percentage, top of the table (300–400% FPL), TY2026",
      "value": 0.0996,
      "period": "TY2026",
      "source": "IRS Rev. Proc. 2025-25, §3.01 Applicable Percentage Table for 2026"
    },
    {
      "id": "hhs.fpl.household-of-one.2025",
      "label": "HHS poverty guideline, one person, 48 contiguous states + DC (2025 — the vintage 2026-coverage ACA subsidies key off)",
      "value": 15650,
      "period": "CY2025 guidelines (used for 2026 coverage year)",
      "source": "HHS Annual Update of the Poverty Guidelines, 90 FR 5917 (2025-01-17)"
    },
    {
      "id": "hhs.fpl.per-additional-person.2025",
      "label": "HHS poverty guideline, per additional household member, 48 contiguous states + DC (2025)",
      "value": 5500,
      "period": "CY2025 guidelines (used for 2026 coverage year)",
      "source": "HHS Annual Update of the Poverty Guidelines, 90 FR 5917 (2025-01-17)"
    },
    {
      "id": "irs.brackets.single.top-of-10pct.2026",
      "label": "Top of 10% ordinary bracket, single (vintage marker for the TY2026 table)",
      "value": 12400,
      "period": "TY2026",
      "source": "IRS TY2026 inflation adjustments (Rev. Proc. 2025-32)"
    },
    {
      "id": "irs.brackets.mfj.top-of-10pct.2026",
      "label": "Top of 10% ordinary bracket, MFJ (vintage marker for the TY2026 table)",
      "value": 24800,
      "period": "TY2026",
      "source": "IRS TY2026 inflation adjustments (Rev. Proc. 2025-32)"
    }
  ],
  "record": {
    "sha256": "cca819d18a751be8f02f3f9df3c6f86a39f207274e77efbb1db66e8723e5e796",
    "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."
}