Ladder rung cost

Purchase cost of a single modeled ladder rung.

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

Appears in: income-floor (rung cost)

Calculation records

• 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

Records that feed this number

• FedInvest security-price CSV: TIPS rows to reference records Data record, justified by dataset

  Purpose: Turns the FedInvest end-of-day price file into TIPS reference rows with rates in percent and ISO maturities.

  Statement: Each line of the header-less FedInvest CSV is split on commas (surrounding quotes trimmed) into cusip, type, rate, maturity (MM/DD/YYYY), call, buy, sell, endOfDay. A row is kept only when it has at least eight cells, type is exactly TIPS, cusip is non-empty, the maturity is a valid calendar date, rate and end-of-day price are finite and the price is positive. Output per row: ratePct = rate × 100, maturityIso = YYYY-MM-DD, endOfDayPrice = the end-of-day price per $100 face; rows sorted ascending by maturityIso. Rounding: none.

  Formula: ratePct = 100 × rate; maturityIso = YYYY-MM-DD from MM/DD/YYYY; endOfDayPrice = endOfDay

  • rate: Coupon rate as published, a decimal fraction (unit: 1) (domain: finite)
  • ratePct: Coupon rate in percent (unit: percent/year) (domain: finite)
  • endOfDay: End-of-day price per $100 face (unit: usd per 100 face) (domain: > 0)

  Timing: one price file per business day; the file carries no date of its own

  Rounding: none

  Limits:

  • FedInvest omits the TIPS inflation index ratio, so parsed prices are a reference check against the embedded-curve quote, never a replacement for it
  • Rows with fewer than eight cells, a non-TIPS type, an invalid date, a non-finite number or a non-positive price are dropped silently
  • The CSV carries no price date; a snapshot imported from a file has no date
  • Cells are split on every comma; a quoted cell containing a comma is not supported

  Dataset: TreasuryDirect FedInvest security price detail CSV (securityprice.csv): one row per marketable Treasury with columns cusip, security type, rate as a decimal fraction, maturity MM/DD/YYYY, call date, buy, sell, end-of-day price per $100 face; no header row , as of 2026-07-08 , retrieved 2026-09-14

  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: fedinvest-csv-tips-parsing.md Mutation receipt: fedinvest-csv-tips-parsing.mutation.md

  Evidence tests: fedInvest.evidence.test.ts

  Implemented in: fedInvest.ts

  Feeds: ladder-rung-cost

• Latest FedInvest price date: previous business day in local time Model record, justified by derivation

  Purpose: The most recent date FedInvest prices are likely to be published for, used as the snapshot and cache key.

  Statement: From a local timestamp now, step back one calendar day (today's prices are not out yet), then keep stepping back while the local weekday is Saturday or Sunday. latestPriceDateIso formats that date from local calendar components as YYYY-MM-DD, never through toISOString, which is UTC and disagrees near a timezone boundary. Domain: any valid Date. Rounding: whole civil days.

  Formula: d = now - 1 day; while weekday(d) in {Saturday, Sunday}: d = d - 1 day; iso = local YYYY-MM-DD of d

  • now: The observation instant, read in local time (unit: timestamp) (domain: valid Date)
  • d: Candidate price date (unit: civil day) (domain: weekday(d) in Monday..Friday)

  Timing: civil days in the local time zone

  Rounding: whole days

  Limits:

  • Federal holidays are not recognized: the day after a Monday holiday reads the holiday itself as the price date
  • No evening publication cutoff is modeled: early on a business day the previous business day is assumed published
  • A publication-availability heuristic, not a data source; FedInvest is an opt-in reference and never replaces the embedded planning yields
  • Local-time components are used throughout; a Date built from a UTC string near midnight resolves to the local civil date

  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: fedinvest-latest-price-date.md Mutation receipt: fedinvest-latest-price-date.mutation.md

  Evidence tests: fedInvest.evidence.test.ts

  Implemented in: fedInvest.ts

  Feeds: ladder-rung-cost

• Nearest FedInvest TIPS for a rung year Formula record, justified by derivation

  Purpose: The reference TIPS whose maturity year is closest to a ladder rung's maturity year, when one lies within a year of it.

  Statement: From a list of parsed TIPS and a target calendar year, find the record minimizing |year(maturityIso) - target|, comparing calendar years only; the first minimum in list order wins a tie. Return that record only when its distance is at most one calendar year (|year(maturityIso) - target| <= 1); otherwise return null, as for an empty list. Units: a record selection, not a number. Rounding: none.

  Formula: selected = argmin_t |year(maturityIso_t) - target| when min_t |year(maturityIso_t) - target| <= 1; null otherwise, including the empty list

  • target: Calendar year the rung matures (unit: year) (domain: integer)
  • maturityIso_t: ISO maturity date of candidate t (unit: date) (domain: YYYY-MM-DD)

  Timing: calendar-year granularity; month and day are ignored

  Rounding: none

  Limits:

  • The one-year window (bestDistance <= 1) was omitted from the first derivation because the doc comment did not state it. The worksheet was re-derived on 2026-09-14 with three cases (A: 2032/2036 for 2033 selects 2032; B: 2030/2035 for 2033 returns null; C: 2033/2034 for 2033 selects 2033), the evidence test asserts all three and passes, and the doc comment now states the window
  • Ties are resolved by list order (first minimum wins); the worksheet states no tie rule and its cases avoid ties
  • Only the calendar year of the maturity is compared; a January and a December maturity of the same year are equidistant
  • A reference-row match for display, not CUSIP-level ladder optimization

  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: fedinvest-nearest-tips-maturity.md Mutation receipt: fedinvest-nearest-tips-maturity.mutation.md

  Evidence tests: fedInvest.evidence.test.ts

  Implemented in: fedInvest.ts

  Feeds: ladder-rung-cost

• Real present value of a cash-flow stream on the TIPS curve Formula record, justified by derivation

  Purpose: What it would cost today to defease each future real dollar with a Treasury of matching maturity.

  Statement: For flows (t, C_t) with t years from now and C_t in real dollars, PV = sum of C_t/(1 + y(t)/100)^t, where y(t) is the interpolated par real yield at maturity t with flat endpoints. A flow at t = 0 is added undiscounted; flows with t < 0 or C_t = 0 are skipped. Units: real (today's) dollars. Domain: finite flows, t >= 0, y(t) > -100%. Rounding: none.

  Formula: PV = sum_t C_t / (1 + y(t)/100)^t; the t = 0 term is C_0

  • t: Years from now to the flow (unit: years) (domain: t >= 0)
  • C_t: Real amount of the flow at t (unit: usd) (domain: finite)
  • y(t): Interpolated par real yield at t years (unit: percent/year) (domain: y(t) > -100)
  • PV: Present value of the stream (unit: usd) (domain: finite)

  Timing: end of year t, annual; t = 0 is today

  Rounding: none

  Limits:

  • Par yields are treated as spot rates; this is a planning approximation, not a bootstrapped zero curve
  • Negative offsets and zero amounts are dropped silently rather than rejected
  • A non-integer offset is discounted with a fractional exponent; no current caller supplies one

  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-real-present-value.md Mutation receipt: ladder-real-present-value.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Feeds: funded-ratio-result-essential-spending-pv, funded-ratio-result-guaranteed-income-pv, funded-ratio-result-funded-ratio-pct, funded-ratio-result-unfunded-pv, ladder-rung-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 (LadderRung.cost)