libitofin 0.52.1

//! Rate helpers for the yield-curve bootstrap.
//!
//! Port of `ql/termstructures/yield/ratehelpers.{hpp,cpp}` plus the overnight
//! helper of `ql/termstructures/yield/oisratehelper.{hpp,cpp}`. This module holds
//! [`DepositRateHelper`], the short end of the curve, [`SwapRateHelper`], the
//! long end over vanilla swaps, [`OISRateHelper`], the long end over
//! overnight-indexed swaps, [`FuturesRateHelper`], the short-to-mid end over
//! exchange-traded IMM/ASX futures, and [`FraRateHelper`], the mid end over
//! forward-rate agreements. [`super::BMASwapRateHelper`] implements municipal swaps
//! in its own module. The `SwapIndex`-based and explicit-start/end-date `SwapRateHelper`
//! constructors are deferred with the swap-index port. The `OISRateHelper`
//! explicit-start/end-date constructor is deferred likewise.
//!
//! [`FraRateHelper`] defers the from-scratch constructors that build a synthetic `"no-fix"` [`IborIndex`]
//! (`ratehelpers.cpp:263,293`), and the IMM-offset constructors
//! (`ratehelpers.cpp:322`, with the `nthImmDate` helper). None sit on the
//! bootstrap oracle path. Unlike C++, which registers the helper with its cloned
//! index (`registerWith(iborIndex_)`) and so must unregister that index from the
//! forwarding handle to keep relink notifications out of the bootstrap, the Rust
//! helper never observes the cloned index (matching [`DepositRateHelper`]), so
//! the relink-notification loop is already broken and no unregister is needed.
//! [`SwapRateHelper`], [`OISRateHelper`] and [`FraRateHelper`] instead subscribe
//! to the cloned index's fixing history on [`Settings`] directly (D11), which
//! keeps the fixing notifications the C++ index relays without observing the
//! clone's forecasting handle.

use std::cell::Cell;
use std::cell::RefCell;
use std::rc::Weak;

use crate::cashflows::RateAveraging;
use crate::errors::{QlError, QlResult};
use crate::handle::{Handle, RelinkableHandle};
use crate::indexes::OvernightIndex;
use crate::indexes::iborindex::IborIndex;
use crate::indexes::index::Index;
use crate::indexes::interestrateindex::InterestRateIndex;
use crate::instrument::Instrument;
use crate::instruments::{
    FuturesType, MakeOis, MakeVanillaSwap, OvernightIndexedSwap, VanillaSwap,
};
use crate::patterns::observable::{AsObservable, Observable};
use crate::quotes::{Quote, SimpleQuote};
use crate::settings::Settings;
use crate::shared::{Shared, shared};
use crate::termstructures::bootstraphelper::{
    BootstrapHelperBase, RateHelper, RelativeDateRateHelper,
};
use crate::termstructures::yieldtermstructure::YieldTermStructure;
use crate::time::businessdayconvention::BusinessDayConvention;
use crate::time::calendar::Calendar;
use crate::time::date::Date;
use crate::time::dategenerationrule::DateGeneration;
use crate::time::daycounter::DayCounter;
use crate::time::frequency::Frequency;
use crate::time::period::Period;
use crate::time::timeunit::TimeUnit;
use crate::time::{asx, imm};
use crate::types::{Integer, Natural, Real};
use std::panic::{AssertUnwindSafe, catch_unwind};

/// Bootstrap helper over a deposit rate (`DepositRateHelper`).
///
/// A deposit borrows at the quoted rate from spot to spot-plus-tenor;
/// [`implied_quote`](RateHelper::implied_quote) re-derives that rate from the
/// bootstrapping curve's discount factors between the value and maturity dates.
///
/// The load-bearing mechanism is the cloned index: the constructor re-curves
/// the supplied index onto the helper's *own* [`RelinkableHandle`] with
/// [`IborIndex::clone_with`] (`ratehelpers.cpp:206`), so the helper forecasts
/// off the curve it is being bootstrapped against rather than whatever curve
/// the index was handed. [`set_term_structure`](RateHelper::set_term_structure)
/// weak-links that handle to the bootstrapping curve, non-owning and unobserved
/// (the `null_deleter`/`observer = false` of `ratehelpers.cpp:217`).
pub struct DepositRateHelper {
    base: BootstrapHelperBase,
    date_error: RefCell<Option<QlError>>,
    index: IborIndex,
    term_structure_handle: RelinkableHandle<dyn YieldTermStructure>,
    fixing_date: Cell<Date>,
}

impl DepositRateHelper {
    /// A deposit helper fitting `quote`, an explicit market-rate handle, with
    /// its schedule taken from `index` (the C++ `DepositRateHelper(rate, i)`
    /// with `rate` a `Handle<Quote>`, `ratehelpers.cpp:195`).
    pub fn new(quote: Handle<dyn Quote>, index: &IborIndex) -> Shared<DepositRateHelper> {
        Self::build(quote, index)
    }

    /// A deposit helper fitting a fixed `rate`, wrapped in a [`SimpleQuote`]
    /// (the `rate`-as-`Rate` arm of the same C++ variant constructor).
    pub fn from_rate(rate: Real, index: &IborIndex) -> Shared<DepositRateHelper> {
        let quote = Handle::new(shared(SimpleQuote::new(rate)) as Shared<dyn Quote>);
        Self::build(quote, index)
    }

    fn build(quote: Handle<dyn Quote>, source_index: &IborIndex) -> Shared<DepositRateHelper> {
        let settings = source_index.base().settings().clone();
        Shared::new_cyclic(|weak: &Weak<DepositRateHelper>| {
            let weak = weak.clone();
            let on_eval_change = Box::new(move || {
                if let Some(helper) = weak.upgrade() {
                    helper.initialize_dates();
                }
            });
            let term_structure_handle = RelinkableHandle::<dyn YieldTermStructure>::empty();
            let index = source_index.clone_with(term_structure_handle.handle());
            let base = BootstrapHelperBase::new_relative(quote, settings, true, on_eval_change);
            let helper = DepositRateHelper {
                base,
                date_error: RefCell::new(None),
                index,
                term_structure_handle,
                fixing_date: Cell::new(Date::null()),
            };
            helper.initialize_dates();
            helper
        })
    }
}

impl AsObservable for DepositRateHelper {
    fn observable(&self) -> &Observable {
        self.base.observable()
    }
}

impl RateHelper for DepositRateHelper {
    fn base(&self) -> &BootstrapHelperBase {
        &self.base
    }

    /// The deposit rate implied by the current curve.
    ///
    /// The forecast flag is forced true (`iborIndex_->fixing(fixingDate_, true)`,
    /// `ratehelpers.cpp:213`): the helper prices off the curve, never off a
    /// stored fixing.
    fn implied_quote(&self) -> QlResult<Real> {
        if let Some(error) = self.date_error.borrow().as_ref() {
            return Err(error.clone());
        }
        self.base.term_structure()?;
        self.index.fixing(self.fixing_date.get(), true)
    }

    /// Weak-links the helper's own pricing handle to the bootstrapping curve,
    /// then records the curve on the base - both non-owning and unobserved
    /// (`ratehelpers.cpp:216`).
    fn set_term_structure(&self, term_structure: &Shared<dyn YieldTermStructure>) {
        self.term_structure_handle
            .link_to_weak(Shared::downgrade(term_structure));
        self.base.set_term_structure(term_structure);
    }
}

impl RelativeDateRateHelper for DepositRateHelper {
    /// Rebuilds the schedule off the current evaluation date
    /// (`initializeDates`, v1.44 `ratehelpers.cpp:228-237`): the earliest date
    /// is the index fixing days advanced on the fixing calendar from the
    /// unadjusted evaluation date (a Saturday plus two days is a Tuesday), the
    /// fixing date that date rolled back, and the maturity the earliest date
    /// advanced by the tenor. Pillar, latest and latest-relevant dates all
    /// equal the maturity.
    ///
    /// The earliest date no longer goes through the index value date, so for
    /// Libor-family indexes the joint-calendar adjust of `Libor::valueDate`
    /// (`libor.cpp:86-99`) no longer applies: the result changes on business
    /// days too when the spot lands on a value-calendar holiday.
    ///
    /// An unset evaluation date is stored as the error and returned by the
    /// next [`implied_quote`](RateHelper::implied_quote) (D10).
    fn initialize_dates(&self) {
        *self.date_error.borrow_mut() = self.try_initialize_dates().err();
    }
}

impl DepositRateHelper {
    fn try_initialize_dates(&self) -> QlResult<()> {
        let evaluation_date = self
            .base
            .evaluation_date()
            .ok_or_else(|| QlError::new("evaluation date is not set", file!(), line!()))?;
        let earliest = self.index.fixing_calendar().advance(
            evaluation_date,
            self.index.fixing_days() as Integer,
            TimeUnit::Days,
            BusinessDayConvention::Following,
            false,
        );
        self.fixing_date.set(self.index.fixing_date(earliest));
        let maturity = self.index.maturity_date(earliest)?;

        self.base.set_earliest_date(earliest);
        self.base.set_maturity_date(maturity);
        self.base.set_pillar_date(maturity);
        self.base.set_latest_date(maturity);
        self.base.set_latest_relevant_date(maturity);
        Ok(())
    }
}

/// Validates that `date` is a legal settlement date for the futures convention
/// (`CheckDate`, `ratehelpers.cpp:46`): IMM and ASX require a valid cycle date,
/// while [`FuturesType::Custom`] imposes no constraint.
fn check_futures_date(date: Date, futures_type: FuturesType) -> QlResult<()> {
    match futures_type {
        FuturesType::Imm => {
            crate::require!(
                imm::is_imm_date(date, false),
                "{date} is not a valid IMM date"
            )
        }
        FuturesType::Asx => {
            crate::require!(
                asx::is_asx_date(date, false),
                "{date} is not a valid ASX date"
            )
        }
        FuturesType::Custom => {}
    }
    Ok(())
}

/// Resolves the maturity of an explicit-date futures helper (the C++
/// `determineMaturityDate` lambda, `ratehelpers.cpp:100`): with no end date,
/// advance three futures periods off `next_date`; with one, take it after
/// checking it is past the start.
fn determine_maturity(
    start: Date,
    end: Option<Date>,
    next_date: impl Fn(Date) -> Date,
) -> QlResult<Date> {
    match end {
        None => Ok(next_date(next_date(next_date(start)))),
        Some(end) => {
            crate::require!(
                end > start,
                "end date ({end}) must be greater than start date ({start})"
            );
            Ok(end)
        }
    }
}

/// Bootstrap helper over an exchange-traded interest-rate future
/// (`FuturesRateHelper`).
///
/// The helper fits the quoted futures price `P` (e.g. `96.0` for a 4% implied
/// rate) at a fixed IMM/ASX window. Unlike the deposit, swap and OIS helpers it
/// derives from the **plain** [`RateHelper`], not [`RelativeDateRateHelper`]:
/// the earliest and maturity dates are absolute, computed once at construction
/// from the supplied dates, and never rebuilt on an evaluation-date change
/// (there is no `initialize_dates`). It therefore holds the bootstrapping curve
/// directly through [`base`](RateHelper::base) rather than forecasting off a
/// cloned index on its own relinkable handle.
///
/// [`implied_quote`](RateHelper::implied_quote) re-derives the price from the
/// curve (`ratehelpers.cpp:157`): the simple forward over the window is
/// `(discount(earliest)/discount(maturity) - 1)/year_fraction`, and the price is
/// `100 * (1 - (forward + convexity_adjustment))`. The convexity adjustment is a
/// plain [`Handle<Quote>`](Handle) value, whatever quote the caller supplies -
/// a [`FuturesConvAdjustmentQuote`](crate::quotes::FuturesConvAdjustmentQuote)
/// prices one off a Hull-White model; it may be negative, as futures margining
/// can push the futures rate either side of the forward.
pub struct FuturesRateHelper {
    base: BootstrapHelperBase,
    year_fraction: Real,
    conv_adj: Handle<dyn Quote>,
}

impl FuturesRateHelper {
    /// A futures helper over a length-in-months window off `ibor_start_date`
    /// (`ratehelpers.cpp:70`): the maturity is the start advanced
    /// `length_in_months` months on `calendar` under `convention`/`end_of_month`.
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        price: Handle<dyn Quote>,
        ibor_start_date: Date,
        length_in_months: Natural,
        calendar: Calendar,
        convention: BusinessDayConvention,
        end_of_month: bool,
        day_counter: DayCounter,
        conv_adj: Handle<dyn Quote>,
        futures_type: FuturesType,
    ) -> QlResult<Shared<FuturesRateHelper>> {
        check_futures_date(ibor_start_date, futures_type)?;
        let earliest = ibor_start_date;
        let maturity = calendar.advance(
            ibor_start_date,
            length_in_months as Integer,
            TimeUnit::Months,
            convention,
            end_of_month,
        );
        let year_fraction = day_counter.year_fraction_ref(earliest, maturity, earliest, maturity);
        Ok(Self::assemble(
            price,
            conv_adj,
            earliest,
            maturity,
            year_fraction,
        ))
    }

    /// A futures helper over an explicit window (`ratehelpers.cpp:91`). With
    /// `ibor_end_date` `None` the maturity is three [`imm`]/[`asx`] periods past
    /// the start; with `Some`, that date (which must be past the start for the
    /// IMM/ASX conventions). [`FuturesType::Custom`] requires an explicit end
    /// date - the C++ null-maturity path is an error here.
    pub fn from_end_date(
        price: Handle<dyn Quote>,
        ibor_start_date: Date,
        ibor_end_date: Option<Date>,
        day_counter: DayCounter,
        conv_adj: Handle<dyn Quote>,
        futures_type: FuturesType,
    ) -> QlResult<Shared<FuturesRateHelper>> {
        check_futures_date(ibor_start_date, futures_type)?;
        let maturity = match futures_type {
            FuturesType::Imm => {
                determine_maturity(ibor_start_date, ibor_end_date, |d| imm::next_date(d, false))?
            }
            FuturesType::Asx => {
                determine_maturity(ibor_start_date, ibor_end_date, |d| asx::next_date(d, false))?
            }
            FuturesType::Custom => match ibor_end_date {
                Some(end) => end,
                None => crate::fail!("a Custom futures helper requires an explicit end date"),
            },
        };
        let earliest = ibor_start_date;
        let year_fraction = day_counter.year_fraction_ref(earliest, maturity, earliest, maturity);
        Ok(Self::assemble(
            price,
            conv_adj,
            earliest,
            maturity,
            year_fraction,
        ))
    }

    /// A futures helper whose window follows `index`'s conventions
    /// (`ratehelpers.cpp:139`): the maturity is the start advanced by the index
    /// tenor on the index's fixing calendar under its business-day convention (no
    /// end-of-month), and the year fraction uses the index day counter.
    pub fn from_index(
        price: Handle<dyn Quote>,
        ibor_start_date: Date,
        index: &IborIndex,
        conv_adj: Handle<dyn Quote>,
        futures_type: FuturesType,
    ) -> QlResult<Shared<FuturesRateHelper>> {
        check_futures_date(ibor_start_date, futures_type)?;
        let earliest = ibor_start_date;
        let maturity = index.fixing_calendar().advance_by_period(
            ibor_start_date,
            index.tenor(),
            index.business_day_convention(),
            false,
        );
        let year_fraction = index
            .day_counter()
            .year_fraction_ref(earliest, maturity, earliest, maturity);
        Ok(Self::assemble(
            price,
            conv_adj,
            earliest,
            maturity,
            year_fraction,
        ))
    }

    /// Builds the plain-date base shared by the three constructors: observes the
    /// price (via the base) and the convexity quote (the C++
    /// `registerWith(convAdj_)`), then pins every schedule date to the fixed
    /// window - `pillar = latest = latest_relevant = maturity`.
    fn assemble(
        price: Handle<dyn Quote>,
        conv_adj: Handle<dyn Quote>,
        earliest: Date,
        maturity: Date,
        year_fraction: Real,
    ) -> Shared<FuturesRateHelper> {
        let base = BootstrapHelperBase::new(price);
        conv_adj.register_observer(&base.observer());
        base.set_earliest_date(earliest);
        base.set_maturity_date(maturity);
        base.set_pillar_date(maturity);
        base.set_latest_date(maturity);
        base.set_latest_relevant_date(maturity);
        shared(FuturesRateHelper {
            base,
            year_fraction,
            conv_adj,
        })
    }

    /// The convexity adjustment applied to the forward (`ratehelpers.cpp:168`):
    /// the convexity quote's value, or zero when no quote was supplied.
    pub fn convexity_adjustment(&self) -> QlResult<Real> {
        if self.conv_adj.is_empty() {
            Ok(0.0)
        } else {
            self.conv_adj.current_link()?.value()
        }
    }
}

impl AsObservable for FuturesRateHelper {
    fn observable(&self) -> &Observable {
        self.base.observable()
    }
}

impl RateHelper for FuturesRateHelper {
    fn base(&self) -> &BootstrapHelperBase {
        &self.base
    }

    /// The futures price implied by the current curve (`ratehelpers.cpp:157`).
    ///
    /// The simple forward over the fixed window comes straight off the curve's
    /// discount factors; the price adds the convexity adjustment to that forward
    /// and quotes `100 * (1 - future_rate)`.
    fn implied_quote(&self) -> QlResult<Real> {
        let term_structure = self.base.term_structure()?;
        let forward = (term_structure.discount_date(self.base.earliest_date(), false)?
            / term_structure.discount_date(self.base.maturity_date(), false)?
            - 1.0)
            / self.year_fraction;
        let future_rate = forward + self.convexity_adjustment()?;
        Ok(100.0 * (1.0 - future_rate))
    }
}

/// Selects the date at which a helper places its curve node.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Pillar {
    /// The instrument's maturity date.
    MaturityDate,
    /// The latest date the instrument needs data at.
    LastRelevantDate,
    /// A fixed date within the helper's earliest and latest relevant dates.
    CustomDate(Date),
}

impl Pillar {
    pub(crate) fn resolve(self, earliest: Date, maturity: Date, latest: Date) -> QlResult<Date> {
        match self {
            Self::MaturityDate => Ok(maturity),
            Self::LastRelevantDate => Ok(latest),
            Self::CustomDate(date) => {
                crate::require!(date != Date::null(), "custom pillar date must be provided");
                crate::require!(
                    date >= earliest,
                    "pillar date must be later than or equal to the instrument's earliest date"
                );
                crate::require!(
                    date <= latest,
                    "pillar date must be before or equal to the instrument's latest relevant date"
                );
                Ok(date)
            }
        }
    }
}

fn rebuild_dates<T>(rebuild: impl FnOnce() -> QlResult<T>) -> QlResult<T> {
    catch_unwind(AssertUnwindSafe(rebuild)).unwrap_or_else(|_| {
        Err(QlError::new(
            "helper dates exceed supported range",
            file!(),
            line!(),
        ))
    })
}

/// Bootstrap helper over a forward-rate-agreement rate (`FraRateHelper`).
///
/// The helper fits the rate of a FRA that starts `period_to_start` after spot
/// and spans the index tenor. Like [`DepositRateHelper`] it clones the supplied
/// index onto its own [`RelinkableHandle`] with [`IborIndex::clone_with`]
/// (`ratehelpers.cpp:315`) so it forecasts off the curve being bootstrapped, and
/// [`set_term_structure`](RateHelper::set_term_structure) weak-links that handle
/// to the bootstrapping curve, non-owning and unobserved.
///
/// It runs in one of two modes (`use_indexed_coupon`, C++ default `true`):
/// **indexed**, where [`implied_quote`](RateHelper::implied_quote) is the index
/// fixing forecast off the curve (`ibor_index.fixing(fixing_date, true)`), the
/// node pinned at `index.maturity_date(earliest)`; and **par**, where the quote
/// is the simple forward `(discount(earliest)/discount(maturity) - 1)/tau` over
/// the raw schedule window with `tau` the index day-count fraction, the node
/// pinned at the maturity (`ratehelpers.cpp:361`).
pub struct FraRateHelper {
    base: BootstrapHelperBase,
    date_error: RefCell<Option<QlError>>,
    index: IborIndex,
    term_structure_handle: RelinkableHandle<dyn YieldTermStructure>,
    period_to_start: Option<Period>,
    use_indexed_coupon: bool,
    pillar: Pillar,
    fixing_date: Cell<Date>,
    spanning_time: Cell<Real>,
}

impl FraRateHelper {
    /// Builds the helper and returns schedule or custom-pillar errors.
    #[allow(clippy::too_many_arguments)]
    pub fn try_new(
        quote: Handle<dyn Quote>,
        period_to_start: Period,
        index: &IborIndex,
        use_indexed_coupon: bool,
        pillar: Pillar,
    ) -> QlResult<Shared<FraRateHelper>> {
        let helper = Self::new(quote, period_to_start, index, use_indexed_coupon, pillar);
        helper.validate_dates()?;
        Ok(helper)
    }

    /// Builds the helper and returns schedule or custom-pillar errors.
    #[allow(clippy::too_many_arguments)]
    pub fn try_from_rate(
        rate: Real,
        period_to_start: Period,
        index: &IborIndex,
        use_indexed_coupon: bool,
        pillar: Pillar,
    ) -> QlResult<Shared<FraRateHelper>> {
        let helper = Self::from_rate(rate, period_to_start, index, use_indexed_coupon, pillar);
        helper.validate_dates()?;
        Ok(helper)
    }

    /// Builds the helper and returns schedule or custom-pillar errors.
    #[allow(clippy::too_many_arguments)]
    pub fn try_from_months(
        quote: Handle<dyn Quote>,
        months_to_start: Natural,
        index: &IborIndex,
        use_indexed_coupon: bool,
        pillar: Pillar,
    ) -> QlResult<Shared<FraRateHelper>> {
        crate::require!(
            months_to_start <= i32::MAX as u32,
            "months to start exceed supported range"
        );
        let helper = Self::from_months(quote, months_to_start, index, use_indexed_coupon, pillar);
        helper.validate_dates()?;
        Ok(helper)
    }

    /// Builds the helper and returns schedule or custom-pillar errors.
    #[allow(clippy::too_many_arguments)]
    pub fn try_from_dates(
        quote: Handle<dyn Quote>,
        start_date: Date,
        end_date: Date,
        index: &IborIndex,
        use_indexed_coupon: bool,
        pillar: Pillar,
    ) -> QlResult<Shared<FraRateHelper>> {
        let helper = Self::from_dates(
            quote,
            start_date,
            end_date,
            index,
            use_indexed_coupon,
            pillar,
        );
        helper.validate_dates()?;
        Ok(helper)
    }

    /// Returns the last schedule error, if a date change invalidated the helper.
    pub fn validate_dates(&self) -> QlResult<()> {
        match self.date_error.borrow().as_ref() {
            Some(error) => Err(error.clone()),
            None => Ok(()),
        }
    }

    /// A FRA helper fitting `quote` over the window starting `period_to_start`
    /// after spot and spanning `index`'s tenor (the index-based `Period`
    /// constructor, `ratehelpers.cpp:305`).
    pub fn new(
        quote: Handle<dyn Quote>,
        period_to_start: Period,
        index: &IborIndex,
        use_indexed_coupon: bool,
        pillar: Pillar,
    ) -> Shared<FraRateHelper> {
        Self::build(
            quote,
            Some(period_to_start),
            index,
            use_indexed_coupon,
            pillar,
            None,
        )
    }

    /// A FRA helper fitting a fixed `rate`, wrapped in a [`SimpleQuote`] (the
    /// `Rate` arm of the C++ `variant<Rate, Handle<Quote>>` constructor).
    pub fn from_rate(
        rate: Real,
        period_to_start: Period,
        index: &IborIndex,
        use_indexed_coupon: bool,
        pillar: Pillar,
    ) -> Shared<FraRateHelper> {
        let quote = Handle::new(shared(SimpleQuote::new(rate)) as Shared<dyn Quote>);
        Self::new(quote, period_to_start, index, use_indexed_coupon, pillar)
    }

    /// A FRA helper whose start is `months_to_start` months after spot (the
    /// index-based `Natural monthsToStart` constructor, `ratehelpers.cpp:271`,
    /// which delegates to the `Period` form via `months_to_start * Months`).
    pub fn from_months(
        quote: Handle<dyn Quote>,
        months_to_start: Natural,
        index: &IborIndex,
        use_indexed_coupon: bool,
        pillar: Pillar,
    ) -> Shared<FraRateHelper> {
        Self::new(
            quote,
            Period::new(months_to_start as Integer, TimeUnit::Months),
            index,
            use_indexed_coupon,
            pillar,
        )
    }

    /// A FRA helper over an explicit `[start_date, end_date]` window (the
    /// non-relative date constructor, `ratehelpers.cpp:341`). Its schedule is
    /// fixed at construction and, mirroring the C++ `RelativeDateRateHelper(rate,
    /// false)`, does not shift when the evaluation date moves.
    pub fn from_dates(
        quote: Handle<dyn Quote>,
        start_date: Date,
        end_date: Date,
        index: &IborIndex,
        use_indexed_coupon: bool,
        pillar: Pillar,
    ) -> Shared<FraRateHelper> {
        Self::build(
            quote,
            None,
            index,
            use_indexed_coupon,
            pillar,
            Some((start_date, end_date)),
        )
    }

    fn build(
        quote: Handle<dyn Quote>,
        period_to_start: Option<Period>,
        source_index: &IborIndex,
        use_indexed_coupon: bool,
        pillar: Pillar,
        explicit_dates: Option<(Date, Date)>,
    ) -> Shared<FraRateHelper> {
        let settings = source_index.base().settings().clone();
        let update_dates = explicit_dates.is_none();
        Shared::new_cyclic(|weak: &Weak<FraRateHelper>| {
            let weak = weak.clone();
            let on_eval_change = Box::new(move || {
                if let Some(helper) = weak.upgrade() {
                    helper.initialize_dates();
                }
            });
            let term_structure_handle = RelinkableHandle::<dyn YieldTermStructure>::empty();
            let index = source_index.clone_with(term_structure_handle.handle());
            let base =
                BootstrapHelperBase::new_relative(quote, settings, update_dates, on_eval_change);
            index
                .settings()
                .register_fixing_observer(&index.name(), &base.observer());
            let helper = FraRateHelper {
                base,
                date_error: RefCell::new(None),
                index,
                term_structure_handle,
                period_to_start,
                use_indexed_coupon,
                pillar,
                fixing_date: Cell::new(Date::null()),
                spanning_time: Cell::new(0.0),
            };
            if let Some((start, end)) = explicit_dates {
                helper.base.set_earliest_date(start);
                helper.base.set_maturity_date(end);
            }
            helper.initialize_dates();
            helper
        })
    }
}

impl AsObservable for FraRateHelper {
    fn observable(&self) -> &Observable {
        self.base.observable()
    }
}

impl RateHelper for FraRateHelper {
    fn base(&self) -> &BootstrapHelperBase {
        &self.base
    }

    /// The FRA rate implied by the current curve (`ratehelpers.cpp:361`).
    ///
    /// In indexed mode this is the index fixing forecast off the curve, forced
    /// on (`ibor_index.fixing(fixing_date, true)`); in par mode it is the simple
    /// forward `(discount(earliest)/discount(maturity) - 1)/spanning_time` read
    /// straight from the curve's discount factors.
    fn implied_quote(&self) -> QlResult<Real> {
        self.validate_dates()?;
        let term_structure = self.base.term_structure()?;
        if self.use_indexed_coupon {
            self.index.fixing(self.fixing_date.get(), true)
        } else {
            let discount_earliest =
                term_structure.discount_date(self.base.earliest_date(), false)?;
            let discount_maturity =
                term_structure.discount_date(self.base.maturity_date(), false)?;
            Ok((discount_earliest / discount_maturity - 1.0) / self.spanning_time.get())
        }
    }

    /// Weak-links the helper's own pricing handle to the bootstrapping curve,
    /// then records the curve on the base - both non-owning and unobserved
    /// (`ratehelpers.cpp:372`, `observer = false`).
    fn set_term_structure(&self, term_structure: &Shared<dyn YieldTermStructure>) {
        self.term_structure_handle
            .link_to_weak(Shared::downgrade(term_structure));
        self.base.set_term_structure(term_structure);
    }
}

impl RelativeDateRateHelper for FraRateHelper {
    /// Rebuilds the schedule off the current evaluation date (`initializeDates`,
    /// v1.44 `ratehelpers.cpp:392-397`).
    ///
    /// When the helper tracks the evaluation date (the relative constructors),
    /// spot is the index fixing days advanced on the fixing calendar from the
    /// unadjusted evaluation date (not the index value date, so no Libor
    /// joint-calendar adjust), the earliest date is `period_to_start` past spot
    /// and the maturity is the
    /// combined `period_to_start + tenor` past spot - both advanced from spot,
    /// not chained, so a business-day roll on the intermediate date cannot leak
    /// into the maturity. The explicit-date constructor sets those two dates at
    /// construction and skips this block. Either way the latest-relevant date,
    /// pillar, latest date and fixing date follow: indexed mode pins the node at
    /// `index.maturity_date(earliest)`, par mode at the maturity and caches the
    /// spanning year fraction.
    fn initialize_dates(&self) {
        *self.date_error.borrow_mut() = self.try_initialize_dates().err();
    }
}

impl FraRateHelper {
    fn try_initialize_dates(&self) -> QlResult<()> {
        let (earliest, maturity, latest_relevant, pillar, fixing_date, spanning_time) =
            rebuild_dates(|| {
                let (earliest, maturity) = if self.base.update_dates() {
                    let evaluation_date = self.base.evaluation_date().ok_or_else(|| {
                        QlError::new("evaluation date is not set", file!(), line!())
                    })?;
                    let calendar = self.index.fixing_calendar();
                    let spot = calendar.advance(
                        evaluation_date,
                        self.index.fixing_days() as Integer,
                        TimeUnit::Days,
                        BusinessDayConvention::Following,
                        false,
                    );
                    let period_to_start = self
                        .period_to_start
                        .expect("a relative-date FRA helper carries a period to start");
                    let convention = self.index.business_day_convention();
                    let end_of_month = self.index.end_of_month();
                    let earliest =
                        calendar.advance_by_period(spot, period_to_start, convention, end_of_month);
                    let maturity = calendar.advance_by_period(
                        spot,
                        period_to_start + self.index.tenor(),
                        convention,
                        end_of_month,
                    );
                    (earliest, maturity)
                } else {
                    (self.base.earliest_date(), self.base.maturity_date())
                };
                let spanning_time = self.index.day_counter().year_fraction(earliest, maturity);
                let latest_relevant = if self.use_indexed_coupon {
                    self.index.maturity_date(earliest)?
                } else {
                    maturity
                };
                let pillar = self.pillar.resolve(earliest, maturity, latest_relevant)?;
                let fixing_date = self.index.fixing_date(earliest);
                Ok((
                    earliest,
                    maturity,
                    latest_relevant,
                    pillar,
                    fixing_date,
                    spanning_time,
                ))
            })?;
        self.base.set_earliest_date(earliest);
        self.base.set_maturity_date(maturity);
        self.base.set_latest_relevant_date(latest_relevant);

        self.base.set_pillar_date(pillar);
        self.base.set_latest_date(pillar);
        self.fixing_date.set(fixing_date);
        self.spanning_time.set(spanning_time);
        Ok(())
    }
}

/// Bootstrap helper over a par swap rate (`SwapRateHelper`).
///
/// The helper fits the fixed rate at which a spot-starting vanilla swap of the
/// quoted tenor is worth par on the bootstrapping curve. Its own swap is built
/// through [`MakeVanillaSwap`] (`ratehelpers.cpp:557`) off a cloned index and a
/// relinkable discounting handle, so the helper prices against the curve it is
/// being bootstrapped against.
///
/// [`implied_quote`](RateHelper::implied_quote) is **not** the swap's fair rate:
/// it is the par-rate reconstruction of `ratehelpers.cpp:633-646`, over the
/// floating- and fixed-leg NPV and BPS, carrying the spread term that a bare
/// `fair_rate()` would drop. Because the helper deliberately does not observe
/// the curve (its pricing handles are weak-linked, unobserved), the swap's
/// cached results go stale when the bootstrap moves the curve; the C++
/// `swap_->deepUpdate()` forces a fresh calculation each call, and this port
/// reproduces that with [`Instrument::recalculate`] before reading the legs.
///
/// The indexed-vs-at-par coupon mode is not read from a global singleton: the
/// helper carries the C++ `useIndexedCoupons_` `optional<bool>` (default `None`)
/// and forwards it to [`MakeVanillaSwap::with_indexed_coupons`], which resolves
/// `None` against [`Settings::using_at_par_coupons`] (D5, #315/#342).
pub struct SwapRateHelper {
    base: BootstrapHelperBase,
    date_error: RefCell<Option<QlError>>,
    swap: RefCell<Option<VanillaSwap>>,
    ibor_index: Shared<IborIndex>,
    term_structure_handle: RelinkableHandle<dyn YieldTermStructure>,
    discount_relinkable_handle: RelinkableHandle<dyn YieldTermStructure>,
    discount_handle: Option<Handle<dyn YieldTermStructure>>,
    spread: Handle<dyn Quote>,
    settings: Shared<Settings<Date>>,
    tenor: Period,
    forward_start: Period,
    calendar: Calendar,
    fixed_frequency: Frequency,
    fixed_convention: BusinessDayConvention,
    fixed_day_count: DayCounter,
    end_of_month: bool,
    use_indexed_coupons: Option<bool>,
    pillar: Pillar,
}

impl SwapRateHelper {
    /// Builds the helper and returns schedule or custom-pillar errors.
    #[allow(clippy::too_many_arguments)]
    pub fn try_with_details(
        quote: Handle<dyn Quote>,
        tenor: Period,
        calendar: Calendar,
        fixed_frequency: Frequency,
        fixed_convention: BusinessDayConvention,
        fixed_day_count: DayCounter,
        ibor_index: &IborIndex,
        spread: Handle<dyn Quote>,
        forward_start: Period,
        discounting_curve: Option<Handle<dyn YieldTermStructure>>,
        pillar: Pillar,
    ) -> QlResult<Shared<SwapRateHelper>> {
        let helper = Self::with_details(
            quote,
            tenor,
            calendar,
            fixed_frequency,
            fixed_convention,
            fixed_day_count,
            ibor_index,
            spread,
            forward_start,
            discounting_curve,
            pillar,
        );
        helper.validate_dates()?;
        Ok(helper)
    }

    /// Returns the last schedule error, if a date change invalidated the helper.
    pub fn validate_dates(&self) -> QlResult<()> {
        match self.date_error.borrow().as_ref() {
            Some(error) => Err(error.clone()),
            None => Ok(()),
        }
    }

    /// A swap helper fitting `quote` with the schedule of a spot-starting swap
    /// of `tenor`, the form the curve-consistency oracle builds
    /// (`piecewiseyieldcurve.cpp:293`): no spread, no forward start, no exogenous
    /// discounting curve, and the default [`Pillar::LastRelevantDate`].
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        quote: Handle<dyn Quote>,
        tenor: Period,
        calendar: Calendar,
        fixed_frequency: Frequency,
        fixed_convention: BusinessDayConvention,
        fixed_day_count: DayCounter,
        ibor_index: &IborIndex,
    ) -> Shared<SwapRateHelper> {
        Self::build(
            quote,
            tenor,
            calendar,
            fixed_frequency,
            fixed_convention,
            fixed_day_count,
            ibor_index,
            Handle::empty(),
            Period::new(0, TimeUnit::Days),
            None,
            Pillar::LastRelevantDate,
        )
    }

    /// A swap helper fitting a fixed `rate`, wrapped in a [`SimpleQuote`].
    #[allow(clippy::too_many_arguments)]
    pub fn from_rate(
        rate: Real,
        tenor: Period,
        calendar: Calendar,
        fixed_frequency: Frequency,
        fixed_convention: BusinessDayConvention,
        fixed_day_count: DayCounter,
        ibor_index: &IborIndex,
    ) -> Shared<SwapRateHelper> {
        let quote = Handle::new(shared(SimpleQuote::new(rate)) as Shared<dyn Quote>);
        Self::new(
            quote,
            tenor,
            calendar,
            fixed_frequency,
            fixed_convention,
            fixed_day_count,
            ibor_index,
        )
    }

    /// The full constructor of the ported (tenor-based) form: a market `spread`
    /// handle (empty for none), a `forward_start`, an optional exogenous
    /// `discounting_curve`, and the [`Pillar`] choice.
    #[allow(clippy::too_many_arguments)]
    pub fn with_details(
        quote: Handle<dyn Quote>,
        tenor: Period,
        calendar: Calendar,
        fixed_frequency: Frequency,
        fixed_convention: BusinessDayConvention,
        fixed_day_count: DayCounter,
        ibor_index: &IborIndex,
        spread: Handle<dyn Quote>,
        forward_start: Period,
        discounting_curve: Option<Handle<dyn YieldTermStructure>>,
        pillar: Pillar,
    ) -> Shared<SwapRateHelper> {
        Self::build(
            quote,
            tenor,
            calendar,
            fixed_frequency,
            fixed_convention,
            fixed_day_count,
            ibor_index,
            spread,
            forward_start,
            discounting_curve,
            pillar,
        )
    }

    #[allow(clippy::too_many_arguments)]
    fn build(
        quote: Handle<dyn Quote>,
        tenor: Period,
        calendar: Calendar,
        fixed_frequency: Frequency,
        fixed_convention: BusinessDayConvention,
        fixed_day_count: DayCounter,
        source_index: &IborIndex,
        spread: Handle<dyn Quote>,
        forward_start: Period,
        discounting_curve: Option<Handle<dyn YieldTermStructure>>,
        pillar: Pillar,
    ) -> Shared<SwapRateHelper> {
        let settings = source_index.base().settings().clone();
        Shared::new_cyclic(|weak: &Weak<SwapRateHelper>| {
            let weak = weak.clone();
            let on_eval_change = Box::new(move || {
                if let Some(helper) = weak.upgrade() {
                    helper.initialize_dates();
                }
            });
            let term_structure_handle = RelinkableHandle::<dyn YieldTermStructure>::empty();
            let ibor_index = shared(source_index.clone_with(term_structure_handle.handle()));
            let base = BootstrapHelperBase::new_relative(
                quote,
                Shared::clone(&settings),
                true,
                on_eval_change,
            );
            if let Some(discount) = &discounting_curve {
                discount.register_observer(&base.observer());
            }
            spread.register_observer(&base.observer());
            settings.register_fixing_observer(&ibor_index.name(), &base.observer());
            let helper = SwapRateHelper {
                base,
                date_error: RefCell::new(None),
                swap: RefCell::new(None),
                ibor_index,
                term_structure_handle,
                discount_relinkable_handle: RelinkableHandle::<dyn YieldTermStructure>::empty(),
                discount_handle: discounting_curve,
                spread,
                settings,
                tenor,
                forward_start,
                calendar,
                fixed_frequency,
                fixed_convention,
                fixed_day_count,
                end_of_month: false,
                use_indexed_coupons: None,
                pillar,
            };
            helper.initialize_dates();
            helper
        })
    }
}

impl AsObservable for SwapRateHelper {
    fn observable(&self) -> &Observable {
        self.base.observable()
    }
}

impl RateHelper for SwapRateHelper {
    fn base(&self) -> &BootstrapHelperBase {
        &self.base
    }

    /// The par swap rate implied by the current curve
    /// (`ratehelpers.cpp:633-646`).
    ///
    /// The curve is brought up to date before the swap is borrowed, so a stale
    /// curve re-bootstraps without re-entering this helper's borrowed swap; the
    /// rate is then priced on the converged curve, as C++ does through
    /// `LazyObject::calculate` (`lazyobject.hpp:257-258`).
    ///
    /// The swap is force-recalculated first (the C++ `swap_->deepUpdate()`,
    /// forced because the helper does not observe the curve); then the rate is
    /// reconstructed from the floating-leg NPV, the spread carried on the
    /// floating-leg BPS, and the fixed-leg BPS, rather than read from
    /// `fair_rate()`.
    fn implied_quote(&self) -> QlResult<Real> {
        self.validate_dates()?;
        let curve = self.base.term_structure()?;
        curve.discount(0.0, true)?;
        let mut guard = self.swap.borrow_mut();
        let swap = guard
            .as_mut()
            .expect("initialize_dates populates the swap at construction");
        swap.recalculate()?;

        const BASIS_POINT: Real = 1.0e-4;
        let floating_leg_npv = swap.fixed_vs_floating_mut().floating_leg_npv()?;
        let spread = if self.spread.is_empty() {
            0.0
        } else {
            self.spread.current_link()?.value()?
        };
        let spread_npv = swap.fixed_vs_floating_mut().floating_leg_bps()? / BASIS_POINT * spread;
        let total_npv = -(floating_leg_npv + spread_npv);
        let fixed_leg_bps = swap.fixed_vs_floating_mut().fixed_leg_bps()?;
        Ok(total_npv / (fixed_leg_bps / BASIS_POINT))
    }

    /// Weak-links both the forecasting handle (used by the cloned index) and the
    /// discounting handle to the bootstrapping curve - or, when an exogenous
    /// discounting curve was supplied, links the discounting handle to that
    /// instead - then records the curve on the base (`ratehelpers.cpp:614`). All
    /// links are non-owning and unobserved.
    fn set_term_structure(&self, term_structure: &Shared<dyn YieldTermStructure>) {
        self.term_structure_handle
            .link_to_weak(Shared::downgrade(term_structure));
        match &self.discount_handle {
            Some(discount) if !discount.is_empty() => {
                let curve = discount
                    .current_link()
                    .expect("a non-empty discount handle resolves");
                self.discount_relinkable_handle
                    .link_to_weak(Shared::downgrade(&curve));
            }
            _ => self
                .discount_relinkable_handle
                .link_to_weak(Shared::downgrade(term_structure)),
        }
        self.base.set_term_structure(term_structure);
    }
}

impl RelativeDateRateHelper for SwapRateHelper {
    /// Rebuilds the swap and its schedule off the current evaluation date
    /// (`initializeDates`, `ratehelpers.cpp:530`): a spot-starting swap of the
    /// helper's tenor, built through [`MakeVanillaSwap`] with a 0% fixed rate so
    /// it does not price at construction. Earliest and maturity come from the
    /// leg schedules; the pillar follows the [`Pillar`] choice.
    ///
    /// The latest relevant date includes the final floating coupon fixing end.
    fn initialize_dates(&self) {
        *self.date_error.borrow_mut() = self.try_initialize_dates().err();
    }
}

impl SwapRateHelper {
    fn try_initialize_dates(&self) -> QlResult<()> {
        let (swap, earliest, maturity, latest_relevant, pillar) = rebuild_dates(|| {
            let fixed_tenor = if self.fixed_frequency == Frequency::Once {
                self.tenor
            } else {
                Period::try_from(self.fixed_frequency)
                    .expect("a swap's fixed frequency maps to a valid period")
            };
            let swap = MakeVanillaSwap::new(
                self.tenor,
                Shared::clone(&self.ibor_index),
                Some(0.0),
                self.forward_start,
                Shared::clone(&self.settings),
            )
            .with_discounting_term_structure(self.discount_relinkable_handle.handle())
            .with_fixed_leg_day_count(self.fixed_day_count.clone())
            .with_fixed_leg_tenor(fixed_tenor)
            .with_fixed_leg_convention(self.fixed_convention)
            .with_fixed_leg_termination_date_convention(self.fixed_convention)
            .with_fixed_leg_calendar(self.calendar.clone())
            .with_fixed_leg_end_of_month(self.end_of_month)
            .with_floating_leg_calendar(self.calendar.clone())
            .with_floating_leg_end_of_month(self.end_of_month)
            .with_indexed_coupons(self.use_indexed_coupons)
            .build()?;

            let base = swap.fixed_vs_floating();
            let earliest = base
                .fixed_schedule()
                .start_date()
                .min(base.floating_schedule().start_date());
            let maturity = base
                .fixed_schedule()
                .end_date()
                .max(base.floating_schedule().end_date());

            let latest_relevant = maturity.max(swap.last_fixing_end_date()?);
            let pillar = self.pillar.resolve(earliest, maturity, latest_relevant)?;
            Ok((swap, earliest, maturity, latest_relevant, pillar))
        })?;
        self.base.set_earliest_date(earliest);
        self.base.set_maturity_date(maturity);
        self.base.set_latest_relevant_date(latest_relevant);

        self.base.set_pillar_date(pillar);
        self.base.set_latest_date(pillar);

        *self.swap.borrow_mut() = Some(swap);
        Ok(())
    }
}

/// Bootstrap helper over an overnight-indexed-swap (OIS) rate (`OISRateHelper`).
///
/// The helper fits the fixed rate at which an OIS of the quoted tenor is worth
/// par on the bootstrapping curve. Its own swap is built through [`MakeOis`]
/// (`oisratehelper.cpp:130`) off a cloned overnight index and a relinkable
/// discounting handle, so it prices against the curve it is being bootstrapped
/// against.
///
/// [`implied_quote`](RateHelper::implied_quote) is the par-rate reconstruction
/// of `oisratehelper.cpp:220-232` (the same shape as [`SwapRateHelper`]'s, not
/// `fair_rate()`): over the overnight-leg NPV and BPS and the fixed-leg BPS,
/// carrying the spread term. Because the helper deliberately does not observe
/// the curve (its pricing handles are weak-linked, unobserved), the swap's
/// cached results go stale when the bootstrap moves the curve; the C++
/// `swap_->deepUpdate()` forces a fresh calculation each call, reproduced here
/// with [`Instrument::recalculate`] before reading the legs.
pub struct OISRateHelper {
    base: BootstrapHelperBase,
    date_error: RefCell<Option<QlError>>,
    swap: RefCell<Option<OvernightIndexedSwap>>,
    overnight_index: Shared<OvernightIndex>,
    term_structure_handle: RelinkableHandle<dyn YieldTermStructure>,
    discount_relinkable_handle: RelinkableHandle<dyn YieldTermStructure>,
    discount_handle: Option<Handle<dyn YieldTermStructure>>,
    overnight_spread: Handle<dyn Quote>,
    settings: Shared<Settings<Date>>,
    settlement_days: Natural,
    tenor: Period,
    forward_start: Period,
    payment_lag: Integer,
    payment_convention: BusinessDayConvention,
    payment_frequency: Frequency,
    averaging_method: RateAveraging,
    pillar: Pillar,
}

impl OISRateHelper {
    /// Builds the helper and returns schedule or custom-pillar errors.
    #[allow(clippy::too_many_arguments)]
    pub fn try_new(
        settlement_days: Natural,
        tenor: Period,
        quote: Handle<dyn Quote>,
        overnight_index: &OvernightIndex,
        discounting_curve: Option<Handle<dyn YieldTermStructure>>,
        payment_lag: Integer,
        payment_convention: BusinessDayConvention,
        payment_frequency: Frequency,
        forward_start: Period,
        overnight_spread: Handle<dyn Quote>,
        pillar: Pillar,
        averaging_method: RateAveraging,
        settings: Shared<Settings<Date>>,
    ) -> QlResult<Shared<OISRateHelper>> {
        let helper = Self::new(
            settlement_days,
            tenor,
            quote,
            overnight_index,
            discounting_curve,
            payment_lag,
            payment_convention,
            payment_frequency,
            forward_start,
            overnight_spread,
            pillar,
            averaging_method,
            settings,
        );
        helper.validate_dates()?;
        Ok(helper)
    }

    /// Returns the last schedule error, if a date change invalidated the helper.
    pub fn validate_dates(&self) -> QlResult<()> {
        match self.date_error.borrow().as_ref() {
            Some(error) => Err(error.clone()),
            None => Ok(()),
        }
    }

    /// An OIS helper fitting `quote` with the schedule of a swap of `tenor`
    /// starting `settlement_days` after the evaluation date, the form the
    /// bootstrap oracle builds (`overnightindexedswap.cpp:236-256`).
    ///
    /// `discounting_curve` is the exogenous discounting curve (empty `None` to
    /// discount off the bootstrapping curve). `overnight_spread` is the market
    /// spread handle (empty for none). The deferred knobs the C++ constructor
    /// carries past `averaging_method` (telescopic value dates, lookback,
    /// lockout, observation shift, custom pillar, per-leg calendars) take their
    /// benign defaults, mirroring the oracle's positional construction.
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        settlement_days: Natural,
        tenor: Period,
        quote: Handle<dyn Quote>,
        overnight_index: &OvernightIndex,
        discounting_curve: Option<Handle<dyn YieldTermStructure>>,
        payment_lag: Integer,
        payment_convention: BusinessDayConvention,
        payment_frequency: Frequency,
        forward_start: Period,
        overnight_spread: Handle<dyn Quote>,
        pillar: Pillar,
        averaging_method: RateAveraging,
        settings: Shared<Settings<Date>>,
    ) -> Shared<OISRateHelper> {
        Shared::new_cyclic(|weak: &Weak<OISRateHelper>| {
            let weak = weak.clone();
            let on_eval_change = Box::new(move || {
                if let Some(helper) = weak.upgrade() {
                    helper.initialize_dates();
                }
            });
            let term_structure_handle = RelinkableHandle::<dyn YieldTermStructure>::empty();
            let cloned_index = overnight_index.clone_with(term_structure_handle.handle());
            let base = BootstrapHelperBase::new_relative(
                quote,
                Shared::clone(&settings),
                true,
                on_eval_change,
            );
            if let Some(discount) = &discounting_curve {
                discount.register_observer(&base.observer());
            }
            overnight_spread.register_observer(&base.observer());
            settings.register_fixing_observer(&cloned_index.name(), &base.observer());
            let helper = OISRateHelper {
                base,
                date_error: RefCell::new(None),
                swap: RefCell::new(None),
                overnight_index: cloned_index,
                term_structure_handle,
                discount_relinkable_handle: RelinkableHandle::<dyn YieldTermStructure>::empty(),
                discount_handle: discounting_curve,
                overnight_spread,
                settings,
                settlement_days,
                tenor,
                forward_start,
                payment_lag,
                payment_convention,
                payment_frequency,
                averaging_method,
                pillar,
            };
            helper.initialize_dates();
            helper
        })
    }
}

impl AsObservable for OISRateHelper {
    fn observable(&self) -> &Observable {
        self.base.observable()
    }
}

impl RateHelper for OISRateHelper {
    fn base(&self) -> &BootstrapHelperBase {
        &self.base
    }

    /// The par OIS rate implied by the current curve (`oisratehelper.cpp:220-232`).
    ///
    /// The curve is brought up to date before the swap is borrowed, so a stale
    /// curve re-bootstraps without re-entering this helper's borrowed swap; the
    /// rate is then priced on the converged curve, as C++ does through
    /// `LazyObject::calculate` (`lazyobject.hpp:257-258`).
    ///
    /// The swap is force-recalculated first (the C++ `swap_->deepUpdate()`,
    /// forced because the helper does not observe the curve); then the rate is
    /// reconstructed from the overnight-leg NPV, the spread carried on the
    /// overnight-leg BPS, and the fixed-leg BPS, rather than read from
    /// `fair_rate()`.
    fn implied_quote(&self) -> QlResult<Real> {
        self.validate_dates()?;
        let curve = self.base.term_structure()?;
        curve.discount(0.0, true)?;
        let mut guard = self.swap.borrow_mut();
        let swap = guard
            .as_mut()
            .expect("initialize_dates populates the swap at construction");
        swap.recalculate()?;

        const BASIS_POINT: Real = 1.0e-4;
        let overnight_leg_npv = swap.overnight_leg_npv()?;
        let spread = if self.overnight_spread.is_empty() {
            0.0
        } else {
            self.overnight_spread.current_link()?.value()?
        };
        let spread_npv = swap.overnight_leg_bps()? / BASIS_POINT * spread;
        let total_npv = -(overnight_leg_npv + spread_npv);
        let fixed_leg_bps = swap.fixed_vs_floating_mut().fixed_leg_bps()?;
        Ok(total_npv / (fixed_leg_bps / BASIS_POINT))
    }

    /// Weak-links the forecasting handle (used by the cloned overnight index) and
    /// the discounting handle to the bootstrapping curve - or, when an exogenous
    /// discounting curve was supplied, links the discounting handle to that
    /// instead - then records the curve on the base (`oisratehelper.cpp:198-210`).
    /// All links are non-owning and unobserved.
    fn set_term_structure(&self, term_structure: &Shared<dyn YieldTermStructure>) {
        self.term_structure_handle
            .link_to_weak(Shared::downgrade(term_structure));
        match &self.discount_handle {
            Some(discount) if !discount.is_empty() => {
                let curve = discount
                    .current_link()
                    .expect("a non-empty discount handle resolves");
                self.discount_relinkable_handle
                    .link_to_weak(Shared::downgrade(&curve));
            }
            _ => self
                .discount_relinkable_handle
                .link_to_weak(Shared::downgrade(term_structure)),
        }
        self.base.set_term_structure(term_structure);
    }
}

impl RelativeDateRateHelper for OISRateHelper {
    /// Rebuilds the OIS and its schedule off the current evaluation date
    /// (`initializeDates`, `oisratehelper.cpp:128-193`): a swap of the helper's
    /// tenor built through [`MakeOis`]' whole builder chain with a 0% fixed rate
    /// so it does not price at construction.
    ///
    /// The latest relevant date includes payments and the final fixing end.
    fn initialize_dates(&self) {
        *self.date_error.borrow_mut() = self.try_initialize_dates().err();
    }
}

impl OISRateHelper {
    fn try_initialize_dates(&self) -> QlResult<()> {
        let (swap, earliest, maturity, latest_relevant, pillar) = rebuild_dates(|| {
            let swap = MakeOis::new(
                self.tenor,
                Shared::clone(&self.overnight_index),
                Some(0.0),
                self.forward_start,
                Shared::clone(&self.settings),
            )
            .with_discounting_term_structure(self.discount_relinkable_handle.handle())
            .with_telescopic_value_dates(false)
            .with_payment_lag(self.payment_lag)
            .with_payment_adjustment(self.payment_convention)
            .with_payment_frequency(self.payment_frequency)
            .with_averaging_method(self.averaging_method)
            .with_lookback_days(None)
            .with_lockout_days(0)
            .with_rule(DateGeneration::Backward)
            .with_convention(BusinessDayConvention::ModifiedFollowing)
            .with_termination_date_convention(BusinessDayConvention::ModifiedFollowing)
            .with_observation_shift(false)
            .with_settlement_days(self.settlement_days)
            .build()?;

            let base_swap = swap.fixed_vs_floating();
            let earliest = swap
                .overnight_schedule()
                .start_date()
                .min(base_swap.fixed_schedule().start_date());
            let maturity = swap
                .overnight_schedule()
                .end_date()
                .max(base_swap.fixed_schedule().end_date());

            let last_overnight_payment =
                swap.overnight_leg().last().map_or(maturity, |cf| cf.date());
            let last_fixed_payment = base_swap
                .fixed_leg()
                .last()
                .map_or(maturity, |cf| cf.date());
            let latest_relevant = maturity
                .max(last_overnight_payment)
                .max(last_fixed_payment)
                .max(swap.last_fixing_end_date()?);

            let pillar = self.pillar.resolve(earliest, maturity, latest_relevant)?;
            Ok((swap, earliest, maturity, latest_relevant, pillar))
        })?;
        self.base.set_earliest_date(earliest);
        self.base.set_maturity_date(maturity);
        self.base.set_latest_relevant_date(latest_relevant);
        self.base.set_latest_date(latest_relevant);

        self.base.set_pillar_date(pillar);

        *self.swap.borrow_mut() = Some(swap);
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::interestrate::Compounding;
    use crate::math::interpolations::loglinear::LogLinear;
    use crate::settings::Settings;
    use crate::termstructures::bootstraptraits::Discount;
    use crate::termstructures::yields::FlatForward;
    use crate::termstructures::yields::PiecewiseYieldCurve;
    use crate::test_support::{Flag, as_observer, implied_quote_on_dirty_curve};
    use crate::time::calendars::target::Target;
    use crate::time::date::{Date, Month};
    use crate::time::daycounters::actual360::Actual360;
    use crate::time::frequency::Frequency;
    use crate::time::period::Period;
    use crate::time::timeunit::TimeUnit;
    use crate::{currency::Currency, types::Rate};

    fn settings_on(today: Date) -> Shared<Settings<Date>> {
        let settings = shared(Settings::<Date>::new());
        settings.set_evaluation_date(today);
        settings
    }

    fn euribor(
        tenor: Period,
        forwarding: Handle<dyn YieldTermStructure>,
        settings: Shared<Settings<Date>>,
    ) -> IborIndex {
        IborIndex::new(
            "Euribor".into(),
            tenor,
            2,
            Currency::eur(),
            Target::new(),
            BusinessDayConvention::Following,
            false,
            Actual360::new(),
            forwarding,
            settings,
        )
    }

    fn flat_curve(reference: Date, rate: Rate) -> Shared<dyn YieldTermStructure> {
        shared(FlatForward::with_rate(
            reference,
            rate,
            Actual360::new(),
            Compounding::Continuous,
            Frequency::Annual,
        )) as Shared<dyn YieldTermStructure>
    }

    fn today() -> Date {
        Date::new(15, Month::June, 2026)
    }

    /// Standalone oracle: off a flat continuously-compounded curve the implied
    /// deposit rate is the closed-form simple forward `(exp(r*t) - 1)/t` over
    /// the helper's value-to-maturity window, and equals the index fixing path.
    #[test]
    fn implied_quote_matches_closed_form_deposit_rate() {
        let settings = settings_on(today());
        let source = euribor(Period::new(6, TimeUnit::Months), Handle::empty(), settings);
        let helper = DepositRateHelper::from_rate(0.02, &source);

        let rate = 0.03;
        let curve = flat_curve(today(), rate);
        helper.set_term_structure(&curve);

        let d1 = helper.earliest_date();
        let d2 = helper.maturity_date();
        let t = Actual360::new().year_fraction(d1, d2);
        let implied = helper.implied_quote().unwrap();

        let closed_form = ((rate * t).exp() - 1.0) / t;
        assert!((implied - closed_form).abs() < 1e-12);
    }

    /// `initializeDates` derives earliest/maturity/pillar from the index
    /// conventions off the evaluation date (`ratehelpers.cpp:228`).
    #[test]
    fn initialize_dates_follows_the_index_conventions() {
        let settings = settings_on(today());
        let source = euribor(Period::new(6, TimeUnit::Months), Handle::empty(), settings);
        let helper = DepositRateHelper::from_rate(0.02, &source);

        let reference = source
            .fixing_calendar()
            .adjust(today(), BusinessDayConvention::Following);
        let earliest = source.value_date(reference).unwrap();
        let maturity = source.maturity_date(earliest).unwrap();

        assert_eq!(helper.earliest_date(), earliest);
        assert!(earliest > today(), "the value date is spot, past today");
        assert_eq!(helper.maturity_date(), maturity);
        assert_eq!(helper.pillar_date(), maturity);
        assert_eq!(helper.latest_relevant_date(), maturity);
    }

    /// The clone mechanism: the helper forecasts off its OWN handle (the curve
    /// it is bootstrapped against), leaving the source index - here on an empty
    /// handle - untouched.
    #[test]
    fn helper_prices_off_its_own_handle_not_the_source_index() {
        let settings = settings_on(today());
        let source = euribor(Period::new(6, TimeUnit::Months), Handle::empty(), settings);
        let helper = DepositRateHelper::from_rate(0.02, &source);

        let curve = flat_curve(today(), 0.03);
        helper.set_term_structure(&curve);
        let implied_low = helper.implied_quote().unwrap();

        let curve_high = flat_curve(today(), 0.06);
        helper.set_term_structure(&curve_high);
        let implied_high = helper.implied_quote().unwrap();

        assert!(
            implied_high > implied_low,
            "relinking the helper's handle moves its implied quote"
        );
        assert!(
            source.forecast_fixing(helper.earliest_date()).is_err(),
            "the source index's own empty handle is untouched"
        );
    }

    /// `quote_error` is market minus implied.
    #[test]
    fn quote_error_is_market_minus_implied() {
        let settings = settings_on(today());
        let source = euribor(Period::new(6, TimeUnit::Months), Handle::empty(), settings);
        let helper = DepositRateHelper::from_rate(0.05, &source);

        let curve = flat_curve(today(), 0.03);
        helper.set_term_structure(&curve);

        let implied = helper.implied_quote().unwrap();
        assert!((helper.quote_error().unwrap() - (0.05 - implied)).abs() < 1e-15);
    }

    /// An evaluation-date change reruns `initializeDates` and notifies observers.
    #[test]
    fn evaluation_date_change_reinitializes_dates() {
        let settings = settings_on(today());
        let source = euribor(
            Period::new(6, TimeUnit::Months),
            Handle::empty(),
            settings.clone(),
        );
        let helper = DepositRateHelper::from_rate(0.02, &source);
        let before = helper.earliest_date();

        let flag = Flag::new();
        helper.observable().register_observer(&as_observer(&flag));

        let moved = today() + 30;
        settings.set_evaluation_date(moved);

        assert!(Flag::is_up(&flag), "date change must notify observers");
        assert!(
            helper.earliest_date() > before,
            "date change must rerun initialize_dates"
        );
    }

    fn swap_setup() -> (Shared<Settings<Date>>, IborIndex) {
        let settings = settings_on(today());
        let source = euribor(
            Period::new(6, TimeUnit::Months),
            Handle::empty(),
            settings.clone(),
        );
        (settings, source)
    }

    /// Builds the same spot-starting swap the helper builds, directly on `curve`,
    /// for a cross-implementation identity: a separate [`MakeVanillaSwap`]
    /// instance priced by its own [`DiscountingSwapEngine`].
    fn independent_swap(
        source: &IborIndex,
        tenor: Period,
        calendar: Calendar,
        convention: BusinessDayConvention,
        curve: &Shared<dyn YieldTermStructure>,
        settings: Shared<Settings<Date>>,
    ) -> VanillaSwap {
        let curve_handle = Handle::new(Shared::clone(curve));
        let index = shared(source.clone_with(curve_handle.clone()));
        MakeVanillaSwap::new(
            tenor,
            index,
            Some(0.0),
            Period::new(0, TimeUnit::Days),
            settings,
        )
        .with_discounting_term_structure(curve_handle)
        .with_fixed_leg_day_count(Actual360::new())
        .with_fixed_leg_tenor(Period::try_from(Frequency::Annual).unwrap())
        .with_fixed_leg_convention(convention)
        .with_fixed_leg_termination_date_convention(convention)
        .with_fixed_leg_calendar(calendar.clone())
        .with_fixed_leg_end_of_month(false)
        .with_floating_leg_calendar(calendar)
        .with_floating_leg_end_of_month(false)
        .build()
        .unwrap()
    }

    /// With no spread, the reconstructed `implied_quote` equals the fair rate of
    /// the same swap computed independently - the par-rate formula reduces to the
    /// fair rate exactly.
    #[test]
    fn implied_quote_matches_fair_rate_of_the_same_swap() {
        let (settings, source) = swap_setup();
        let tenor = Period::new(5, TimeUnit::Years);
        let calendar = Target::new();
        let convention = BusinessDayConvention::ModifiedFollowing;
        let helper = SwapRateHelper::from_rate(
            0.02,
            tenor,
            calendar.clone(),
            Frequency::Annual,
            convention,
            Actual360::new(),
            &source,
        );
        let curve = flat_curve(today(), 0.03);
        helper.set_term_structure(&curve);

        let implied = helper.implied_quote().unwrap();
        let mut independent =
            independent_swap(&source, tenor, calendar, convention, &curve, settings);
        let fair = independent.fixed_vs_floating_mut().fair_rate().unwrap();
        assert!(
            (implied - fair).abs() < 1e-12,
            "implied {implied} vs fair {fair}"
        );
    }

    /// A nonzero spread shifts the implied quote off the fair rate by exactly
    /// `spread * floatingLegBPS / fixedLegBPS` (BPS from an independent swap) -
    /// the term a bare `fair_rate()` would drop.
    #[test]
    fn nonzero_spread_shifts_the_implied_quote_by_the_bps_ratio() {
        let (settings, source) = swap_setup();
        let tenor = Period::new(5, TimeUnit::Years);
        let calendar = Target::new();
        let convention = BusinessDayConvention::ModifiedFollowing;
        let curve = flat_curve(today(), 0.03);

        let helper0 = SwapRateHelper::from_rate(
            0.02,
            tenor,
            calendar.clone(),
            Frequency::Annual,
            convention,
            Actual360::new(),
            &source,
        );
        helper0.set_term_structure(&curve);
        let implied0 = helper0.implied_quote().unwrap();

        let spread = 0.001;
        let spread_handle = Handle::new(shared(SimpleQuote::new(spread)) as Shared<dyn Quote>);
        let helper_s = SwapRateHelper::with_details(
            Handle::new(shared(SimpleQuote::new(0.02)) as Shared<dyn Quote>),
            tenor,
            calendar.clone(),
            Frequency::Annual,
            convention,
            Actual360::new(),
            &source,
            spread_handle,
            Period::new(0, TimeUnit::Days),
            None,
            Pillar::LastRelevantDate,
        );
        helper_s.set_term_structure(&curve);
        let implied_s = helper_s.implied_quote().unwrap();

        assert!(
            (implied_s - implied0).abs() > 1e-8,
            "the spread must move the implied quote"
        );

        let mut independent =
            independent_swap(&source, tenor, calendar, convention, &curve, settings);
        let floating_bps = independent
            .fixed_vs_floating_mut()
            .floating_leg_bps()
            .unwrap();
        let fixed_bps = independent.fixed_vs_floating_mut().fixed_leg_bps().unwrap();
        let expected = implied0 - spread * floating_bps / fixed_bps;
        assert!(
            (implied_s - expected).abs() < 1e-12,
            "implied_s {implied_s} vs expected {expected}"
        );
    }

    /// The forced recalculation: moving the curve (mutating its underlying quote,
    /// not relinking) changes the implied quote even though the helper never
    /// observes the curve and receives no notification - proving `implied_quote`
    /// forces a fresh calculation rather than reading a stale cache.
    #[test]
    fn moving_the_curve_updates_the_quote_without_notifying_the_helper() {
        let (_settings, source) = swap_setup();
        let tenor = Period::new(5, TimeUnit::Years);
        let helper = SwapRateHelper::from_rate(
            0.02,
            tenor,
            Target::new(),
            Frequency::Annual,
            BusinessDayConvention::ModifiedFollowing,
            Actual360::new(),
            &source,
        );

        let quote = shared(SimpleQuote::new(0.03));
        let curve: Shared<dyn YieldTermStructure> = shared(FlatForward::new(
            today(),
            Handle::new(Shared::clone(&quote) as Shared<dyn Quote>),
            Actual360::new(),
            Compounding::Continuous,
            Frequency::Annual,
        ));
        helper.set_term_structure(&curve);
        let implied_before = helper.implied_quote().unwrap();

        let flag = Flag::new();
        helper.observable().register_observer(&as_observer(&flag));

        quote.set_value(0.05);
        assert!(
            !Flag::is_up(&flag),
            "the helper must not observe the bootstrapping curve"
        );

        let implied_after = helper.implied_quote().unwrap();
        assert!(
            (implied_after - implied_before).abs() > 1e-6,
            "the forced recalculation must surface the curve move without a notification"
        );
    }

    /// `initialize_dates` builds a spot-starting swap and the pillar follows the
    /// [`Pillar`] choice.
    #[test]
    fn initialize_dates_spot_starts_and_pillar_follows_the_choice() {
        let (_settings, source) = swap_setup();
        let tenor = Period::new(5, TimeUnit::Years);
        let helper = SwapRateHelper::with_details(
            Handle::new(shared(SimpleQuote::new(0.02)) as Shared<dyn Quote>),
            tenor,
            Target::new(),
            Frequency::Annual,
            BusinessDayConvention::ModifiedFollowing,
            Actual360::new(),
            &source,
            Handle::empty(),
            Period::new(0, TimeUnit::Days),
            None,
            Pillar::MaturityDate,
        );
        assert!(
            helper.earliest_date() > today(),
            "the swap starts spot, past today"
        );
        assert!(helper.maturity_date() > helper.earliest_date());
        assert_eq!(
            helper.pillar_date(),
            helper.maturity_date(),
            "the MaturityDate pillar equals the maturity"
        );
    }

    /// `quote_error` is market minus implied.
    #[test]
    fn swap_quote_error_is_market_minus_implied() {
        let (_settings, source) = swap_setup();
        let tenor = Period::new(5, TimeUnit::Years);
        let helper = SwapRateHelper::from_rate(
            0.05,
            tenor,
            Target::new(),
            Frequency::Annual,
            BusinessDayConvention::ModifiedFollowing,
            Actual360::new(),
            &source,
        );
        let curve = flat_curve(today(), 0.03);
        helper.set_term_structure(&curve);

        let implied = helper.implied_quote().unwrap();
        assert!((helper.quote_error().unwrap() - (0.05 - implied)).abs() < 1e-15);
    }

    /// Bootstraps a curve through the helper `build` makes on an exogenous
    /// discounting curve backed by a [`SimpleQuote`], moves that quote, and
    /// checks the existing curve re-bootstraps to the same discount factor as a
    /// curve built fresh on the moved quote (`ratehelpers.cpp:544`,
    /// `oisratehelper.cpp:119`). Without the helper observing its discounting
    /// handle the existing curve stays stale.
    fn assert_curve_tracks_exogenous_discount(
        build: impl Fn(Handle<dyn YieldTermStructure>) -> Shared<dyn RateHelper>,
    ) {
        let discount_curve = |quote: &Shared<SimpleQuote>| {
            Handle::new(shared(FlatForward::new(
                today(),
                Handle::new(Shared::clone(quote) as Shared<dyn Quote>),
                Actual360::new(),
                Compounding::Continuous,
                Frequency::Annual,
            )) as Shared<dyn YieldTermStructure>)
        };
        let bootstrap = |helper: Shared<dyn RateHelper>| {
            let maturity = helper.maturity_date();
            let curve = PiecewiseYieldCurve::<Discount, LogLinear>::new(
                today(),
                vec![helper],
                Actual360::new(),
                LogLinear,
            )
            .unwrap();
            (curve, maturity)
        };

        let quote = shared(SimpleQuote::new(0.01));
        let (curve, maturity) = bootstrap(build(discount_curve(&quote)));
        let before = curve.discount_date(maturity, false).unwrap();

        quote.set_value(0.05);
        let moved = curve.discount_date(maturity, false).unwrap();

        let fresh_quote = shared(SimpleQuote::new(0.05));
        let (fresh_curve, _) = bootstrap(build(discount_curve(&fresh_quote)));
        let fresh = fresh_curve.discount_date(maturity, false).unwrap();

        assert!(
            (fresh - before).abs() > 1e-8,
            "degenerate fixture: the discounting curve does not move the bootstrap"
        );
        assert!(
            (moved - fresh).abs() < 1e-12,
            "stale curve after the discounting quote moved: {moved} vs fresh {fresh}"
        );
    }

    #[test]
    fn swap_helper_observes_its_exogenous_discounting_curve() {
        let (_settings, source) = swap_setup();
        assert_curve_tracks_exogenous_discount(|discount| {
            SwapRateHelper::with_details(
                Handle::new(shared(SimpleQuote::new(0.03)) as Shared<dyn Quote>),
                Period::new(5, TimeUnit::Years),
                Target::new(),
                Frequency::Annual,
                BusinessDayConvention::ModifiedFollowing,
                Actual360::new(),
                &source,
                Handle::empty(),
                Period::new(0, TimeUnit::Days),
                Some(discount),
                Pillar::LastRelevantDate,
            ) as Shared<dyn RateHelper>
        });
    }

    /// Bootstraps a curve through a [`SwapRateHelper`] carrying a market spread,
    /// moves the spread, and checks the existing curve re-bootstraps to the same
    /// discount factor as a curve built fresh on the moved spread
    /// (`ratehelpers.cpp:543`). The spread is observed even through a handle
    /// that is empty at construction and linked later, as C++ `registerWith`
    /// registers an empty handle.
    #[test]
    fn swap_helper_observes_its_spread() {
        let (_settings, source) = swap_setup();
        let bootstrap = |spread: Handle<dyn Quote>| {
            let helper = SwapRateHelper::with_details(
                Handle::new(shared(SimpleQuote::new(0.03)) as Shared<dyn Quote>),
                Period::new(5, TimeUnit::Years),
                Target::new(),
                Frequency::Annual,
                BusinessDayConvention::ModifiedFollowing,
                Actual360::new(),
                &source,
                spread,
                Period::new(0, TimeUnit::Days),
                None,
                Pillar::LastRelevantDate,
            );
            let maturity = helper.maturity_date();
            let curve = PiecewiseYieldCurve::<Discount, LogLinear>::new(
                today(),
                vec![helper as Shared<dyn RateHelper>],
                Actual360::new(),
                LogLinear,
            )
            .unwrap();
            (curve, maturity)
        };
        let quote_handle =
            |value: Real| Handle::new(shared(SimpleQuote::new(value)) as Shared<dyn Quote>);

        let spread = shared(SimpleQuote::new(0.001));
        let (curve, maturity) = bootstrap(Handle::new(Shared::clone(&spread) as Shared<dyn Quote>));
        let before = curve.discount_date(maturity, false).unwrap();
        spread.set_value(0.004);
        let moved = curve.discount_date(maturity, false).unwrap();
        let (fresh_curve, _) = bootstrap(quote_handle(0.004));
        let fresh = fresh_curve.discount_date(maturity, false).unwrap();
        assert!(
            (fresh - before).abs() > 1e-6,
            "degenerate fixture: the spread does not move the bootstrap"
        );
        assert!(
            (moved - fresh).abs() < 1e-12,
            "stale curve after the spread moved: {moved} vs fresh {fresh}"
        );

        let relinkable = RelinkableHandle::<dyn Quote>::empty();
        let (curve, _) = bootstrap(relinkable.handle());
        let unspread = curve.discount_date(maturity, false).unwrap();
        relinkable.link_to(shared(SimpleQuote::new(0.004)) as Shared<dyn Quote>);
        let linked = curve.discount_date(maturity, false).unwrap();
        assert!((unspread - fresh).abs() > 1e-6);
        assert!(
            (linked - fresh).abs() < 1e-12,
            "stale curve after linking the spread: {linked} vs fresh {fresh}"
        );
    }

    /// Bootstraps a curve through the helper `build` makes, records a fixing
    /// dated on the evaluation date (the first floating coupon's fixing), and
    /// checks the existing curve re-bootstraps to the same discount factor as a
    /// curve built fresh with that fixing present (`ratehelpers.cpp:542`,
    /// `oisratehelper.cpp:118`). Without the helper observing the fixing
    /// history the existing curve stays stale.
    fn assert_curve_tracks_todays_fixing(
        build: impl Fn() -> Shared<dyn RateHelper>,
        add_fixing: impl FnOnce(),
    ) {
        let bootstrap = || {
            let helper = build();
            let maturity = helper.maturity_date();
            let curve = PiecewiseYieldCurve::<Discount, LogLinear>::new(
                today(),
                vec![helper],
                Actual360::new(),
                LogLinear,
            )
            .unwrap();
            (curve, maturity)
        };

        let (curve, maturity) = bootstrap();
        let before = curve.discount_date(maturity, false).unwrap();
        add_fixing();
        let moved = curve.discount_date(maturity, false).unwrap();
        let (fresh_curve, _) = bootstrap();
        let fresh = fresh_curve.discount_date(maturity, false).unwrap();

        assert!(
            (fresh - before).abs() > 1e-6,
            "degenerate fixture: today's fixing does not move the bootstrap"
        );
        assert!(
            (moved - fresh).abs() < 1e-12,
            "stale curve after today's fixing: {moved} vs fresh {fresh}"
        );
    }

    fn five_year_swap_helper(source: &IborIndex) -> Shared<SwapRateHelper> {
        SwapRateHelper::with_details(
            Handle::new(shared(SimpleQuote::new(0.03)) as Shared<dyn Quote>),
            Period::new(5, TimeUnit::Years),
            Target::new(),
            Frequency::Annual,
            BusinessDayConvention::ModifiedFollowing,
            Actual360::new(),
            source,
            Handle::empty(),
            Period::new(0, TimeUnit::Days),
            None,
            Pillar::LastRelevantDate,
        )
    }

    #[test]
    fn swap_helper_observes_todays_fixing() {
        let (_settings, source) = swap_setup();
        assert_curve_tracks_todays_fixing(
            || five_year_swap_helper(&source) as Shared<dyn RateHelper>,
            || source.add_fixing(today(), 0.08).unwrap(),
        );
    }

    #[test]
    fn ois_helper_observes_todays_fixing() {
        use crate::indexes::ibor::Estr;

        let settings = settings_on(today());
        let estr = Estr::new(Handle::empty(), settings.clone());
        assert_curve_tracks_todays_fixing(
            || {
                OISRateHelper::new(
                    0,
                    Period::new(1, TimeUnit::Months),
                    Handle::new(shared(SimpleQuote::new(0.03)) as Shared<dyn Quote>),
                    &estr,
                    None,
                    0,
                    BusinessDayConvention::Following,
                    Frequency::Annual,
                    Period::new(0, TimeUnit::Days),
                    Handle::empty(),
                    Pillar::LastRelevantDate,
                    RateAveraging::Compound,
                    settings.clone(),
                ) as Shared<dyn RateHelper>
            },
            || estr.add_fixing(today(), 0.08).unwrap(),
        );
    }

    /// A direct `implied_quote()` on a dirty curve re-bootstraps first and
    /// prices on the converged curve, as C++ does (`lazyobject.hpp:257-258`),
    /// rather than re-borrowing the swap from inside the nested bootstrap.
    #[test]
    fn swap_implied_quote_on_a_dirty_curve_reprices_the_new_quote() {
        let (_settings, source) = swap_setup();
        let (dirty, fresh) = implied_quote_on_dirty_curve(today(), 0.03, 0.04, |quote| {
            SwapRateHelper::with_details(
                quote,
                Period::new(1, TimeUnit::Years),
                Target::new(),
                Frequency::Annual,
                BusinessDayConvention::ModifiedFollowing,
                Actual360::new(),
                &source,
                Handle::empty(),
                Period::new(0, TimeUnit::Days),
                None,
                Pillar::LastRelevantDate,
            ) as Shared<dyn RateHelper>
        });
        assert!((dirty - fresh).abs() < 1e-10, "{dirty} vs {fresh}");
        assert!((dirty - 0.04).abs() < 1e-9, "{dirty}");
    }

    #[test]
    fn ois_implied_quote_on_a_dirty_curve_reprices_the_new_quote() {
        use crate::indexes::ibor::Estr;

        let settings = settings_on(today());
        let estr = Estr::new(Handle::empty(), settings.clone());
        let (dirty, fresh) = implied_quote_on_dirty_curve(today(), 0.03, 0.04, |quote| {
            OISRateHelper::new(
                2,
                Period::new(1, TimeUnit::Years),
                quote,
                &estr,
                None,
                0,
                BusinessDayConvention::Following,
                Frequency::Annual,
                Period::new(0, TimeUnit::Days),
                Handle::empty(),
                Pillar::LastRelevantDate,
                RateAveraging::Compound,
                settings.clone(),
            ) as Shared<dyn RateHelper>
        });
        assert!((dirty - fresh).abs() < 1e-10, "{dirty} vs {fresh}");
        assert!((dirty - 0.04).abs() < 1e-9, "{dirty}");
    }

    /// The FRA helper is notified of a fixing (`ratehelpers.cpp:318`), and so
    /// invalidates the curve, but its value cannot move: the indexed quote
    /// forecasts even today's fixing (`ratehelpers.cpp:364`) and the par quote
    /// reads discount factors only.
    #[test]
    fn fra_helper_observes_fixings_without_moving_the_curve() {
        let (_settings, source) = swap_setup();
        let helper = FraRateHelper::new(
            Handle::new(shared(SimpleQuote::new(0.03)) as Shared<dyn Quote>),
            Period::new(0, TimeUnit::Months),
            &source,
            true,
            Pillar::LastRelevantDate,
        );
        let curve = PiecewiseYieldCurve::<Discount, LogLinear>::new(
            today(),
            vec![Shared::clone(&helper) as Shared<dyn RateHelper>],
            Actual360::new(),
            LogLinear,
        )
        .unwrap();
        let maturity = helper.maturity_date();
        let before = curve.discount_date(maturity, false).unwrap();
        let helper_flag = Flag::new();
        let curve_flag = Flag::new();
        helper
            .observable()
            .register_observer(&as_observer(&helper_flag));
        curve.register_observer(&as_observer(&curve_flag));

        source.add_fixing(today(), 0.08).unwrap();

        assert!(Flag::is_up(&helper_flag), "a fixing must notify the helper");
        assert!(
            Flag::is_up(&curve_flag),
            "a fixing must invalidate the curve"
        );
        let after = curve.discount_date(maturity, false).unwrap();
        assert!((after - before).abs() < 1e-12);
    }

    /// Relinking the source index's forwarding handle to the curve the helper
    /// bootstraps, and away again, neither notifies the helper nor loops; a
    /// fixing still reaches it through the fixing history.
    #[test]
    fn swap_helper_relinks_do_not_loop_and_fixings_still_notify() {
        let settings = settings_on(today());
        let forwarding = RelinkableHandle::<dyn YieldTermStructure>::empty();
        let source = euribor(
            Period::new(6, TimeUnit::Months),
            forwarding.handle(),
            settings,
        );
        let helper = five_year_swap_helper(&source);
        let curve = PiecewiseYieldCurve::<Discount, LogLinear>::new(
            today(),
            vec![Shared::clone(&helper) as Shared<dyn RateHelper>],
            Actual360::new(),
            LogLinear,
        )
        .unwrap();
        let maturity = helper.maturity_date();
        let flag = Flag::new();
        helper.observable().register_observer(&as_observer(&flag));

        forwarding.link_to(Shared::clone(&curve) as Shared<dyn YieldTermStructure>);
        let linked = curve.discount_date(maturity, false).unwrap();
        forwarding.link_to(flat_curve(today(), 0.04));
        let relinked = curve.discount_date(maturity, false).unwrap();
        assert!(!Flag::is_up(&flag), "a relink must not notify the helper");
        assert!((linked - relinked).abs() < 1e-12);

        forwarding.link_to(Shared::clone(&curve) as Shared<dyn YieldTermStructure>);
        source.add_fixing(today(), 0.08).unwrap();
        assert!(Flag::is_up(&flag), "a fixing must notify the helper");
        let fixed = curve.discount_date(maturity, false).unwrap();
        assert!((fixed - linked).abs() > 1e-6);
    }

    #[test]
    fn ois_helper_observes_its_exogenous_discounting_curve() {
        use crate::indexes::ibor::Estr;

        let settings = settings_on(today());
        let estr = Estr::new(Handle::empty(), settings.clone());
        assert_curve_tracks_exogenous_discount(|discount| {
            OISRateHelper::new(
                2,
                Period::new(5, TimeUnit::Years),
                Handle::new(shared(SimpleQuote::new(0.03)) as Shared<dyn Quote>),
                &estr,
                Some(discount),
                2,
                BusinessDayConvention::Following,
                Frequency::Annual,
                Period::new(0, TimeUnit::Days),
                Handle::empty(),
                Pillar::LastRelevantDate,
                RateAveraging::Compound,
                settings.clone(),
            ) as Shared<dyn RateHelper>
        });
    }

    /// QuantLib 1.43 values from `tests/fixtures/overnight_averaging/bindings.json`.
    #[test]
    fn ois_spread_updates_rebootstrap_without_retaining_the_curve() {
        use crate::indexes::ibor::Estr;
        use crate::math::interpolations::loglinear::LogLinear;
        use crate::termstructures::bootstraptraits::Discount;
        use crate::termstructures::yields::PiecewiseYieldCurve;

        for (averaging, initial_discount, updated_discount) in [
            (
                RateAveraging::Compound,
                0.9533435978894659,
                0.9542712749129756,
            ),
            (
                RateAveraging::Simple,
                0.9522505927886751,
                0.9532216074564187,
            ),
        ] {
            let reference = Date::new(7, Month::July, 2026);
            let settings = settings_on(reference);
            let index = Estr::new(Handle::empty(), settings.clone());
            let spread = shared(SimpleQuote::new(0.002));
            let spread_handle = RelinkableHandle::new(spread.clone() as Shared<dyn Quote>);
            let helper = OISRateHelper::new(
                2,
                Period::new(1, TimeUnit::Years),
                Handle::new(shared(SimpleQuote::new(0.05)) as Shared<dyn Quote>),
                &index,
                None,
                2,
                BusinessDayConvention::Following,
                Frequency::Annual,
                Period::new(0, TimeUnit::Days),
                spread_handle.handle(),
                Pillar::LastRelevantDate,
                averaging,
                settings,
            );
            let curve = PiecewiseYieldCurve::<Discount, LogLinear>::new(
                reference,
                vec![helper.clone() as Shared<dyn RateHelper>],
                Actual360::new(),
                LogLinear,
            )
            .unwrap();
            let maturity = helper.maturity_date();
            assert!(
                (curve.discount_date(maturity, false).unwrap() - initial_discount).abs() < 1e-12
            );
            spread.set_value(0.003);
            assert!(
                (curve.discount_date(maturity, false).unwrap() - updated_discount).abs() < 1e-12
            );
            assert!((helper.implied_quote().unwrap() - 0.05).abs() < 1e-12);
            spread_handle.link_to(shared(SimpleQuote::new(0.002)) as Shared<dyn Quote>);
            assert!(
                (curve.discount_date(maturity, false).unwrap() - initial_discount).abs() < 1e-12
            );
            let weak_helper = Shared::downgrade(&helper);
            let weak_curve = Shared::downgrade(&curve);
            drop(helper);
            drop(curve);
            assert!(weak_helper.upgrade().is_none());
            assert!(weak_curve.upgrade().is_none());
            spread.set_value(0.004);
        }
    }

    /// `overnightindexedswap.cpp estrSwapData` (`:92-125`): the OIS quotes the
    /// bootstrap oracle fits, `(tenor length, unit, rate %)`; all use two
    /// settlement days.
    const ESTR_SWAP_DATA: [(i32, TimeUnit, Real); 33] = [
        (1, TimeUnit::Weeks, 1.245),
        (2, TimeUnit::Weeks, 1.269),
        (3, TimeUnit::Weeks, 1.277),
        (1, TimeUnit::Months, 1.281),
        (2, TimeUnit::Months, 1.18),
        (3, TimeUnit::Months, 1.143),
        (4, TimeUnit::Months, 1.125),
        (5, TimeUnit::Months, 1.116),
        (6, TimeUnit::Months, 1.111),
        (7, TimeUnit::Months, 1.109),
        (8, TimeUnit::Months, 1.111),
        (9, TimeUnit::Months, 1.117),
        (10, TimeUnit::Months, 1.129),
        (11, TimeUnit::Months, 1.141),
        (12, TimeUnit::Months, 1.153),
        (15, TimeUnit::Months, 1.218),
        (18, TimeUnit::Months, 1.308),
        (21, TimeUnit::Months, 1.407),
        (2, TimeUnit::Years, 1.510),
        (3, TimeUnit::Years, 1.916),
        (4, TimeUnit::Years, 2.254),
        (5, TimeUnit::Years, 2.523),
        (6, TimeUnit::Years, 2.746),
        (7, TimeUnit::Years, 2.934),
        (8, TimeUnit::Years, 3.092),
        (9, TimeUnit::Years, 3.231),
        (10, TimeUnit::Years, 3.380),
        (11, TimeUnit::Years, 3.457),
        (12, TimeUnit::Years, 3.544),
        (15, TimeUnit::Years, 3.702),
        (20, TimeUnit::Years, 3.703),
        (25, TimeUnit::Years, 3.541),
        (30, TimeUnit::Years, 3.369),
    ];

    /// `overnightindexedswap.cpp testBaseBootstrap` (`:397` ->
    /// `testBootstrap(false, RateAveraging::Compound)`, `:208`): an Estr
    /// discounting curve bootstrapped purely from [`OISRateHelper`]s reprices
    /// every OIS quote to 1e-8.
    ///
    /// The deposit helpers of the C++ setup are omitted deliberately: for a zero
    /// spread `implied_quote == fair_rate`, and each swap tenor is self-pinned by
    /// its own OIS node solved so `implied_quote_i == quote_i`, so
    /// `fair_rate_i == quote_i` to solver accuracy independent of the sub-week
    /// short end the deposits shape. `paymentLag = 2` and `today = 5 Feb 2009`
    /// are transcribed from `CommonVars` / `testBootstrap` (`:180-215`).
    ///
    /// The three sibling cases stay deferred: `testBootstrapWithArithmeticAverage`
    /// (`:402`) needs the arithmetic-averaging pricer, and the two telescopic
    /// cases (`:407`/`:413`) need telescopic value dates - neither on main.
    #[test]
    fn ois_bootstrap_reprices_the_quotes() {
        use crate::indexes::ibor::Estr;
        use crate::math::interpolations::loglinear::LogLinear;
        use crate::termstructures::bootstraptraits::Discount;
        use crate::termstructures::yields::PiecewiseYieldCurve;
        use crate::time::daycounters::actual365fixed::Actual365Fixed;

        const PAYMENT_LAG: Integer = 2;
        let today = Date::new(5, Month::February, 2009);
        let settings = settings_on(today);
        let calendar = Target::new();
        let settlement = calendar.advance(
            today,
            2,
            TimeUnit::Days,
            BusinessDayConvention::Following,
            false,
        );

        let estr = Estr::new(Handle::empty(), settings.clone());
        let mut instruments: Vec<Shared<dyn RateHelper>> = Vec::new();
        for (n, unit, rate) in ESTR_SWAP_DATA {
            let quote = Handle::new(shared(SimpleQuote::new(rate / 100.0)) as Shared<dyn Quote>);
            let helper = OISRateHelper::new(
                2,
                Period::new(n, unit),
                quote,
                &estr,
                None,
                PAYMENT_LAG,
                BusinessDayConvention::Following,
                Frequency::Annual,
                Period::new(0, TimeUnit::Days),
                Handle::empty(),
                Pillar::LastRelevantDate,
                RateAveraging::Compound,
                settings.clone(),
            );
            instruments.push(helper as Shared<dyn RateHelper>);
        }

        let curve = PiecewiseYieldCurve::<Discount, LogLinear>::new(
            today,
            instruments,
            Actual365Fixed::new(),
            LogLinear,
        )
        .unwrap();
        let handle: Handle<dyn YieldTermStructure> =
            Handle::new(Shared::clone(&curve) as Shared<dyn YieldTermStructure>);

        for (n, unit, rate) in ESTR_SWAP_DATA {
            let priced_estr = shared(Estr::new(handle.clone(), settings.clone()));
            let mut swap = MakeOis::new(
                Period::new(n, unit),
                priced_estr,
                Some(0.0),
                Period::new(0, TimeUnit::Days),
                settings.clone(),
            )
            .with_effective_date(settlement)
            .with_nominal(100.0)
            .with_payment_lag(PAYMENT_LAG)
            .with_discounting_term_structure(handle.clone())
            .with_averaging_method(RateAveraging::Compound)
            .build()
            .unwrap();

            let calculated = swap.fixed_vs_floating_mut().fair_rate().unwrap();
            let expected = rate / 100.0;
            assert!(
                (calculated - expected).abs() < 1.0e-8,
                "{n} {unit:?} OIS: calculated {calculated} vs expected {expected}"
            );
        }
    }

    fn quote_handle(value: Real) -> Handle<dyn Quote> {
        Handle::new(shared(SimpleQuote::new(value)) as Shared<dyn Quote>)
    }

    /// The convexity-shift pin (`ratehelpers.cpp:157`): two curves bootstrapped
    /// through a single [`FuturesRateHelper`] at the same price, one with zero
    /// convexity and one with `c`, produce forwards that differ by exactly `c`.
    ///
    /// Non-circular: the bootstrap only pins `implied_quote == price` at the
    /// pillar, which fixes `forward = (100 - price)/100 - conv_adj` per curve, so
    /// `forward_c == forward_0 - c` is a property of the convexity term itself,
    /// independent of the discount interpolation. Stubbing
    /// `convexity_adjustment()` to zero collapses both curves onto the same
    /// forward and this assertion fails.
    #[test]
    fn convexity_adjustment_shifts_the_bootstrapped_forward() {
        use crate::math::interpolations::loglinear::LogLinear;
        use crate::termstructures::bootstraptraits::Discount;
        use crate::termstructures::yields::PiecewiseYieldCurve;
        use crate::time::daycounters::actual365fixed::Actual365Fixed;

        let reference = today();
        let imm_start = imm::next_date(reference, false);
        let price = 96.0;
        let c = 0.001;

        let forward_from = |conv_adj: Handle<dyn Quote>| -> Real {
            let helper = FuturesRateHelper::from_end_date(
                quote_handle(price),
                imm_start,
                None,
                Actual360::new(),
                conv_adj,
                FuturesType::Imm,
            )
            .unwrap();
            let earliest = helper.earliest_date();
            let maturity = helper.maturity_date();
            let instruments: Vec<Shared<dyn RateHelper>> = vec![helper as Shared<dyn RateHelper>];
            let curve = PiecewiseYieldCurve::<Discount, LogLinear>::new(
                reference,
                instruments,
                Actual365Fixed::new(),
                LogLinear,
            )
            .unwrap();
            let disc_e = curve.discount_date(earliest, false).unwrap();
            let disc_m = curve.discount_date(maturity, false).unwrap();
            let yf = Actual360::new().year_fraction_ref(earliest, maturity, earliest, maturity);
            (disc_e / disc_m - 1.0) / yf
        };

        let forward_0 = forward_from(Handle::empty());
        let forward_c = forward_from(quote_handle(c));
        assert!(
            (forward_c - (forward_0 - c)).abs() < 1e-10,
            "forward_c {forward_c} vs forward_0 - c {}",
            forward_0 - c
        );
    }

    /// The bootstrap reprices the futures quote (`ratehelpers.cpp:157`): the
    /// forward recomputed from the bootstrapped discounts reproduces the quoted
    /// price through `100 * (1 - forward - conv_adj)`, and [`implied_quote`] on
    /// the fitted curve returns the price to solver accuracy.
    ///
    /// [`implied_quote`]: RateHelper::implied_quote
    #[test]
    fn bootstrap_reprices_the_futures_quote() {
        use crate::math::interpolations::loglinear::LogLinear;
        use crate::termstructures::bootstraptraits::Discount;
        use crate::termstructures::yields::PiecewiseYieldCurve;
        use crate::time::daycounters::actual365fixed::Actual365Fixed;

        let reference = today();
        let imm_start = imm::next_date(reference, false);
        let price = 96.0;
        let c = 0.001;
        let helper = FuturesRateHelper::from_end_date(
            quote_handle(price),
            imm_start,
            None,
            Actual360::new(),
            quote_handle(c),
            FuturesType::Imm,
        )
        .unwrap();
        let earliest = helper.earliest_date();
        let maturity = helper.maturity_date();
        let instruments: Vec<Shared<dyn RateHelper>> =
            vec![Shared::clone(&helper) as Shared<dyn RateHelper>];
        let curve = PiecewiseYieldCurve::<Discount, LogLinear>::new(
            reference,
            instruments,
            Actual365Fixed::new(),
            LogLinear,
        )
        .unwrap();

        let disc_e = curve.discount_date(earliest, false).unwrap();
        let disc_m = curve.discount_date(maturity, false).unwrap();
        let yf = Actual360::new().year_fraction_ref(earliest, maturity, earliest, maturity);
        let forward = (disc_e / disc_m - 1.0) / yf;
        let repriced = 100.0 * (1.0 - forward - c);
        assert!(
            (repriced - price).abs() < 1e-9,
            "repriced {repriced} vs {price}"
        );

        let implied = helper.implied_quote().unwrap();
        assert!(
            (implied - price).abs() < 1e-9,
            "implied {implied} vs {price}"
        );
    }

    /// The explicit-date constructor with no end date advances three IMM periods
    /// and pins every schedule date to that window (`ratehelpers.cpp:91`).
    /// Stubbing the three-period advance to a single one makes the expected
    /// maturity disagree and this assertion fails.
    #[test]
    fn from_end_date_advances_three_imm_periods_and_pins_the_schedule() {
        let imm_start = imm::next_date(today(), false);
        assert!(imm::is_imm_date(imm_start, false));
        let helper = FuturesRateHelper::from_end_date(
            quote_handle(96.0),
            imm_start,
            None,
            Actual360::new(),
            Handle::empty(),
            FuturesType::Imm,
        )
        .unwrap();

        let expected_maturity = imm::next_date(
            imm::next_date(imm::next_date(imm_start, false), false),
            false,
        );
        assert_eq!(helper.earliest_date(), imm_start);
        assert_eq!(helper.maturity_date(), expected_maturity);
        assert_eq!(helper.pillar_date(), expected_maturity);
        assert_eq!(helper.latest_date(), expected_maturity);
        assert_eq!(helper.latest_relevant_date(), expected_maturity);
    }

    /// A start that is not a valid IMM date is rejected under the IMM convention
    /// (`CheckDate`, `ratehelpers.cpp:46`).
    #[test]
    fn a_non_imm_start_is_rejected_under_the_imm_convention() {
        let start = today();
        assert!(
            !imm::is_imm_date(start, false),
            "the fixture start must not be an IMM date"
        );
        let result = FuturesRateHelper::from_end_date(
            quote_handle(96.0),
            start,
            None,
            Actual360::new(),
            Handle::empty(),
            FuturesType::Imm,
        );
        assert!(result.is_err());
    }

    /// A Custom helper needs an explicit end date; the C++ null-maturity path is
    /// an error here (divergence documented on [`FuturesRateHelper::from_end_date`]).
    #[test]
    fn a_custom_helper_requires_an_explicit_end_date() {
        let start = today();
        let result = FuturesRateHelper::from_end_date(
            quote_handle(96.0),
            start,
            None,
            Actual360::new(),
            Handle::empty(),
            FuturesType::Custom,
        );
        assert!(result.is_err());
    }

    /// The index constructor takes its window from the index conventions: the
    /// maturity is the start advanced by the index tenor on its fixing calendar
    /// (`ratehelpers.cpp:139`).
    #[test]
    fn from_index_takes_the_window_from_the_index_conventions() {
        let settings = settings_on(today());
        let index = euribor(Period::new(3, TimeUnit::Months), Handle::empty(), settings);
        let imm_start = imm::next_date(today(), false);
        let helper = FuturesRateHelper::from_index(
            quote_handle(96.0),
            imm_start,
            &index,
            Handle::empty(),
            FuturesType::Imm,
        )
        .unwrap();

        let expected_maturity = index.fixing_calendar().advance_by_period(
            imm_start,
            index.tenor(),
            index.business_day_convention(),
            false,
        );
        assert_eq!(helper.earliest_date(), imm_start);
        assert_eq!(helper.maturity_date(), expected_maturity);
    }

    /// `FraRateHelper::initializeDates` (`ratehelpers.cpp:393`): the earliest
    /// date is `period_to_start` past spot and the maturity is the *combined*
    /// `period_to_start + tenor` past spot. The degeneracy guard asserts that on
    /// this evaluation date the faithful (advance-from-spot) maturity really
    /// differs from the plausible-wrong chained reading `advance(earliest,
    /// tenor)`; without the difference the pin would not discriminate the trap.
    #[test]
    fn fra_initialize_dates_advances_maturity_from_spot_not_chained() {
        let eval = Date::new(13, Month::May, 2026);
        let settings = settings_on(eval);
        let index = euribor(Period::new(3, TimeUnit::Months), Handle::empty(), settings);
        let period_to_start = Period::new(3, TimeUnit::Months);
        let helper = FraRateHelper::from_rate(
            0.03,
            period_to_start,
            &index,
            true,
            Pillar::LastRelevantDate,
        );

        let calendar = index.fixing_calendar();
        let reference = calendar.adjust(eval, BusinessDayConvention::Following);
        let spot = index.value_date(reference).unwrap();
        let convention = index.business_day_convention();
        let eom = index.end_of_month();
        let earliest = calendar.advance_by_period(spot, period_to_start, convention, eom);
        let maturity_from_spot =
            calendar.advance_by_period(spot, period_to_start + index.tenor(), convention, eom);
        let maturity_chained = calendar.advance_by_period(earliest, index.tenor(), convention, eom);
        assert_ne!(
            maturity_from_spot, maturity_chained,
            "degenerate fixture: pick an evaluation date where the roll separates the two maturities"
        );

        assert_eq!(helper.earliest_date(), earliest);
        assert_eq!(helper.maturity_date(), maturity_from_spot);
        let latest_relevant = index.maturity_date(earliest).unwrap();
        assert_eq!(helper.latest_relevant_date(), latest_relevant);
        assert_eq!(helper.pillar_date(), latest_relevant);
        assert_eq!(helper.latest_date(), latest_relevant);
    }

    /// The explicit-date constructor (`ratehelpers.cpp:341`, built on
    /// `RelativeDateRateHelper(rate, false)`): its window is fixed at
    /// construction and, unlike the relative constructors, does not shift when
    /// the evaluation date moves. Par mode with the `MaturityDate` pillar pins
    /// the latest-relevant date and pillar at the explicit end date.
    #[test]
    fn fra_from_dates_pins_explicit_window_and_ignores_eval_change() {
        let settings = settings_on(today());
        let index = euribor(
            Period::new(3, TimeUnit::Months),
            Handle::empty(),
            settings.clone(),
        );
        let start = Date::new(15, Month::September, 2026);
        let end = Date::new(15, Month::December, 2026);
        let helper = FraRateHelper::from_dates(
            Handle::new(shared(SimpleQuote::new(0.03)) as Shared<dyn Quote>),
            start,
            end,
            &index,
            false,
            Pillar::MaturityDate,
        );

        assert_eq!(helper.earliest_date(), start);
        assert_eq!(helper.maturity_date(), end);
        assert_eq!(helper.latest_relevant_date(), end);
        assert_eq!(helper.pillar_date(), end);

        settings.set_evaluation_date(today() + 90);
        assert_eq!(
            helper.earliest_date(),
            start,
            "an explicit-date FRA must not shift on an evaluation-date change"
        );
        assert_eq!(helper.maturity_date(), end);
    }

    /// The bootstrap fixture: a short deposit anchor plus one FRA node built by
    /// `factory`, bootstrapped into a `Discount`/`LogLinear` curve. Returns the
    /// curve handle, the evaluation date and the shared settings so the caller
    /// can reprice the FRA arm off independently-reconstructed dates.
    fn bootstrap_with_fra(
        fra: Shared<dyn RateHelper>,
        settings: Shared<Settings<Date>>,
        today: Date,
    ) -> Handle<dyn YieldTermStructure> {
        let calendar = Target::new();
        let settlement = calendar.advance(
            today,
            2,
            TimeUnit::Days,
            BusinessDayConvention::Following,
            false,
        );
        let deposit_index = euribor(
            Period::new(3, TimeUnit::Months),
            Handle::empty(),
            settings.clone(),
        );
        let deposit = DepositRateHelper::from_rate(0.02, &deposit_index);
        let curve = PiecewiseYieldCurve::<Discount, LogLinear>::new(
            settlement,
            vec![deposit as Shared<dyn RateHelper>, fra],
            Actual360::new(),
            LogLinear,
        )
        .unwrap();
        Handle::new(Shared::clone(&curve) as Shared<dyn YieldTermStructure>)
    }

    /// Independently reconstructs the FRA `[start, end]` window off `index`'s
    /// conventions for the given evaluation date, so the reprice arms do not
    /// reuse the helper's own (possibly wrong) dates - the discrimination lives
    /// in this from-scratch reconstruction, not in crossing modes.
    fn reconstruct_window(index: &IborIndex, eval: Date, period_to_start: Period) -> (Date, Date) {
        let calendar = index.fixing_calendar();
        let reference = calendar.adjust(eval, BusinessDayConvention::Following);
        let spot = index.value_date(reference).unwrap();
        let convention = index.business_day_convention();
        let eom = index.end_of_month();
        let start = calendar.advance_by_period(spot, period_to_start, convention, eom);
        let end =
            calendar.advance_by_period(spot, period_to_start + index.tenor(), convention, eom);
        (start, end)
    }

    /// Indexed arm (`ratehelpers.cpp:363`): bootstrap through an indexed FRA,
    /// then forecast the fixing off the curve through a fresh index over an
    /// independently reconstructed window and assert it reproduces the input
    /// rate. Passing proves bootstrap convergence; the confirm-by-stubbing gate
    /// (perturbing `fixing_date`) is what proves the date math discriminates.
    #[test]
    fn fra_indexed_bootstrap_reprices_the_input_rate() {
        let eval = Date::new(13, Month::May, 2026);
        let settings = settings_on(eval);
        let period_to_start = Period::new(3, TimeUnit::Months);
        let fra_rate = 0.03;
        let fra_index = euribor(
            Period::new(3, TimeUnit::Months),
            Handle::empty(),
            settings.clone(),
        );
        let fra = FraRateHelper::from_rate(
            fra_rate,
            period_to_start,
            &fra_index,
            true,
            Pillar::LastRelevantDate,
        );
        let handle = bootstrap_with_fra(
            Shared::clone(&fra) as Shared<dyn RateHelper>,
            settings.clone(),
            eval,
        );

        let reprice_index = euribor(
            Period::new(3, TimeUnit::Months),
            handle.clone(),
            settings.clone(),
        );
        let (start, _end) = reconstruct_window(&reprice_index, eval, period_to_start);
        let fixing_date = reprice_index.fixing_date(start);
        let estimated = reprice_index.fixing(fixing_date, true).unwrap();
        assert!(
            (estimated - fra_rate).abs() <= 1.0e-9,
            "indexed reprice {estimated} vs input {fra_rate}"
        );
    }

    /// Par arm (`ratehelpers.cpp:365`): bootstrap through a par FRA, then
    /// recompute the simple forward `(disc(start)/disc(end) - 1)/tau` off the
    /// curve over an independently reconstructed window and assert it reproduces
    /// the input rate. The confirm-by-stubbing gate (perturbing the maturity)
    /// proves the date math discriminates.
    #[test]
    fn fra_par_bootstrap_reprices_the_input_rate() {
        let eval = Date::new(13, Month::May, 2026);
        let settings = settings_on(eval);
        let period_to_start = Period::new(3, TimeUnit::Months);
        let fra_rate = 0.03;
        let fra_index = euribor(
            Period::new(3, TimeUnit::Months),
            Handle::empty(),
            settings.clone(),
        );
        let fra = FraRateHelper::from_rate(
            fra_rate,
            period_to_start,
            &fra_index,
            false,
            Pillar::LastRelevantDate,
        );
        let handle = bootstrap_with_fra(
            Shared::clone(&fra) as Shared<dyn RateHelper>,
            settings.clone(),
            eval,
        );

        let reprice_index = euribor(
            Period::new(3, TimeUnit::Months),
            handle.clone(),
            settings.clone(),
        );
        let (start, end) = reconstruct_window(&reprice_index, eval, period_to_start);
        let chained_end = reprice_index.fixing_calendar().advance_by_period(
            start,
            reprice_index.tenor(),
            reprice_index.business_day_convention(),
            reprice_index.end_of_month(),
        );
        assert_ne!(
            end, chained_end,
            "degenerate fixture: the maturity trap does not bite on this window, so the par reprice would not discriminate it"
        );
        let curve = handle.current_link().unwrap();
        let discount_start = curve.discount_date(start, false).unwrap();
        let discount_end = curve.discount_date(end, false).unwrap();
        let tau = reprice_index.day_counter().year_fraction(start, end);
        let estimated = (discount_start / discount_end - 1.0) / tau;
        assert!(
            (estimated - fra_rate).abs() <= 1.0e-9,
            "par reprice {estimated} vs input {fra_rate}"
        );
    }

    /// D10: a deposit helper built before the evaluation date is set does not
    /// panic; its first read returns the unset-date error, and setting the
    /// date rebuilds a usable schedule.
    #[test]
    fn deposit_unset_evaluation_date_is_an_error_on_first_read() {
        let settings = shared(Settings::<Date>::new());
        let source = euribor(
            Period::new(6, TimeUnit::Months),
            Handle::empty(),
            settings.clone(),
        );
        let helper = DepositRateHelper::from_rate(0.02, &source);
        let curve = flat_curve(today(), 0.03);
        helper.set_term_structure(&curve);

        let error = helper.quote_error().unwrap_err();
        assert_eq!(error.message(), "evaluation date is not set");

        settings.set_evaluation_date(today());
        assert!(helper.earliest_date() > today());
        helper.quote_error().unwrap();
    }

    /// D10: the FRA helper's unset evaluation date surfaces as that error, not
    /// as the `rebuild_dates` panic fallback "helper dates exceed supported
    /// range", and clears once the date is set.
    #[test]
    fn fra_unset_evaluation_date_is_an_error_on_first_read() {
        let settings = shared(Settings::<Date>::new());
        let source = euribor(
            Period::new(3, TimeUnit::Months),
            Handle::empty(),
            settings.clone(),
        );
        let error = FraRateHelper::try_from_rate(
            0.02,
            Period::new(3, TimeUnit::Months),
            &source,
            true,
            Pillar::LastRelevantDate,
        )
        .err()
        .unwrap();
        assert_eq!(error.message(), "evaluation date is not set");

        let helper = FraRateHelper::from_rate(
            0.02,
            Period::new(3, TimeUnit::Months),
            &source,
            true,
            Pillar::LastRelevantDate,
        );
        let curve = flat_curve(today(), 0.03);
        helper.set_term_structure(&curve);
        let error = helper.quote_error().unwrap_err();
        assert_eq!(error.message(), "evaluation date is not set");

        settings.set_evaluation_date(today());
        assert!(helper.validate_dates().is_ok());
        assert!(helper.earliest_date() > today());
        helper.quote_error().unwrap();
    }

    /// `testHelperDatesFromNonBusinessEvaluationDate` (v1.44
    /// `piecewiseyieldcurve.cpp:2422`): on Saturday 20 June 2026 the deposit,
    /// FRA and BMA helpers count their fixing / settlement days from the
    /// Saturday itself (`ratehelpers.cpp:232-233/396-397/676-678`). The C++
    /// deposit is built from explicit Euribor6M parameters; the port's
    /// index-based [`DepositRateHelper::from_rate`] builds the same schedule.
    #[test]
    fn helper_dates_from_a_saturday_evaluation_date() {
        use crate::indexes::ibor::Euribor;
        use crate::indexes::{BMAIndex, UsdLibor};
        use crate::termstructures::yields::BMASwapRateHelper;
        use crate::time::calendars::{JointCalendar, JointCalendarRule};

        let settings = settings_on(Date::new(20, Month::June, 2026));
        let euribor6m = Euribor::six_months(Handle::empty(), Shared::clone(&settings));

        let depo = DepositRateHelper::from_rate(0.03, &euribor6m);
        assert_eq!(
            depo.base().earliest_date(),
            Date::new(23, Month::June, 2026)
        );

        let fra = FraRateHelper::from_months(
            Handle::new(shared(SimpleQuote::new(0.03)) as Shared<dyn Quote>),
            3,
            &euribor6m,
            true,
            Pillar::LastRelevantDate,
        );
        assert_eq!(
            fra.base().earliest_date(),
            Date::new(23, Month::September, 2026)
        );

        let bma_index = shared(BMAIndex::new(Handle::empty(), Shared::clone(&settings)));
        let libor = shared(
            UsdLibor::new(
                Period::new(3, TimeUnit::Months),
                Handle::empty(),
                Shared::clone(&settings),
            )
            .unwrap(),
        );
        let bma_calendar = JointCalendar::of_two(
            bma_index.fixing_calendar(),
            libor.fixing_calendar(),
            JointCalendarRule::JoinHolidays,
        );
        let bma = BMASwapRateHelper::new(
            Handle::new(shared(SimpleQuote::new(0.75)) as Shared<dyn Quote>),
            Period::new(5, TimeUnit::Years),
            3,
            bma_calendar,
            Period::new(3, TimeUnit::Months),
            BusinessDayConvention::Following,
            Actual360::new(),
            &bma_index,
            &libor,
        )
        .unwrap();
        assert_eq!(bma.base().earliest_date(), Date::new(24, Month::June, 2026));
    }
}