Ladder build total cost

Purchase cost of all rungs in the modeled income-floor ladder.

Field: totalCost Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (ladder total cost)

Calculation records

• Level-real-income ladder: faces solved back to front Formula record, justified by derivation

  Purpose: The face amount of each rung so that every payout year's maturing principal plus the coupons of the rungs still outstanding equals the target real income.

  Statement: For target real income A, first payout offset p and payout count q (each rounded to an integer and clamped to at least 1), rungs mature at offsets m = p..p+q-1 with coupon rates c_m = max(0.125%, y(m))/100. Faces are solved from the last offset backward: F_m = max(0, (A - sum over later offsets j of F_j c_j)/(1 + c_m)), so that F_m(1 + c_m) plus the coupons of every rung still outstanding equals A in year m. Each rung is then priced on the curve (ladder-annual-coupon-par-pricing); totalCost is the sum of rung costs; annualRealIncomeByOffset lists coupons plus maturing principal for offsets 1..p+q-1 (coupon-only inside a deferral window); targetAnnualRealIncome echoes A. Units: real (today's) dollars. Rounding: none.

  Formula: F_m = max(0, (A - sum_{j>m} F_j c_j) / (1 + c_m)) for m from last to first; income_m = F_m (1 + c_m) + sum_{j>m} F_j c_j = A

  • A: Level real income target per payout year (unit: usd) (domain: A >= 0)
  • m: Maturity offset of a rung (unit: years) (domain: integer, p <= m <= p+q-1, p >= 1)
  • c_m: Coupon rate of the rung maturing at m, as a fraction (unit: 1) (domain: c_m >= 0.00125)
  • F_m: Real face of the rung maturing at m (unit: usd) (domain: F_m >= 0)

  Timing: end of year, annual; the rung maturing in year m pays its last coupon and principal that year

  Rounding: none

  Limits:

  • Faces are floored at zero: a target smaller than the later rungs' coupons yields a zero-face rung and that year then receives more than the target
  • Payout offset and count are rounded and clamped to at least 1 rather than rejected
  • Coupons pay annually and par yields serve as spot rates for pricing (ladderMath.ts header simplifications)
  • No CUSIP-level lot rounding in core mode; faces are continuous

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: ladder-backward-face-construction.md Mutation receipt: ladder-backward-face-construction.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Is the number of: ladder-rung-face, ladder-build-annual-real-income-by-offset, ladder-build-total-cost, ladder-build-target-annual-real-income

Records that feed this number

• Synthetic TIPS rung: floored coupon and par-curve price Formula record, justified by derivation

  Purpose: What one ladder rung costs today: its annual real coupons and principal discounted on the curve, with the coupon set to the yield at maturity floored at 0.125%.

  Statement: For a rung of real face F maturing n whole years out, the coupon rate is c = max(0.125%, y(n)), where y(n) is the interpolated par real yield at n years. The price is the sum over k = 1..n of (F·c/100 + [k = n]·F)/(1 + y(k)/100)^k: each end-of-year cash flow discounted at the interpolated par yield for its own year treated as a spot rate. On a flat curve with a nonbinding floor c = y and the price equals F. Units: real (today's) dollars; percent inputs are divided by 100. Domain: F >= 0, integer n >= 1, y(k) > -100%. Rounding: none.

  Formula: c = max(0.125, y(n)); P = sum_{k=1..n} (F c/100 + [k = n] F) / (1 + y(k)/100)^k

  • F: Real face (principal) of the rung (unit: usd) (domain: F >= 0)
  • n: Maturity offset from the anchor year (unit: years) (domain: integer n >= 1)
  • y(k): Interpolated par real yield at k years (unit: percent/year) (domain: y(k) > -100)
  • c: Annual coupon rate of the synthetic rung (unit: percent/year) (domain: c >= 0.125)
  • P: Real purchase price of the rung (unit: usd) (domain: P >= 0)

  Timing: end of year, annual coupons, principal with the last coupon

  Rounding: none

  Limits:

  • Coupons pay annually; real-world semiannual TIPS timing is ignored (ladderMath.ts header)
  • Par yields are used as spot rates for discounting; no zero curve is bootstrapped (ladderMath.ts header)
  • The 0.125% floor is the regulatory minimum TIPS coupon; a curve yield below it prices the rung above par
  • No CUSIP-level lot rounding in core mode: face is continuous at $1 granularity (ladderMath.ts header)
  • tipsCouponRatePct and priceRung are module-private; the evidence reaches them through buildLadder with a one-rung ladder whose target is F(1 + c), which the back-substitution solves to face F exactly

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: ladder-annual-coupon-par-pricing.md Mutation receipt: ladder-annual-coupon-par-pricing.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Is the number of: ladder-rung-cost, ladder-rung-coupon-rate-pct

  Feeds: ladder-build-total-cost

• Embedded Treasury par real-yield curve, 2026-06-30 Data record, justified by dataset

  Purpose: The offline TIPS real-yield snapshot every ladder quote and funded ratio discounts on.

  Statement: Five par real yields in percent per year at 5, 7, 10, 20 and 30 years, dated 2026-06-30, taken from the U.S. Treasury Daily Par Real Yield Curve and stored as {asOfIso, source, points[]} sorted ascending by maturity. Consumers interpolate linearly between points and hold the endpoints flat (ladder-real-yield-interpolation). The stored row is the official 2026-06-30 row exactly as Treasury publishes it: 1.93, 2.06, 2.20, 2.54 and 2.73. Rounding: none; the yields keep the hundredth of a percent Treasury publishes.

  Limits:

  • Stored exactly as published, with no rounding to the nearest 5 basis points (decision D-TREASURY, 2026-09-25). Until 2026-09-27 the stored row was 1.85/2.05/2.25/2.55/2.70, which the worksheet showed was neither the official row nor its nearest 5 basis points: 8 basis points below the official row at 5 years, 1 below at 7, 5 above at 10, 1 above at 20 and 3 below at 30. Every ladder quote and funded ratio priced on the curve moved with the correction
  • Maturities below 5 years read the 5-year yield and above 30 years the 30-year yield (flat endpoints)
  • Par yields are consumed as spot rates by every ladder and funded-ratio calculation
  • Refresh cadence is annual with the published parameters; the opt-in FedInvest fetch never replaces this snapshot

  Dataset: U.S. Department of the Treasury, Daily Treasury Par Real Yield Curve Rates, row dated 06/30/2026 (5, 7, 10, 20 and 30 year columns) , as of 2026-06-30 , retrieved 2026-09-27

  Provenance: derived by claude, implemented by claude-subagent.

  Independent review: codex

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: treasury-real-yield-curve-2026.md Mutation receipt: treasury-real-yield-curve-2026.mutation.md

  Evidence tests: realYieldCurve2026.evidence.test.ts

  Implemented in: realYieldCurve2026.ts

  Feeds: income-floor-ladder-yield-pct, ladder-rung-cost, ladder-rung-coupon-rate-pct, ladder-build-total-cost, funded-ratio-result-essential-spending-pv, funded-ratio-result-guaranteed-income-pv, funded-ratio-result-funded-ratio-pct, funded-ratio-result-unfunded-pv

Engine source: engine/src/ladder/ladderMath.ts (LadderBuild.totalCost)