Guard against rates at or below -100% and fix rounding in ytm

[tubedude]

Summary

This release hardens the library against edge cases where rates at or below -100% would cause arithmetic errors or nonsensical results. It also fixes a double-rounding bug in bond yield calculations and improves validation of input parameters.

Key Changes

Rate validation (the main fix)

• All functions that compute (1 + rate)^t now validate that 1 + rate > 0 and return {:error, :undefined} instead of raising ArithmeticError or returning garbage. This includes:
  • CashFlow.xnpv, npv, mirr
  • TVM.fv, pv, pmt, amortization_schedule
  • Bonds.price and risk metrics (duration, modified_duration, convexity)
  • Returns.discounted_payback_period, profitability_index, twr
  • Rates.effective_annual_rate
  • Depreciation.sln (also now rejects non-positive life)
• Rates.nominal_rate(-1.0, m) now correctly returns -m (total loss), staying the exact inverse of effective_annual_rate

Bond yield rounding fix

• Bonds.ytm now solves the per-period rate at high precision (≥12 decimals) and rounds the annualized yield once, rather than rounding the period rate first and then multiplying by freq. The old path let freq amplify rounding error into the last reported digit (off by 1–3 units depending on frequency).
• Returns.profitability_index similarly computes at full precision before the final round

Input validation improvements

• :precision is now validated as 0..15 (the range Float.round/2 accepts) instead of any non-negative integer
• :guess and :tolerance now accept integers as well as floats
• Bonds functions now require an integer freq (matching the documented pos_integer type)
• Depreciation.syd rejects fractional period values, matching ddb/db
• xirr(dates, []) now correctly returns {:error, :mismatched_lengths} instead of crashing (empty amounts list is the two-list form, not options)

Discounting refactor

• Centralized overflow-safe discounting in a new discount_factor(rate, t) helper that computes (1 + rate)^-t (negative exponent). This avoids the divide form 1 / (1 + rate)^t which would overflow its denominator at high rates over long horizons. All bond and returns metrics now route through this helper.
• Moved the safely/1 wrapper (which catches ArithmeticError and maps it to :diverged) to Finance.Shared so both solvers use it consistently

Date parsing robustness

• CashFlow.xirr now uses Date.from_erl/1 instead of a broad rescue, so malformed amounts raise immediately (a caller error) rather than being mislabeled as {:error, :invalid_date}

Test coverage

• Added @solvers list to run fuzz properties and pathological corpus tests against both Newton and Brent solvers, ensuring both satisfy the same robustness contracts
• Extended test suite with edge cases for rates at/below -100%, negative coupons, and degenerate inputs

Notable Implementation Details

• The bracket scan in the solver now stops one step sooner when the root sits exactly at the guess, improving efficiency
• Bond risk metrics (duration, modified_duration, convexity) now return {:error, :undefined} when a negative coupon drives the unit-face price to zero, rather than a nonsensical value or crash
• TVM.amortization_schedule validates that the principal is positive and the rate is above -100% before building the schedule, preventing undefined payment calculations
• All rate-dependent calculations now use a consistent guard: 1 + rate > 0 (or

https://claude.ai/code/session_01AVibXT2w1dEdVtMHqffFKn

[coveralls]

coverage: 100.0%. remained the same — 1.6.1 into main