Extend Scheduling.fs to support balloon and bullet repayments

[Copilot]

Extends Scheduling.fs to support balloon and bullet repayment structures — a final lump-sum payment larger than the regular instalments.

Changes Made

AutoGenerateSchedule.BalloonPayment: int64<Cent>

A new field on AutoGenerateSchedule representing the deferred principal due at maturity (PCP Guaranteed Future Value, HP option price, or the full principal for bullet/interest-only loans). Defaults to 0L<Cent> for fully amortising products. All 92 existing call sites updated with BalloonPayment = 0L<Cent>.

Correct payment and APR calculation

• The bisection solver now targets principalBalance - balloonAmount = 0, so regular payments amortise only principal - balloon.
• The final payment is automatically set to last regular instalment + balloon by the existing adjustFinalPayment function.
• The rough-interest estimate uses an interpolated reduction factor (2/3 for fully amortising → 1.0 for bullet) so the bisection bounds always bracket the true level payment.
• APR is automatically correct — it already reads from the actual scheduled cash flows, so the balloon-inflated final payment is included with no extra work.
• The add-on interest convergence loop (equaliseInterest) also accounts for the balloon when computing the level payment and the convergence check.
• balloonAmount is clamped to [0, principal] to guard against invalid inputs.

pcp convenience constructor

A new pcp function in Scheduling.fs that builds a BasicParameters record with the GFV set as BalloonPayment. Pass the result to calculateBasicSchedule to derive the regular monthly payments, full amortisation schedule, and APR automatically.

HTML output

ScheduleConfig.toHtmlTable now shows the balloon payment amount when it is non-zero.

Testing

• ✅ Build passes with no warnings
• ✅ 219 pre-existing test failures unchanged (unrelated HTML-generation issue)
• ✅ 3 new tests added and passing:
  • BalloonTest_Pcp_20000_gfv8000_7pct_36m — PCP loan (£20k principal, £8k GFV, 7% annual, 36 months)
  • BalloonTest_Bullet_10000_5pct_12m — Bullet/interest-only loan (full principal as balloon, 5% annual, 12 months)
  • BalloonTest_Pcp_Convenience_25000_gfv10000_6p9pct_36m — PCP via pcp convenience constructor

[simontreanor]

@copilot continue

[Copilot]

@copilot continue

Implemented in commit a1f4920. Here's what was added:

AutoGenerateSchedule.BalloonPayment: int64<Cent> — The deferred principal due at maturity (GFV, HP option price, or full principal for bullet/interest-only). Defaults to 0L<Cent> for fully amortising products.

The bisection solver now targets principalBalance - balloonAmount = 0, so regular payments only amortise principal - balloon. The final payment is automatically adjusted by adjustFinalPayment to be last regular instalment + balloon. The interpolated interest-reduction factor (between 2/3 for fully amortising and 1.0 for bullet loans) ensures the bisection bounds always bracket the answer. APR is correct with no extra work since it already reads from the actual scheduled cash flows.

pcp convenience constructor — Builds a BasicParameters with the GFV as BalloonPayment; pass to calculateBasicSchedule to get the full schedule, APR, and stats.

Three new tests cover: a PCP loan (£20 k, £8 k GFV, 7%), a bullet/interest-only loan (£10 k principal = balloon, 5%), and the pcp convenience constructor. All 92 existing AutoGenerateSchedule { } record expressions updated with BalloonPayment = 0L<Cent>.