@insiderfinance/totalfinance 0.1.0

package/modules/fixed-income/dist/rates.js

@@ -0,0 +1,686 @@
+/**
+ * Rates derivatives (spec §14.3): FRAs, interest-rate swaps and OIS, European swaptions, and caps /
+ * floors, priced off {@link YieldCurve}s with the Black (lognormal-forward) and Bachelier
+ * (normal-forward) models.
+ *
+ * The library is multi-curve aware: a `discountCurve` discounts every cash flow while an optional
+ * `forecastCurve` projects floating coupons (defaulting to the discount curve for the single-curve
+ * case). Volatility-model inputs are validated and unknown selectors throw (no silent degradation).
+ */
+import { seriesFacade, ErrorCode, InputError, ensureFinite, ensureKnownKeys, ensureNonNegative, ensurePositive, requireArgumentObject, requireFiniteFields, CONVENTIONS_VERSION, } from '../../core/dist/index.js';
+import { requireSpecification, ensureDayCountWhenPresent, ensureFrequencyWhenPresent, } from './validate.js';
+import { ensureFiniteWhenPresent } from '../../core/dist/index.js';
+import { normalCdf, normalPdf } from '../../math/dist/index.js';
+import { addMonths, generateSchedule, paymentsPerYear, yearFraction, } from './conventions.js';
+/**
+ * Curve fields take a curve INSTANCE (from `curves.fromZeroRates(...)` / `curves.flat(...)` /
+ * `curves.bootstrap(...)`), not a raw pillar list. A `{}` or a curve-shaped guess would die on the
+ * first `discount()` call deep inside a leg loop — teach the fix at the boundary instead
+ * (the same pattern as `requireCurveInstance` in bonds).
+ */
+function requireCurveField(functionName, field, value) {
+    const c = value;
+    if (c === null ||
+        c === undefined ||
+        typeof c !== 'object' ||
+        typeof c.discount !== 'function' ||
+        typeof c.forwardRate !== 'function') {
+        throw new InputError(`${functionName}: ${field} must be a yield curve built by curves.fromZeroRates(...) / curves.flat(...) / ` +
+            `curves.bootstrap(...) (an object with discount()/forwardRate()); got ` +
+            `${c === null ? 'null' : c === undefined ? 'undefined' : typeof c}. Build the curve first, then pass it here.`, { code: ErrorCode.InputWrongType, context: { function: functionName, field } });
+    }
+}
+/** Validate a {@link SwapCurves} bundle: `discountCurve` required, `forecastCurve` optional. */
+function requireSwapCurves(functionName, curves) {
+    requireArgumentObject(functionName, 'curves', curves);
+    ensureKnownKeys(functionName, 'curves', curves, SWAP_CURVES_KEYS);
+    requireCurveField(functionName, 'curves.discountCurve', curves.discountCurve);
+    if (curves.forecastCurve !== undefined) {
+        requireCurveField(functionName, 'curves.forecastCurve', curves.forecastCurve);
+    }
+}
+// ---------------------------------------------------------------------------------------------------
+// Forward-option model cores (undiscounted: the caller multiplies by the discount/annuity numeraire)
+// ---------------------------------------------------------------------------------------------------
+/**
+ * Shared input guard for the forward-option cores: a bad `right`, a negative/NaN vol, or a
+ * negative/NaN maturity must throw rather than silently returning intrinsic (negative vol) or leaking
+ * NaN (negative `t`). Runtime JSON callers routinely hit these.
+ */
+function validateForwardOptionInputs(input) {
+    const { functionName, volatility, timeToExpiryYears, right } = input;
+    if (right !== 'call' && right !== 'put') {
+        throw new InputError(`${functionName}: right must be 'call' or 'put', got "${String(right)}".`, {
+            code: ErrorCode.InputInvalidEnum,
+            context: { right },
+        });
+    }
+    if (!Number.isFinite(volatility) || volatility < 0) {
+        throw new InputError(`${functionName}: volatility must be finite and ≥ 0, got ${volatility}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { volatility },
+        });
+    }
+    if (!Number.isFinite(timeToExpiryYears) || timeToExpiryYears < 0) {
+        throw new InputError(`${functionName}: time-to-expiry must be finite and ≥ 0, got ${timeToExpiryYears}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { timeToExpiryYears },
+        });
+    }
+}
+export function blackKernel(input) {
+    requireArgumentObject('blackKernel', 'input', input);
+    ensureKnownKeys('blackKernel', 'input', input, [
+        'forward',
+        'strike',
+        'volatility',
+        'timeToExpiryYears',
+        'right',
+    ]);
+    const { forward, strike, volatility, timeToExpiryYears, right } = input;
+    validateForwardOptionInputs({
+        functionName: 'blackKernel',
+        volatility,
+        timeToExpiryYears,
+        right,
+    });
+    if (!(forward > 0) || !(strike > 0)) {
+        throw new InputError('blackKernel: Black model requires positive forward and strike (use Bachelier for ≤0).', {
+            code: ErrorCode.InputOutOfRange,
+            context: { forward, strike },
+        });
+    }
+    const intrinsic = right === 'call' ? Math.max(forward - strike, 0) : Math.max(strike - forward, 0);
+    const sd = volatility * Math.sqrt(timeToExpiryYears);
+    if (sd <= 0)
+        return intrinsic;
+    const d1 = (Math.log(forward / strike) + 0.5 * sd * sd) / sd;
+    const d2 = d1 - sd;
+    return right === 'call'
+        ? forward * normalCdf(d1) - strike * normalCdf(d2)
+        : strike * normalCdf(-d2) - forward * normalCdf(-d1);
+}
+export function bachelierKernel(input) {
+    requireArgumentObject('bachelierKernel', 'input', input);
+    ensureKnownKeys('bachelierKernel', 'input', input, [
+        'forward',
+        'strike',
+        'normalVolatility',
+        'timeToExpiryYears',
+        'right',
+    ]);
+    // `validateForwardOptionInputs` covers volatility/expiry/right; the two PRICE legs were unchecked,
+    // so `bachelierKernel({ normalVolatility, timeToExpiryYears, right })` returned NaN as a premium.
+    requireFiniteFields('bachelierKernel', input, ['forward', 'strike'], {
+        exampleCall: 'bachelierKernel({ forward: 0.03, strike: 0.032, normalVolatility: 0.01, ' +
+            "timeToExpiryYears: 1, right: 'call' })",
+        hints: {
+            forward: 'a forward RATE in decimal (0.03 = 3%), not a price',
+            strike: 'decimal, same units as the forward rate',
+        },
+    });
+    const { forward, strike, normalVolatility: vol, timeToExpiryYears, right } = input;
+    validateForwardOptionInputs({
+        functionName: 'bachelierKernel',
+        volatility: vol,
+        timeToExpiryYears,
+        right,
+    });
+    const intrinsic = right === 'call' ? Math.max(forward - strike, 0) : Math.max(strike - forward, 0);
+    const sd = vol * Math.sqrt(timeToExpiryYears);
+    if (sd <= 0)
+        return intrinsic;
+    const d = (forward - strike) / sd;
+    const sign = right === 'call' ? 1 : -1;
+    return sign * (forward - strike) * normalCdf(sign * d) + sd * normalPdf(d);
+}
+function priceForward(input) {
+    const { model, forward, strike, volatility, timeToExpiryYears, right } = input;
+    if (model === 'black')
+        return blackKernel({
+            forward,
+            strike,
+            volatility,
+            timeToExpiryYears,
+            right,
+        });
+    if (model === 'bachelier') {
+        return bachelierKernel({
+            forward,
+            strike,
+            normalVolatility: volatility,
+            timeToExpiryYears,
+            right,
+        });
+    }
+    throw new InputError(`priceForward: Unknown rates vol model "${String(model)}".`, {
+        code: ErrorCode.InputInvalidEnum,
+        context: { field: 'model', value: model },
+    });
+}
+/** {@link FraSpecification} keys (Law 12 — mirrors the interface above; keep in sync). */
+const FRA_SPEC_KEYS = ['start', 'end', 'fixedRate', 'notional', 'dayCount'];
+/** The options shape `fraValue` accepts (Law 12 — mirrors the parameter type; keep in sync). */
+const FRA_VALUE_OPTIONS_KEYS = ['curve'];
+/** Law 2 report grammar (D5): every rates answer carries its conventions and a warnings channel. */
+function ratesReport(assumptions, warnings = []) {
+    return {
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION, ...assumptions },
+        diagnostics: { warnings },
+    };
+}
+/** Value a forward rate agreement off a curve: `N·τ·(F − K)·DF(end)`. */
+/**
+ * Optional swap/rates conventions run their ladders once per external call (the 350c2796 ruling):
+ * a null dayCount/frequency used to coalesce into the industry default and silently change the
+ * accrual math; `model: null` silently priced Black.
+ */
+/** The swap family's required fixed leg: an omitted fixedRate used to value the swap as NaN. */
+function requireFixedRate(functionName, s) {
+    requireFiniteFields(functionName, s, ['fixedRate'], {
+        exampleCall: `${functionName}({ effectiveDate: '2026-01-15', maturityDate: '2031-01-15', fixedRate: 0.04 }, { discountCurve })`,
+    });
+}
+function requireRatesConventions(functionName, s, fields) {
+    // Self-guarding: heads call this early, so a null/undefined specification must teach here
+    // rather than crash on the first field read (the deep-sweep law).
+    requireArgumentObject(functionName, 'specification', s);
+    for (const field of fields) {
+        const value = s[field];
+        if (field.toLowerCase().includes('daycount')) {
+            if (value !== undefined && value === null) {
+                // ensureDayCountWhenPresent rejects null with the domain — route through it.
+            }
+            ensureDayCountWhenPresentNamed(value, functionName, field);
+        }
+        else if (field.toLowerCase().includes('frequency')) {
+            ensureFrequencyWhenPresent(value, functionName);
+        }
+        else if (field === 'model') {
+            if (value !== undefined && value !== 'black' && value !== 'bachelier') {
+                throw new InputError(`${functionName}: model must be 'black' | 'bachelier' when provided. Received ${value === null ? 'null' : JSON.stringify(value)}.`, {
+                    code: ErrorCode.InputInvalidEnum,
+                    context: { function: functionName, field: 'model', received: value },
+                });
+            }
+        }
+        else {
+            ensureFiniteWhenPresent(value, field, functionName);
+        }
+    }
+}
+/** `ensureDayCountWhenPresent`, reporting the caller's field name (fixedDayCount, floatDayCount…). */
+function ensureDayCountWhenPresentNamed(value, functionName, field) {
+    try {
+        ensureDayCountWhenPresent(value, functionName);
+    }
+    catch (error) {
+        if (error instanceof InputError && field !== 'dayCount') {
+            throw new InputError(error.message.replace('dayCount', field), {
+                code: ErrorCode.InputInvalidEnum,
+                context: { function: functionName, field, received: value },
+            });
+        }
+        throw error;
+    }
+}
+export function fraValue(specification, options) {
+    requireArgumentObject('fraValue', 'options', options);
+    ensureKnownKeys('fraValue', 'options', options, FRA_VALUE_OPTIONS_KEYS);
+    requireArgumentObject('fraValue', 'specification', specification);
+    ensureKnownKeys('fraValue', 'specification', specification, FRA_SPEC_KEYS);
+    requireCurveField('fraValue', 'options.curve', options.curve);
+    requireRatesConventions('fraValue', specification, [
+        'dayCount',
+        'notional',
+    ]);
+    requireSpecification('fraValue', specification, ['start', 'end', 'fixedRate']);
+    for (const dateField of ['start', 'end']) {
+        const value = specification[dateField];
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new InputError(`fraValue: ${dateField} must be an ISO date string. Received ${value === null ? 'null' : typeof value}.`, { code: ErrorCode.InputWrongType, context: { field: dateField } });
+        }
+    }
+    requireFiniteFields('fraValue', specification, ['fixedRate'], {
+        exampleCall: "fraValue({ start: '2026-04-15', end: '2026-07-15', fixedRate: 0.045 }, { curve })",
+    });
+    const dayCount = specification.dayCount ?? 'ACT/360';
+    const notional = specification.notional ?? 1;
+    const accrual = yearFraction(specification.start, specification.end, dayCount);
+    const forwardRate = options.curve.forwardRate(specification.start, specification.end, dayCount);
+    const discountFactor = options.curve.discount(specification.end); // DF from the curve reference date to the payment
+    const value = notional * accrual * (forwardRate - specification.fixedRate) * discountFactor;
+    return {
+        value,
+        forwardRate,
+        discountFactor,
+        accrual,
+        ...ratesReport({ dayCount, notional }),
+    };
+}
+/** {@link SwapSpecification} keys (Law 12 — mirrors the interface above; keep in sync). */
+const SWAP_SPEC_KEYS = [
+    'startDate',
+    'maturityDate',
+    'fixedRate',
+    'notional',
+    'fixedFrequency',
+    'fixedDayCount',
+    'floatFrequency',
+    'floatDayCount',
+    'floatSpread',
+];
+/** {@link SwapCurves} keys (Law 12 — mirrors the interface above; keep in sync). */
+const SWAP_CURVES_KEYS = ['discountCurve', 'forecastCurve'];
+/** Fixed-leg annuity Σ τᵢ·DF(payDateᵢ) for a swap, per unit notional. */
+function fixedAnnuity(specification, discount) {
+    const schedule = generateSchedule({
+        effectiveDate: specification.startDate,
+        maturityDate: specification.maturityDate,
+        frequency: specification.fixedFrequency ?? 'semiannual',
+    });
+    const dc = specification.fixedDayCount ?? '30/360';
+    let a = 0;
+    for (const p of schedule)
+        a += yearFraction(p.accrualStart, p.accrualEnd, dc) * discount.discount(p.paymentDate);
+    return a;
+}
+/** Floating-leg PV Σ (Fᵢ + spread)·τᵢ·DF(payDateᵢ), per unit notional. */
+function floatLegPresentValue(specification, discount, forecast) {
+    const schedule = generateSchedule({
+        effectiveDate: specification.startDate,
+        maturityDate: specification.maturityDate,
+        frequency: specification.floatFrequency ?? 'quarterly',
+    });
+    const dc = specification.floatDayCount ?? 'ACT/360';
+    const spread = specification.floatSpread ?? 0;
+    let pv = 0;
+    for (const p of schedule) {
+        const accrual = yearFraction(p.accrualStart, p.accrualEnd, dc);
+        const fwd = forecast.forwardRate(p.accrualStart, p.accrualEnd, dc);
+        pv += (fwd + spread) * accrual * discount.discount(p.paymentDate);
+    }
+    return pv;
+}
+/** Value an interest-rate swap (or OIS) off discount/forecast curves. */
+export function swapValue(specification, curves) {
+    requireSwapCurves('swapValue', curves);
+    requireFixedRate('swapValue', specification);
+    requireRatesConventions('swapValue', specification, [
+        'fixedFrequency',
+        'fixedDayCount',
+        'floatFrequency',
+        'floatDayCount',
+        'floatSpread',
+        'notional',
+    ]);
+    requireArgumentObject('swapValue', 'specification', specification);
+    ensureKnownKeys('swapValue', 'specification', specification, SWAP_SPEC_KEYS);
+    const notional = specification.notional ?? 1;
+    const discount = curves.discountCurve;
+    const forecast = curves.forecastCurve ?? discount;
+    const annuity = fixedAnnuity(specification, discount);
+    if (annuity === 0) {
+        // Law 7: a zero fixed-leg annuity means the schedule produced no accrual periods — a
+        // malformed spec, rejected typed rather than a NaN parRate flowing downstream.
+        throw new InputError('swapValue: the fixed leg has no accrual periods (zero annuity) — check startDate/maturityDate/frequency.', {
+            code: ErrorCode.InputWrongShape,
+            context: { start: specification.startDate, maturity: specification.maturityDate },
+        });
+    }
+    const floatPv = floatLegPresentValue(specification, discount, forecast);
+    const fixedPv = specification.fixedRate * annuity;
+    const parRate = floatPv / annuity;
+    const value = notional * (floatPv - fixedPv);
+    return {
+        value,
+        parRate,
+        annuity,
+        fixedLegPresentValue: notional * fixedPv,
+        floatLegPresentValue: notional * floatPv,
+        pv01: notional * annuity * 1e-4,
+        ...ratesReport({
+            notional,
+            fixedFrequency: specification.fixedFrequency ?? 'semiannual',
+            fixedDayCount: specification.fixedDayCount ?? '30/360',
+            floatDayCount: specification.floatDayCount ?? 'ACT/360',
+        }),
+    };
+}
+/** {@link ParSwapSpecification} keys (Law 12 — `SWAP_SPEC_KEYS` minus the irrelevant `fixedRate`). */
+const PAR_SWAP_SPEC_KEYS = SWAP_SPEC_KEYS.filter((k) => k !== 'fixedRate');
+function swapRateValuation(functionName, specification, curves) {
+    requireSwapCurves(functionName, curves);
+    requireRatesConventions(functionName, specification, [
+        'fixedFrequency',
+        'fixedDayCount',
+        'floatFrequency',
+        'floatDayCount',
+        'floatSpread',
+        'notional',
+    ]);
+    requireArgumentObject(functionName, 'specification', specification);
+    ensureKnownKeys(functionName, 'specification', specification, PAR_SWAP_SPEC_KEYS);
+    // `fixedRate` does not affect the par rate or annuity; 0 is a harmless placeholder for the reuse.
+    return swapValue({ ...specification, fixedRate: 0 }, curves);
+}
+/**
+ * Par swap rate that makes the swap value zero: `floatLegPv / annuity`. Facade (H04): the plain
+ * call returns the scalar; `.explain()` discloses the leg decomposition and every applied
+ * convention.
+ */
+export const swapRate = seriesFacade('swapRate', (specification, curves) => swapRateValuation('swapRate', specification, curves).parRate, ((specification, curves) => {
+    const valuation = swapRateValuation('swapRate.explain', specification, curves);
+    return {
+        value: valuation.parRate,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            startDate: specification.startDate,
+            maturityDate: specification.maturityDate,
+            notional: specification.notional ?? 1,
+            fixedFrequency: specification.fixedFrequency ?? 'semiannual',
+            fixedDayCount: specification.fixedDayCount ?? '30/360',
+            floatFrequency: specification.floatFrequency ?? 'quarterly',
+            floatDayCount: specification.floatDayCount ?? 'ACT/360',
+            floatSpread: specification.floatSpread ?? 0,
+        },
+        diagnostics: {
+            method: 'closed-form',
+            // The arithmetic the rate came from: parRate = floatLegPresentValue / annuity (both per
+            // unit notional, exactly as the ratio consumes them).
+            decomposition: {
+                floatLegPresentValue: valuation.floatLegPresentValue / (specification.notional ?? 1),
+                annuity: valuation.annuity,
+            },
+            warnings: [],
+        },
+    };
+    /* The FI day-count vocabulary is wider than core's Assumptions enum — type-level only. */
+}));
+/** {@link ForwardSwapSpecification} keys (Law 12 — the {@link SwapSpecification} keys minus `fixedRate`). */
+const FORWARD_SWAP_SPEC_KEYS = SWAP_SPEC_KEYS.filter((k) => k !== 'fixedRate');
+/**
+ * The curve-driven forward swap rate and annuity of a (possibly forward-starting) swap — the two curve
+ * inputs a swaption needs, in one call. For a swaption struck at `K` expiring at `startDate`, the price
+ * is `annuity · Black(forwardSwapRate, K, σ, T)` (Bachelier for normal σ). Pair this with a vol from
+ * `@insiderfinance/totalfinance/volatility`'s swaption cube (`swaptionCubeVolatility`) for a fully curve-consistent swaption price, so
+ * the forward and annuity come from the live (OIS/projection) curves rather than stale market nodes.
+ */
+export function forwardSwap(specification, curves) {
+    requireSwapCurves('forwardSwap', curves);
+    requireRatesConventions('forwardSwap', specification, [
+        'fixedFrequency',
+        'fixedDayCount',
+        'floatFrequency',
+        'floatDayCount',
+        'floatSpread',
+        'notional',
+    ]);
+    requireArgumentObject('forwardSwap', 'specification', specification);
+    ensureKnownKeys('forwardSwap', 'specification', specification, FORWARD_SWAP_SPEC_KEYS);
+    // `fixedRate` doesn't affect the par rate or annuity; 0 is a harmless placeholder for the reuse.
+    const v = swapValue({ ...specification, fixedRate: 0 }, curves);
+    return {
+        forwardSwapRate: v.parRate,
+        annuity: v.annuity,
+        pv01: v.pv01,
+        assumptions: v.assumptions,
+        diagnostics: v.diagnostics,
+    };
+}
+/** {@link SwaptionSpecification} keys (Law 12 — the {@link SwapSpecification} keys plus the option fields above). */
+const SWAPTION_SPEC_KEYS = [
+    ...SWAP_SPEC_KEYS,
+    'expiry',
+    'volatility',
+    'optionType',
+    'model',
+];
+/**
+ * Price a European swaption. The forward swap rate `S` is the natural martingale under the annuity
+ * measure, so the price is `annuity · ForwardOption(S, K, σ, T)` — Black for lognormal vol, Bachelier
+ * for normal vol.
+ */
+export function swaptionPrice(specification, curves) {
+    requireSwapCurves('swaptionPrice', curves);
+    requireRatesConventions('swaptionPrice', specification, [
+        'fixedFrequency',
+        'fixedDayCount',
+        'floatFrequency',
+        'floatDayCount',
+        'floatSpread',
+        'model',
+        'notional',
+    ]);
+    requireArgumentObject('swaptionPrice', 'specification', specification);
+    ensureKnownKeys('swaptionPrice', 'specification', specification, SWAPTION_SPEC_KEYS);
+    if (specification.optionType !== 'payer' && specification.optionType !== 'receiver') {
+        throw new InputError(`swaptionPrice: optionType must be 'payer' or 'receiver', got "${String(specification.optionType)}".`, { code: ErrorCode.InputInvalidEnum, context: { optionType: specification.optionType } });
+    }
+    const discount = curves.discountCurve;
+    const forecast = curves.forecastCurve ?? discount;
+    const annuity = fixedAnnuity(specification, discount);
+    if (annuity === 0) {
+        throw new InputError('swaptionPrice: the underlying fixed leg has no accrual periods (zero annuity) — check startDate/maturityDate/frequency.', {
+            code: ErrorCode.InputWrongShape,
+            context: { start: specification.startDate, maturity: specification.maturityDate },
+        });
+    }
+    const floatPv = floatLegPresentValue(specification, discount, forecast);
+    const forwardSwapRate = floatPv / annuity;
+    const t = yearFraction(discount.referenceDate, specification.expiry, 'ACT/365F');
+    if (t < 0) {
+        throw new InputError('swaptionPrice: Swaption expiry is before the curve reference date.', {
+            code: ErrorCode.InputOutOfRange,
+            context: { expiry: specification.expiry, referenceDate: discount.referenceDate },
+        });
+    }
+    const right = specification.optionType === 'payer' ? 'call' : 'put';
+    const model = specification.model ?? 'black';
+    const fwdOption = priceForward({
+        model,
+        forward: forwardSwapRate,
+        strike: specification.fixedRate,
+        volatility: specification.volatility,
+        timeToExpiryYears: t,
+        right,
+    });
+    const notional = specification.notional ?? 1;
+    return {
+        price: notional * annuity * fwdOption,
+        forwardSwapRate,
+        annuity,
+        ...ratesReport({ model, notional, optionType: specification.optionType, expiryYears: t }),
+    };
+}
+/** {@link CapFloorSpecification} keys (Law 12 — mirrors the interface above; keep in sync). */
+const CAP_FLOOR_SPEC_KEYS = [
+    'startDate',
+    'maturityDate',
+    'strike',
+    'volatility',
+    'type',
+    'notional',
+    'frequency',
+    'dayCount',
+    'model',
+];
+/** Price a cap or floor as a strip of Black/Bachelier caplets/floorlets off discount/forecast curves. */
+export function capFloorPrice(specification, curves) {
+    requireSwapCurves('capFloorPrice', curves);
+    requireRatesConventions('capFloorPrice', specification, [
+        'dayCount',
+        'frequency',
+        'model',
+        'notional',
+    ]);
+    requireArgumentObject('capFloorPrice', 'specification', specification);
+    ensureKnownKeys('capFloorPrice', 'specification', specification, CAP_FLOOR_SPEC_KEYS);
+    if (specification.type !== 'cap' && specification.type !== 'floor') {
+        throw new InputError(`capFloorPrice: type must be 'cap' or 'floor', got "${String(specification.type)}".`, { code: ErrorCode.InputInvalidEnum, context: { type: specification.type } });
+    }
+    const discount = curves.discountCurve;
+    const forecast = curves.forecastCurve ?? discount;
+    const dc = specification.dayCount ?? 'ACT/360';
+    const notional = specification.notional ?? 1;
+    const model = specification.model ?? 'black';
+    const right = specification.type === 'cap' ? 'call' : 'put';
+    const schedule = generateSchedule({
+        effectiveDate: specification.startDate,
+        maturityDate: specification.maturityDate,
+        frequency: specification.frequency ?? 'quarterly',
+    });
+    const caplets = [];
+    let price = 0;
+    // EVERY scheduled period becomes a caplet, including the one that has already fixed. The market
+    // convention for a spot-starting cap is to DROP that first caplet (its rate is known, so it is
+    // not optional); here it is kept and priced at zero time value, i.e. intrinsic. That is a
+    // defensible choice and a material one — it is the difference between two quotes of the same cap
+    // — so it is stated in `assumptions.firstCaplet` rather than left for the caller to rediscover.
+    for (const p of schedule) {
+        const accrual = yearFraction(p.accrualStart, p.accrualEnd, dc);
+        const forwardRate = forecast.forwardRate(p.accrualStart, p.accrualEnd, dc);
+        const expiry = Math.max(0, yearFraction(discount.referenceDate, p.accrualStart, 'ACT/365F'));
+        const fwdOption = priceForward({
+            model,
+            forward: forwardRate,
+            strike: specification.strike,
+            volatility: specification.volatility,
+            timeToExpiryYears: expiry,
+            right,
+        });
+        const value = notional * accrual * discount.discount(p.paymentDate) * fwdOption;
+        caplets.push({ start: p.accrualStart, end: p.accrualEnd, expiry, forwardRate, value });
+        price += value;
+    }
+    return {
+        price,
+        caplets,
+        ...ratesReport({
+            model,
+            notional,
+            dayCount: dc,
+            type: specification.type,
+            /** The already-fixed first period is priced, at intrinsic — not dropped as the market does. */
+            firstCaplet: 'included-at-intrinsic',
+        }),
+    };
+}
+/** {@link CmsSpecification} keys (Law 12 — mirrors the interface above; keep in sync). */
+const CMS_SPEC_KEYS = [
+    'resetDate',
+    'swapTenorYears',
+    'volatility',
+    'fixedFrequency',
+    'fixedDayCount',
+    'floatFrequency',
+    'floatDayCount',
+];
+/** {@link CmsConvexityInput} keys (Law 12 — mirrors the interface above; keep in sync). */
+const CMS_CONVEXITY_INPUT_KEYS = [
+    'forwardSwapRate',
+    'swapTenorYears',
+    'paymentsPerYear',
+    'volatility',
+    'expiry',
+];
+/** The raw Hull adjustment, shared by the public envelope and {@link forwardCmsRate}. */
+function cmsConvexityKernel(input) {
+    const { forwardSwapRate: y, paymentsPerYear: m, swapTenorYears, volatility, expiry } = input;
+    const n = Math.round(swapTenorYears * m);
+    const base = 1 + y / m;
+    let gPrime = 0; // dG/dy
+    let gDouble = 0; // d²G/dy²
+    for (let i = 1; i <= n; i++) {
+        const coupon = y / m + (i === n ? 1 : 0); // par-bond cash flow at period i
+        gPrime += coupon * (-i / m) * Math.pow(base, -i - 1);
+        gDouble += coupon * ((i * (i + 1)) / (m * m)) * Math.pow(base, -i - 2);
+    }
+    if (gPrime === 0)
+        return 0;
+    return -0.5 * y * y * volatility * volatility * expiry * (gDouble / gPrime);
+}
+/**
+ * The standard CMS convexity adjustment (Hull): valuing the swap-rate payoff with the bond function
+ * `G(y) = Σ cᵢ·(1 + y/m)^(−i)` of a par bond paying the swap's fixed cash flows gives
+ * `Δ = −½·y₀²·σ²·T·G''(y₀)/G'(y₀)` (positive, since `G' < 0` and `G'' > 0`). Returns a Law-2
+ * envelope: the adjustment in `value` plus the applied conventions and a warnings channel.
+ */
+export function cmsConvexityAdjustment(specification) {
+    const functionName = 'cmsConvexityAdjustment';
+    requireArgumentObject(functionName, 'specification', specification);
+    ensureKnownKeys(functionName, 'specification', specification, CMS_CONVEXITY_INPUT_KEYS);
+    ensureFinite(specification.forwardSwapRate, 'forwardSwapRate', functionName);
+    ensurePositive(specification.swapTenorYears, 'swapTenorYears', functionName);
+    ensurePositive(specification.paymentsPerYear, 'paymentsPerYear', functionName);
+    ensureNonNegative(specification.volatility, 'volatility', functionName);
+    ensureNonNegative(specification.expiry, 'expiry', functionName);
+    const value = cmsConvexityKernel(specification);
+    return {
+        value,
+        ...ratesReport({
+            swapTenorYears: specification.swapTenorYears,
+            paymentsPerYear: specification.paymentsPerYear,
+            expiryYears: specification.expiry,
+            bondFunction: 'par-bond G(y)',
+        }),
+    };
+}
+/**
+ * Forward CMS rate off a curve: the forward swap rate of the underlying constant-maturity swap plus the
+ * convexity adjustment. Discount the resulting rate on the relevant payment date to value a CMS leg.
+ */
+export function forwardCmsRate(specification, curves) {
+    requireSwapCurves('forwardCmsRate', curves);
+    requireRatesConventions('forwardCmsRate', specification, [
+        'fixedFrequency',
+        'fixedDayCount',
+        'floatFrequency',
+        'floatDayCount',
+        'notional',
+    ]);
+    requireFiniteFields('forwardCmsRate', specification, ['volatility'], {
+        exampleCall: "forwardCmsRate({ effectiveDate: '2026-01-15', maturityDate: '2031-01-15', volatility: 0.2 }, { discountCurve })",
+    });
+    requireArgumentObject('forwardCmsRate', 'specification', specification);
+    ensureKnownKeys('forwardCmsRate', 'specification', specification, CMS_SPEC_KEYS);
+    const discount = curves.discountCurve;
+    const maturity = addMonths(specification.resetDate, 12 * specification.swapTenorYears);
+    const underlying = {
+        startDate: specification.resetDate,
+        maturityDate: maturity,
+        ...(specification.fixedFrequency !== undefined
+            ? { fixedFrequency: specification.fixedFrequency }
+            : {}),
+        ...(specification.fixedDayCount !== undefined
+            ? { fixedDayCount: specification.fixedDayCount }
+            : {}),
+        ...(specification.floatFrequency !== undefined
+            ? { floatFrequency: specification.floatFrequency }
+            : {}),
+        ...(specification.floatDayCount !== undefined
+            ? { floatDayCount: specification.floatDayCount }
+            : {}),
+    };
+    const forwardSwapRate = swapRate(underlying, curves);
+    const expiry = Math.max(0, yearFraction(discount.referenceDate, specification.resetDate, 'ACT/365F'));
+    const m = paymentsPerYear(specification.fixedFrequency ?? 'semiannual');
+    const convexityAdjustment = cmsConvexityKernel({
+        forwardSwapRate,
+        paymentsPerYear: m,
+        swapTenorYears: specification.swapTenorYears,
+        volatility: specification.volatility,
+        expiry,
+    });
+    return {
+        forwardSwapRate,
+        convexityAdjustment,
+        cmsRate: forwardSwapRate + convexityAdjustment,
+        ...ratesReport({
+            swapTenorYears: specification.swapTenorYears,
+            paymentsPerYear: m,
+            expiryYears: expiry,
+        }),
+    };
+}
+//# sourceMappingURL=rates.js.map