Integrate TransformedYield and add Cashflow support for ZRC methods

[alecloudenback]

Summary

This PR upgrades ActuaryUtilities to work with FinanceModels v5, integrating TransformedYield for key-rate bump-and-reprice, adding Cashflow object support across all ZeroRateCurve methods, and expanding documentation with live @example blocks.

Key changes

• TransformedYield for KeyRateZero — Replace the old _krd_new_curve(::KeyRateZero) (which extracted zero rates, mutated a vector, and refitted a spline) with a lazy TransformedYield that applies a Ho (1992) tent-function bump closure directly. This avoids unnecessary curve refitting and preserves the original curve's interpolation method.

• Cashflow object support — All ZeroRateCurve-based duration, convexity, and sensitivities methods now accept AbstractVector{<:Cashflow} directly (amounts and timepoints extracted automatically), eliminating the need to manually split cashflows.

• Do-block forwarding for AbstractYieldModel — duration(fn, yield_model) and convexity(fn, yield_model) now forward correctly to the existing duration(yield, fn) dispatch, enabling do-block syntax with any yield model (not just ZRC).

• FinanceModels v5 compat — Bumped compat to "5", updated tests for two FM v5 breaking changes:

  • CompositeYield now operates in continuous zero-rate space, so duration(Yield.Constant(r), ...) returns the continuous modified duration (= Macaulay duration) rather than periodic modified duration
  • ForwardYields renamed to ForwardYield (singular)

Files changed

File	Change
Project.toml	FM compat ^4.17 → 5
docs/Project.toml	Add FinanceModels dep for @example blocks
README.md	Update snippet to use Cashflow objects
src/financial_math.jl	_tent_bump + _ensure_yield_model helpers, TransformedYield-based _krd_new_curve(::KeyRateZero), _extract_cfs_times helper, Cashflow overloads for all ZRC methods, do-block forwarding for AbstractYieldModel
test/runtests.jl	Fix 3 tests for FM v5 API changes, add KeyRateZero TransformedYield testset (tent bump shape, type checks, KRD sum ≈ total duration), add Cashflow support testset (27 tests across single/two-curve variants), add do-block + dispatch priority tests
docs/src/financial_math.md	New "Curve Transformations" section with 6 live @example blocks (parallel shift, periodic rate arithmetic, tenor-dependent twist, PV comparison, bootstrapped curve + stress, negative rates)
docs/src/sensitivities.md	New "Using Cashflow Objects" and "Constructing a ZeroRateCurve from Other Models" sections, new "Validating AD with TransformedYield" live @example block

Test plan

• All existing tests pass (72/72 duration and convexity, including the 3 fixed FM v5 tests)
• New KeyRateZero TransformedYield tests pass (14 tests — tent bump shape for interior/first/last points, type checks, KRD sum ≈ total modified duration)
• New ZeroRateCurve Cashflow support tests pass (27 tests — all duration/convexity/sensitivities variants with single and two-curve, including semi-annual cashflows on annual-tenor curves)
• New do-block with AbstractYieldModel tests pass (2 tests)
• New ZRC dispatch priority tests pass (2 tests — ZRC AD path preferred over AbstractYieldModel forwarding)
• Docs build with live @example blocks (requires FM dev with TransformedYield)

🤖 Generated with Claude Code