@insiderfinance/totalfinance 0.1.0

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

@@ -0,0 +1,951 @@
+/**
+ * Bonds (spec §14.1): fixed-rate, zero-coupon, floating-rate notes, amortizing, and inflation-linked
+ * instruments, with the full analytics suite — clean/dirty price, accrued interest, yield to maturity
+ * and to call, Macaulay / modified / effective / key-rate duration, convexity, and DV01/PV01.
+ *
+ * Yield-based metrics use the actuarial ("true yield") convention: a cash flow at year fraction τ from
+ * settlement (under the bond's day count) is discounted by `(1 + y/f)^(−f·τ)`, where `f` is the bond's
+ * coupon frequency. This is unambiguous, handles stub periods and zero-coupons uniformly, and yields
+ * clean closed-form duration/convexity. Curve-based metrics (effective/key-rate duration) reprice
+ * against a {@link YieldCurve} and its shocks. Floating and inflation coupons are *projected* from the
+ * supplied curve/index, then valued — bad or missing projection inputs throw (no silent degradation).
+ */
+import { requireFiniteFields, CONVENTIONS_VERSION, ConvergenceError, ErrorCode, InputError, ensureKnownKeys, requireArgumentObject, seriesFacade, validateClosedRequest, warning, } from '../../core/dist/index.js';
+import { brent } from '../../math/dist/index.js';
+import { FIELD_HINTS, specificationExampleCall } from './validate.js';
+import { VALIDATION_SPECS } from './generated/validation-specs.js';
+import { compareDates, generateSchedule, paymentsPerYear, yearFraction, } from './conventions.js';
+function faceOf(specification) {
+    const f = specification.faceValue ?? 100;
+    if (!Number.isFinite(f) || f <= 0) {
+        throw new InputError(`faceOf: faceValue must be a positive number (got ${f}).`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { field: 'faceValue', value: f },
+        });
+    }
+    return f;
+}
+/**
+ * Generated closed-request specs (spec 3B.1b): allowlists projected from the declarations —
+ * including the `Amortization` union, whose branch resolution is the shared validator's
+ * discriminant-first path. Resolved at module load so a stale key fails at import.
+ */
+function specOf(key) {
+    const spec = VALIDATION_SPECS[key];
+    if (spec === undefined) {
+        throw new Error(`bonds: no generated validation spec for '${key}' — run \`pnpm validation:update\``);
+    }
+    return spec;
+}
+const FIXED_RATE_SPEC = specOf('bonds.fixedRate#0');
+const ZERO_COUPON_SPEC = specOf('bonds.zeroCoupon#0');
+const FRN_SPEC = specOf('bonds.floatingRateNote#0');
+const AMORTIZING_SPEC = specOf('bonds.amortizing#0');
+const INFLATION_LINKED_SPEC = specOf('bonds.inflationLinked#0');
+const BOND_CONTEXT_SPEC = specOf('Bond#cashflows#0');
+const PRICE_MULTI_CURVE_BOND_SPEC = specOf('priceMultiCurve#0');
+const PRICE_MULTI_CURVE_OPTIONS_SPEC = specOf('priceMultiCurve#1');
+const YIELD_TO_CALL_BOND_SPEC = specOf('yieldToCall#0');
+const YIELD_TO_CALL_CALL_SPEC = specOf('yieldToCall#1');
+const YIELD_TO_CALL_OPTIONS_SPEC = specOf('yieldToCall#2');
+const ANALYTICS_EXAMPLE = () => "yieldToCall(bond, { callDate: '2028-01-15', callPrice: 102 }, { price: 98.5, settlementDate: '2026-06-15' })";
+/** The bespoke bond teaching, unchanged from `requireSpecification`: derived example + unit hints. */
+function specificationTeaching(functionName, required) {
+    return {
+        argumentName: 'specification',
+        subject: true,
+        exampleCall: () => specificationExampleCall(functionName, required),
+        hints: FIELD_HINTS,
+    };
+}
+const CONTEXT_TEACHING = {
+    argumentName: 'context',
+    exampleCall: "bond.futureCashflows('2026-06-15', { forecastCurve, knownFixingRate: 0.0532 })",
+};
+function buildSchedule(specification) {
+    return generateSchedule({
+        effectiveDate: specification.issueDate,
+        maturityDate: specification.maturityDate,
+        frequency: specification.frequency,
+        ...(specification.convention !== undefined ? { convention: specification.convention } : {}),
+        ...(specification.endOfMonth !== undefined ? { endOfMonth: specification.endOfMonth } : {}),
+    });
+}
+/** Assemble the shared `Bond` shell from a precomputed cash-flow generator. */
+function makeBond(kind, specification, schedule, flowsFor) {
+    const face = faceOf(specification);
+    const dayCount = specification.dayCount ?? '30/360';
+    const frequency = paymentsPerYear(specification.frequency);
+    const accrued = (settlementDate, context = {}) => {
+        validateClosedRequest('bond.accrued', context, BOND_CONTEXT_SPEC, CONTEXT_TEACHING);
+        const period = schedule.find((p) => compareDates(p.accrualStart, settlementDate) <= 0 &&
+            compareDates(settlementDate, p.accrualEnd) < 0);
+        if (!period)
+            return 0; // before issue or on/after maturity
+        const full = yearFraction(period.accrualStart, period.accrualEnd, dayCount);
+        const partial = yearFraction(period.accrualStart, settlementDate, dayCount);
+        const frac = full === 0 ? 0 : partial / full;
+        // The interest the *current* period will pay, scaled by the elapsed fraction.
+        const flow = flowsFor(context).find((f) => f.date === period.accrualEnd);
+        return flow ? flow.interest * frac : 0;
+    };
+    return {
+        kind,
+        faceValue: face,
+        issueDate: specification.issueDate,
+        maturityDate: specification.maturityDate,
+        couponRate: specification.couponRate,
+        frequency,
+        dayCount,
+        // Mirrors the default in `generateSchedule` (buildSchedule omits it when spec.convention is unset).
+        businessDayConvention: specification.convention ?? 'modifiedFollowing',
+        schedule,
+        cashflows: (context = {}) => {
+            validateClosedRequest('bond.cashflows', context, BOND_CONTEXT_SPEC, CONTEXT_TEACHING);
+            return flowsFor(context);
+        },
+        futureCashflows: (settlementDate, context = {}) => {
+            validateClosedRequest('bond.futureCashflows', context, BOND_CONTEXT_SPEC, CONTEXT_TEACHING);
+            return flowsFor(context).filter((f) => compareDates(f.date, settlementDate) > 0);
+        },
+        accrued,
+    };
+}
+function fixedRate(specification) {
+    validateClosedRequest('bonds.fixedRate', specification, FIXED_RATE_SPEC, specificationTeaching('bonds.fixedRate', [
+        'issueDate',
+        'maturityDate',
+        'couponRate',
+        'frequency',
+    ]));
+    const face = faceOf(specification);
+    const dayCount = specification.dayCount ?? '30/360';
+    const schedule = buildSchedule(specification);
+    const last = schedule.length - 1;
+    const flowsFor = () => schedule.map((p, i) => {
+        const interest = specification.couponRate * face * yearFraction(p.accrualStart, p.accrualEnd, dayCount);
+        const principal = i === last ? face : 0;
+        return {
+            date: p.accrualEnd,
+            paymentDate: p.paymentDate,
+            interest,
+            principal,
+            amount: interest + principal,
+            notional: face,
+        };
+    });
+    return makeBond('fixed', specification, schedule, flowsFor);
+}
+function zeroCoupon(specification) {
+    validateClosedRequest('bonds.zeroCoupon', specification, ZERO_COUPON_SPEC, specificationTeaching('bonds.zeroCoupon', ['issueDate', 'maturityDate']));
+    const face = faceOf(specification);
+    const base = {
+        issueDate: specification.issueDate,
+        maturityDate: specification.maturityDate,
+        couponRate: 0,
+        frequency: specification.frequency ?? 'annual',
+        ...(specification.faceValue !== undefined ? { faceValue: specification.faceValue } : {}),
+        ...(specification.dayCount !== undefined ? { dayCount: specification.dayCount } : {}),
+    };
+    // A single redemption flow at maturity — no coupon schedule.
+    const schedule = [
+        {
+            accrualStart: specification.issueDate,
+            accrualEnd: specification.maturityDate,
+            paymentDate: specification.maturityDate,
+            isStub: false,
+        },
+    ];
+    const flowsFor = () => [
+        {
+            date: specification.maturityDate,
+            paymentDate: specification.maturityDate,
+            interest: 0,
+            principal: face,
+            amount: face,
+            notional: face,
+        },
+    ];
+    return makeBond('zero', base, schedule, flowsFor);
+}
+/**
+ * Resolve the index rate for ONE floating coupon: the curve's forward when the reset is still in
+ * the future, the caller's observed fixing when the reset already happened.
+ *
+ * A forecast curve begins at its reference date, so `curve.forwardRate` over a period that STARTED
+ * before it is a query before t = 0 and throws `Curve query before reference date (t=−0.08)`. That
+ * is the correct refusal from the curve and a useless message from the FRN: settling any FRN
+ * between two coupon dates hits it, and nothing in the error names the missing input. The in-progress
+ * coupon is not a projection at all — it was fixed on a past reset date — so the caller supplies it
+ * via {@link ProjectionContext.knownFixingRate}.
+ */
+function projectFrnRate(period, curve, dayCount, context) {
+    if (compareDates(period.accrualStart, curve.referenceDate) >= 0) {
+        return curve.forwardRate(period.accrualStart, period.accrualEnd, dayCount);
+    }
+    // The reset predates the curve. Only a coupon still ACCRUING at the reference date is a single,
+    // nameable fixing; a coupon that also ENDED before it is settled history.
+    if (compareDates(period.accrualEnd, curve.referenceDate) <= 0) {
+        throw new InputError(`projectFrnRate: A floating-rate note coupon accruing ${period.accrualStart} → ${period.accrualEnd} ended before ` +
+            `the forecast curve's reference date (${curve.referenceDate}): it was set by a historical ` +
+            'index print, which a forward curve cannot supply, and one fixing cannot stand in for a strip ' +
+            'of past resets. Build the note from the coupon period in progress (issueDate = the last ' +
+            'reset date) and pass that reset via context.knownFixingRate, or use a forecast curve whose ' +
+            "referenceDate is on or before the note's issueDate.", {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                kind: 'frn',
+                accrualStart: period.accrualStart,
+                accrualEnd: period.accrualEnd,
+                curveReferenceDate: curve.referenceDate,
+            },
+        });
+    }
+    const fixing = context.knownFixingRate;
+    if (fixing === undefined) {
+        throw new InputError(`projectFrnRate: A floating-rate note settling mid-period needs context.knownFixingRate: the coupon accruing ` +
+            `${period.accrualStart} → ${period.accrualEnd} was FIXED on ${period.accrualStart}, before the ` +
+            `forecast curve's reference date (${curve.referenceDate}), so the curve cannot project it. ` +
+            'Pass the observed index fixing for that reset (a decimal, e.g. 0.0532 for 5.32%).\n' +
+            '  e.g. priceMultiCurve(frn, { settlementDate, discountCurve, forecastCurve }) with\n' +
+            '       frn.cashflows({ forecastCurve, knownFixingRate: 0.0532 })', {
+            code: ErrorCode.InputMissingField,
+            context: {
+                kind: 'frn',
+                field: 'knownFixingRate',
+                accrualStart: period.accrualStart,
+                accrualEnd: period.accrualEnd,
+                curveReferenceDate: curve.referenceDate,
+            },
+        });
+    }
+    if (!Number.isFinite(fixing)) {
+        throw new InputError(`context.knownFixingRate must be a finite decimal rate (got ${fixing}).`, {
+            code: ErrorCode.InputNotFinite,
+            context: { field: 'knownFixingRate', value: fixing },
+        });
+    }
+    return fixing;
+}
+function floatingRateNote(specification) {
+    validateClosedRequest('bonds.floatingRateNote', specification, FRN_SPEC, specificationTeaching('bonds.floatingRateNote', ['issueDate', 'maturityDate', 'frequency']));
+    const face = faceOf(specification);
+    const dayCount = specification.dayCount ?? 'ACT/360';
+    const spread = specification.spread ?? 0;
+    const baseSpecification = { ...specification, dayCount };
+    const schedule = buildSchedule(baseSpecification);
+    const last = schedule.length - 1;
+    const flowsFor = (context) => {
+        const curve = context.forecastCurve;
+        if (!curve) {
+            throw new InputError('flowsFor: A floating-rate note needs context.forecastCurve to project its coupons.', {
+                code: ErrorCode.InputMissingField,
+                context: { kind: 'frn' },
+            });
+        }
+        return schedule.map((p, i) => {
+            const accrual = yearFraction(p.accrualStart, p.accrualEnd, dayCount);
+            const forward = projectFrnRate(p, curve, dayCount, context);
+            const interest = (forward + spread) * face * accrual;
+            const principal = i === last ? face : 0;
+            return {
+                date: p.accrualEnd,
+                paymentDate: p.paymentDate,
+                interest,
+                principal,
+                amount: interest + principal,
+                notional: face,
+            };
+        });
+    };
+    return makeBond('frn', baseSpecification, schedule, flowsFor);
+}
+function amortizing(specification) {
+    validateClosedRequest('bonds.amortizing', specification, AMORTIZING_SPEC, specificationTeaching('bonds.amortizing', [
+        'issueDate',
+        'maturityDate',
+        'couponRate',
+        'frequency',
+    ]));
+    const face = faceOf(specification);
+    const dayCount = specification.dayCount ?? '30/360';
+    const baseSpecification = { ...specification, dayCount };
+    const schedule = buildSchedule(baseSpecification);
+    const n = schedule.length;
+    const principalSchedule = () => {
+        const amort = specification.amortization;
+        if ('principalByPeriod' in amort) {
+            if (amort.principalByPeriod.length !== n) {
+                throw new InputError(`principalSchedule: principalByPeriod has ${amort.principalByPeriod.length} entries but the schedule has ${n} periods.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { expected: n, got: amort.principalByPeriod.length },
+                });
+            }
+            const total = amort.principalByPeriod.reduce((s, x) => s + x, 0);
+            if (Math.abs(total - face) > 1e-6 * face) {
+                throw new InputError(`principalSchedule: principalByPeriod sums to ${total}, expected the face value ${face}.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { total, face },
+                });
+            }
+            return [...amort.principalByPeriod];
+        }
+        if (amort.type === 'straight') {
+            return schedule.map(() => face / n);
+        }
+        // annuity: solve a level total payment A using each period's actual rate.
+        const rates = schedule.map((p) => specification.couponRate * yearFraction(p.accrualStart, p.accrualEnd, dayCount));
+        // For equal periods these are all c = couponRate/f; A = face·c/(1−(1+c)^−n). Use period 0's rate.
+        const c = rates[0];
+        let outstanding = face;
+        const principals = [];
+        if (c === 0) {
+            // No interest ⇒ equal principal.
+            return schedule.map(() => face / n);
+        }
+        const A = (face * c) / (1 - Math.pow(1 + c, -n));
+        for (let i = 0; i < n; i++) {
+            const interest = outstanding * rates[i];
+            let principal = A - interest;
+            if (i === n - 1)
+                principal = outstanding; // clean up rounding on the final period
+            principals.push(principal);
+            outstanding -= principal;
+        }
+        return principals;
+    };
+    const flowsFor = () => {
+        const principals = principalSchedule();
+        let outstanding = face;
+        return schedule.map((p, i) => {
+            const accrual = yearFraction(p.accrualStart, p.accrualEnd, dayCount);
+            const interest = specification.couponRate * outstanding * accrual;
+            const principal = principals[i];
+            const notional = outstanding;
+            outstanding -= principal;
+            return {
+                date: p.accrualEnd,
+                paymentDate: p.paymentDate,
+                interest,
+                principal,
+                amount: interest + principal,
+                notional,
+            };
+        });
+    };
+    return makeBond('amortizing', baseSpecification, schedule, flowsFor);
+}
+function inflationLinked(specification) {
+    validateClosedRequest('bonds.inflationLinked', specification, INFLATION_LINKED_SPEC, specificationTeaching('bonds.inflationLinked', [
+        'issueDate',
+        'maturityDate',
+        'couponRate',
+        'frequency',
+    ]));
+    const face = faceOf(specification);
+    const dayCount = specification.dayCount ?? 'ACT/ACT';
+    const baseSpecification = { ...specification, dayCount };
+    const schedule = buildSchedule(baseSpecification);
+    const last = schedule.length - 1;
+    if (!Number.isFinite(specification.baseIndex) || specification.baseIndex <= 0) {
+        throw new InputError(`inflationLinked: baseIndex must be positive (got ${specification.baseIndex}).`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { field: 'baseIndex', value: specification.baseIndex },
+        });
+    }
+    const flowsFor = (context) => {
+        const index = context.referenceIndex;
+        if (!index) {
+            throw new InputError('flowsFor: An inflation-linked bond needs context.referenceIndex to index its cash flows.', {
+                code: ErrorCode.InputMissingField,
+                context: { kind: 'inflation' },
+            });
+        }
+        return schedule.map((p, i) => {
+            const ratio = index(p.accrualEnd) / specification.baseIndex;
+            if (!Number.isFinite(ratio) || ratio <= 0) {
+                throw new InputError(`flowsFor: referenceIndex(${p.accrualEnd}) produced a non-positive index ratio.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: { date: p.accrualEnd, ratio },
+                });
+            }
+            const interest = specification.couponRate *
+                face *
+                yearFraction(p.accrualStart, p.accrualEnd, dayCount) *
+                ratio;
+            let principal = 0;
+            if (i === last) {
+                const uplifted = face * ratio;
+                principal = specification.deflationFloor ? Math.max(uplifted, face) : uplifted;
+            }
+            return {
+                date: p.accrualEnd,
+                paymentDate: p.paymentDate,
+                interest,
+                principal,
+                amount: interest + principal,
+                notional: face * ratio,
+            };
+        });
+    };
+    return makeBond('inflation', baseSpecification, schedule, flowsFor);
+}
+/** Bond constructors (spec §14.1). */
+export const bonds = {
+    fixedRate,
+    zeroCoupon,
+    floatingRateNote,
+    amortizing,
+    inflationLinked,
+};
+// ---------------------------------------------------------------------------------------------------
+// Pricing & metrics
+// ---------------------------------------------------------------------------------------------------
+/**
+ * Guard the actuarial discount base `1 + y/f`. A yield at or below `−f` (e.g. `y = −2` at annual
+ * frequency) drives the base non-positive, which makes `base^(−f·τ)` return NaN or a sign-flipped
+ * price (a one-year zero would report `−100`). Reject it rather than emit a bogus number.
+ */
+function actuarialBase(y, f, functionName) {
+    if (!Number.isFinite(y)) {
+        throw new InputError(`${functionName}: yield must be finite, got ${y}.`, {
+            code: ErrorCode.InputNotFinite,
+            context: { yield: y },
+        });
+    }
+    const base = 1 + y / f;
+    if (!(base > 0)) {
+        throw new InputError(`${functionName}: yield ${y} implies a non-positive actuarial base (1 + y/${f} = ${base}); price is undefined. Yields must satisfy y > −${f}.`, { code: ErrorCode.InputOutOfRange, context: { yield: y, frequency: f, base } });
+    }
+    return base;
+}
+/**
+ * Ceiling on the expanding yield bracket: 1000%. Past this a "yield" is no longer a yield — the
+ * price is almost certainly wrong (a typo, the wrong settlement date, or a defaulted bond quoted in
+ * points upfront), and reporting a four-digit percentage would dress that up as an answer.
+ */
+const MAXIMUM_YIELD_BRACKET = 10;
+/**
+ * Bracket and solve a yield root, EXPANDING the upper bound until the objective changes sign
+ * (doubling from 100%, capped at {@link MAXIMUM_YIELD_BRACKET}).
+ *
+ * The bracket used to be the hard-coded `[−0.99·f, 1]`. Any distressed bond — a 1-year zero at 40
+ * yields 150% — has its root outside it, so Brent found no sign change and the caller was told the
+ * solve "did not converge": a true statement that named the wrong cause and suggested a numerical
+ * flaw rather than a bracket that never contained the answer. Beyond the cap the error now names
+ * the interval actually searched.
+ */
+function solveYieldBracketed(objective, frequency, functionName, context) {
+    // Yield must exceed −f (so 1 + y/f > 0); bracket just above that singularity.
+    const lo = -frequency * 0.99;
+    let hi = 1.0;
+    const fLo = objective(lo);
+    let fHi = objective(hi);
+    let expansions = 0;
+    while (Number.isFinite(fLo) &&
+        Number.isFinite(fHi) &&
+        fLo * fHi > 0 &&
+        hi < MAXIMUM_YIELD_BRACKET) {
+        hi = Math.min(hi * 2, MAXIMUM_YIELD_BRACKET);
+        fHi = objective(hi);
+        expansions++;
+    }
+    const res = brent(objective, lo, hi, { stepTolerance: 1e-12, maximumIterations: 200 });
+    if (!res.converged) {
+        const asPercent = (y) => `${(y * 100).toFixed(1)}%`;
+        throw new ConvergenceError(`${functionName}: no yield in the bracket searched — [${asPercent(lo)}, ${asPercent(hi)}] ` +
+            `(expanded upward from 100% to at most ${asPercent(MAXIMUM_YIELD_BRACKET)}) — reprices the ` +
+            'bond to the target price. A price outside that range is usually a mis-entered price, the ' +
+            'wrong settlement date, or a defaulted bond quoted in points upfront rather than on yield.', {
+            code: ErrorCode.SolverNoConvergence,
+            context: {
+                ...context,
+                bracketSearched: [lo, hi],
+                bracketExpansions: expansions,
+                iterations: res.iterations,
+                reason: res.reason,
+            },
+        });
+    }
+    return { value: res.value, iterations: res.iterations + expansions };
+}
+/** Discount a future cash-flow set at yield `y` (actuarial convention) → dirty price. */
+function dirtyFromYield(flows, settlementDate, y, f, dayCount) {
+    const base = actuarialBase(y, f, 'priceFromYield');
+    let pv = 0;
+    for (const cf of flows) {
+        const tau = yearFraction(settlementDate, cf.date, dayCount);
+        pv += cf.amount * Math.pow(base, -f * tau);
+    }
+    return pv;
+}
+/**
+ * The fixed-income twin of core's `plausibilityWarnings`: a coupon rate is a DECIMAL (`0.05` = 5%),
+ * so `couponRate: 5` is a 500% coupon. It prices, it solves, and every duration and DV01 downstream
+ * is nonsense — with nothing in the output to say so. Informational, never thrown: a 150% coupon is
+ * legal in distressed/EM paper, so the threshold is 100% and the verdict is the caller's.
+ */
+function couponRateWarnings(bond) {
+    const couponRate = bond.couponRate;
+    if (!Number.isFinite(couponRate) || Math.abs(couponRate) <= 1)
+        return [];
+    return [
+        warning(ErrorCode.InputSuspiciousCouponRate, `couponRate=${couponRate} implies a ${(couponRate * 100).toFixed(0)}% coupon — couponRate is a ` +
+            `decimal; did you mean ${(couponRate / 100).toFixed(4)}?`, 'info', { couponRate }),
+    ];
+}
+/** Build the conventions echo for a bond result. */
+function bondAssumptions(bond, settlementDate, compounding) {
+    return {
+        conventionsVersion: CONVENTIONS_VERSION,
+        dayCount: bond.dayCount,
+        compounding,
+        frequency: bond.frequency,
+        settlementDate,
+        businessDayConvention: bond.businessDayConvention,
+    };
+}
+/**
+ * Build a bond facade on core `seriesFacade` (label first, shared first-argument guard). The only
+ * departure from the stock helper is the envelope's assumptions type: {@link BondAssumptions}
+ * widens `dayCount`/`compounding` past the core enums, which `Computed<T, Extra>` cannot express as
+ * an `Extra` intersection — the runtime shape is exactly the core envelope, so the casts below are
+ * type-level only.
+ */
+/**
+ * The bond analytics facades take a Bond INSTANCE (from `bonds.fixedRate(...)` et al.), not a raw
+ * spec object — a plain `{ couponRate, … }` would crash on the first method call, so it teaches.
+ */
+function requireBondInstance(bond, functionName) {
+    const b = bond;
+    if (typeof b.futureCashflows !== 'function' || typeof b.accrued !== 'function') {
+        throw new InputError(`${functionName}: expected a bond built by bonds.fixedRate(...) / bonds.zeroCoupon(...) (a Bond instance with cash-flow methods), not a raw specification object. Build the bond first, then pass it here.`, { code: ErrorCode.InputWrongType, context: { function: functionName, field: 'bond' } });
+    }
+    // Bonds are structurally typed artifacts. Validate the methods we consume while allowing
+    // provenance, identifiers, and downstream risk metadata to decorate the object.
+}
+/**
+ * Curve parameters take a curve INSTANCE (from `curves.fromZeroRates(...)`, `curves.bootstrap(...)`),
+ * not a raw pillar list — teach the fix instead of crashing on the first method call.
+ */
+function requireCurveInstance(curve, functionName) {
+    const c = curve;
+    if (typeof c.discount !== 'function' ||
+        typeof c.shift !== 'function' ||
+        !Array.isArray(c.pillars)) {
+        throw new InputError(`${functionName}: expected a curve built by curves.fromZeroRates(...) / curves.bootstrap(...) (a Curve instance with discount()/shift()), not a raw object. Build the curve first, then pass it here.`, { code: ErrorCode.InputWrongType, context: { function: functionName, field: 'curve' } });
+    }
+}
+function bondFacade(label, call, explain) {
+    return seriesFacade(label, call, explain);
+}
+/** {@link PriceFromYieldOptions} keys (Law 12 — mirrors the interface above; keep in sync). */
+const PRICE_FROM_YIELD_OPTIONS_KEYS = ['settlementDate', 'yield', 'context'];
+function priceFromYieldValue(bond, options) {
+    requireArgumentObject('priceFromYield', 'options', options);
+    ensureKnownKeys('priceFromYield', 'options', options, PRICE_FROM_YIELD_OPTIONS_KEYS);
+    requireAnalyticsOptionLadders('priceFromYield', options);
+    requireArgumentObject('priceFromYield', 'bond', bond);
+    requireBondInstance(bond, 'priceFromYield');
+    const flows = bond.futureCashflows(options.settlementDate, options.context);
+    const dirty = dirtyFromYield(flows, options.settlementDate, options.yield, bond.frequency, bond.dayCount);
+    const accruedInterest = bond.accrued(options.settlementDate, options.context);
+    return {
+        dirtyPrice: dirty,
+        cleanPrice: dirty - accruedInterest,
+        accruedInterest,
+        assumptions: bondAssumptions(bond, options.settlementDate, 'actuarial'),
+        diagnostics: { method: 'closed-form', warnings: couponRateWarnings(bond) },
+    };
+}
+/**
+ * Dirty/clean price and accrued interest for a bond at a given yield. Facade (dx §2.7): the plain
+ * call returns the rich {@link BondPrice}; `.explain()` wraps the same result in the core envelope
+ * with the conventions echoed at the top level.
+ */
+export const priceFromYield = bondFacade('priceFromYield', priceFromYieldValue, (bond, options) => {
+    const price = priceFromYieldValue(bond, options);
+    return { value: price, assumptions: price.assumptions, diagnostics: price.diagnostics };
+});
+/** {@link YieldFromPriceOptions} keys (Law 12 — mirrors the interface above; keep in sync). */
+const YIELD_FROM_PRICE_OPTIONS_KEYS = ['settlementDate', 'price', 'priceType', 'context'];
+/**
+ * Shared analytics-option ladders: `context: null` used to reach `bond.cashflows(null)` and the
+ * settlementDate string flowed unchecked into date arithmetic.
+ */
+function requireAnalyticsOptionLadders(functionName, options) {
+    const context = options['context'];
+    if (context !== undefined && (context === null || typeof context !== 'object')) {
+        throw new InputError(`${functionName}: context must be a projection-context object when provided. Received ${context === null ? 'null' : typeof context}.`, { code: ErrorCode.InputWrongType, context: { field: 'context' } });
+    }
+    const settlementDate = options['settlementDate'];
+    if (settlementDate !== undefined &&
+        (typeof settlementDate !== 'string' || settlementDate.length === 0)) {
+        throw new InputError(`${functionName}: settlementDate must be an ISO date string when provided. Received ${settlementDate === null ? 'null' : typeof settlementDate}.`, { code: ErrorCode.InputWrongType, context: { field: 'settlementDate' } });
+    }
+    // The context MEMBERS the projection consumes (C05: validate consumed fields, teach each type).
+    if (context !== undefined) {
+        const projection = context;
+        const forecastCurve = projection['forecastCurve'];
+        if (forecastCurve !== undefined &&
+            (forecastCurve === null || typeof forecastCurve !== 'object')) {
+            throw new InputError(`${functionName}: context.forecastCurve must be a yield-curve object when provided. Received ${forecastCurve === null ? 'null' : typeof forecastCurve}.`, { code: ErrorCode.InputWrongType, context: { field: 'context.forecastCurve' } });
+        }
+        const referenceIndex = projection['referenceIndex'];
+        if (referenceIndex !== undefined && typeof referenceIndex !== 'function') {
+            throw new InputError(`${functionName}: context.referenceIndex must be a function (date => index level) when provided. Received ${referenceIndex === null ? 'null' : typeof referenceIndex}.`, { code: ErrorCode.InputWrongType, context: { field: 'context.referenceIndex' } });
+        }
+        const knownFixingRate = projection['knownFixingRate'];
+        if (knownFixingRate !== undefined &&
+            (typeof knownFixingRate !== 'number' || !Number.isFinite(knownFixingRate))) {
+            throw new InputError(`${functionName}: context.knownFixingRate must be a finite decimal rate when provided. Received ${knownFixingRate === null ? 'null' : typeof knownFixingRate}.`, { code: ErrorCode.InputWrongType, context: { field: 'context.knownFixingRate' } });
+        }
+    }
+}
+/** Pre-coalesce enum ladder: `priceType: null` must never silently quote clean. */
+function resolvePriceType(value) {
+    if (value === undefined)
+        return 'clean';
+    if (value !== 'clean' && value !== 'dirty') {
+        throw new InputError(`resolvePriceType: priceType must be 'clean' | 'dirty' when provided — omit the field for a clean quote. Received ${value === null ? 'null' : JSON.stringify(value)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'priceType', received: value } });
+    }
+    return value;
+}
+/** Root-find the YTM; returns the solver facts so the explain path can disclose them honestly. */
+function solveYieldToMaturity(bond, options) {
+    requireArgumentObject('yieldToMaturity', 'options', options);
+    ensureKnownKeys('yieldToMaturity', 'options', options, YIELD_FROM_PRICE_OPTIONS_KEYS);
+    requireAnalyticsOptionLadders('yieldToMaturity', options);
+    // `price` is declared REQUIRED: a null price used to root-find against NaN and report
+    // non-convergence instead of teaching the missing field.
+    requireFiniteFields('yieldToMaturity', options, ['price'], {
+        exampleCall: "yieldToMaturity(bond, { price: 98.5, settlementDate: '2026-06-15' })",
+    });
+    requireArgumentObject('yieldToMaturity', 'bond', bond);
+    requireBondInstance(bond, 'yieldToMaturity');
+    const flows = bond.futureCashflows(options.settlementDate, options.context);
+    if (flows.length === 0) {
+        throw new InputError('solveYieldToMaturity: No cash flows after the settlement date — cannot solve a yield.', {
+            code: ErrorCode.InputOutOfRange,
+            context: { settlementDate: options.settlementDate },
+        });
+    }
+    const accruedInterest = bond.accrued(options.settlementDate, options.context);
+    const targetDirty = resolvePriceType(options.priceType) === 'dirty'
+        ? options.price
+        : options.price + accruedInterest;
+    const f = bond.frequency;
+    const objective = (y) => dirtyFromYield(flows, options.settlementDate, y, f, bond.dayCount) - targetDirty;
+    return solveYieldBracketed(objective, f, 'yieldToMaturity', {
+        targetPrice: options.price,
+        settlementDate: options.settlementDate,
+    });
+}
+/**
+ * Solve the yield to maturity that reprices a bond to the observed price (Brent on [−0.99·f, 1]).
+ * Facade (dx §2.7): the plain call returns the bare yield; `.explain()` returns the core envelope
+ * echoing the bond's conventions plus honest solver diagnostics (this is a root-find, so
+ * `converged`/`iterations` are disclosed — a non-converged solve throws rather than returning).
+ */
+export const yieldToMaturity = bondFacade('yieldToMaturity', (bond, options) => solveYieldToMaturity(bond, options).value, (bond, options) => {
+    const res = solveYieldToMaturity(bond, options);
+    return {
+        value: res.value,
+        assumptions: bondAssumptions(bond, options.settlementDate, 'actuarial'),
+        diagnostics: {
+            method: 'brent',
+            converged: true,
+            iterations: res.iterations,
+            warnings: couponRateWarnings(bond),
+        },
+    };
+});
+/** {@link YieldMetricsOptions} keys (Law 12 — mirrors the interface above; keep in sync). */
+const YIELD_METRICS_OPTIONS_KEYS = ['settlementDate', 'yield', 'context'];
+function yieldMetricsValue(bond, options) {
+    requireArgumentObject('yieldMetrics', 'options', options);
+    ensureKnownKeys('yieldMetrics', 'options', options, YIELD_METRICS_OPTIONS_KEYS);
+    requireAnalyticsOptionLadders('yieldMetrics', options);
+    requireArgumentObject('yieldMetrics', 'bond', bond);
+    requireBondInstance(bond, 'yieldMetrics');
+    const flows = bond.futureCashflows(options.settlementDate, options.context);
+    const f = bond.frequency;
+    const y = options.yield;
+    const base = actuarialBase(y, f, 'yieldMetrics');
+    let pv = 0;
+    let dur = 0; // Σ τ·PV
+    let cvx = 0; // Σ τ(τ+1/f)·PV
+    for (const cf of flows) {
+        const tau = yearFraction(options.settlementDate, cf.date, bond.dayCount);
+        const pvk = cf.amount * Math.pow(base, -f * tau);
+        pv += pvk;
+        dur += tau * pvk;
+        cvx += tau * (tau + 1 / f) * pvk;
+    }
+    const macaulay = pv === 0 ? 0 : dur / pv;
+    const modified = macaulay / base;
+    const convexity = pv === 0 ? 0 : cvx / (pv * base * base);
+    const accruedInterest = bond.accrued(options.settlementDate, options.context);
+    const dv01 = modified * pv * 1e-4;
+    return {
+        yield: y,
+        dirtyPrice: pv,
+        cleanPrice: pv - accruedInterest,
+        accruedInterest,
+        macaulayDuration: macaulay,
+        modifiedDuration: modified,
+        convexity,
+        dv01,
+        pv01: dv01,
+        assumptions: bondAssumptions(bond, options.settlementDate, 'actuarial'),
+        diagnostics: { method: 'closed-form', warnings: couponRateWarnings(bond) },
+    };
+}
+/**
+ * Full set of yield-based risk metrics at a given yield (actuarial convention). Duration and
+ * convexity are the closed-form analytic sensitivities of the dirty price to a parallel yield move.
+ * Facade (dx §2.7): the plain call returns the rich {@link YieldMetrics}; `.explain()` wraps the
+ * same result in the core envelope with the conventions echoed at the top level.
+ */
+export const yieldMetrics = bondFacade('yieldMetrics', yieldMetricsValue, (bond, options) => {
+    const metrics = yieldMetricsValue(bond, options);
+    return { value: metrics, assumptions: metrics.assumptions, diagnostics: metrics.diagnostics };
+});
+// ---- curve-based pricing & effective/key-rate risk ----
+/** Dirty price discounting each cash flow on `curve` from the settlement date (single-curve). */
+function dirtyFromCurve(bond, curve, settlementDate, context) {
+    // Single-curve effective risk: floating coupons project off the (possibly shocked) curve itself, so
+    // a curve bump moves coupons and discounting together — that is what gives an FRN ~zero duration.
+    const projectionCtx = bond.kind === 'frn' ? { ...context, forecastCurve: curve } : context;
+    const flows = bond.futureCashflows(settlementDate, projectionCtx);
+    const dfSettle = curve.discount(settlementDate);
+    let pv = 0;
+    for (const cf of flows) {
+        pv += cf.amount * (curve.discount(cf.paymentDate) / dfSettle);
+    }
+    return pv;
+}
+/** {@link CurvePricingOptions} keys (Law 12 — mirrors the interface above; keep in sync). */
+const CURVE_PRICING_OPTIONS_KEYS = ['settlementDate', 'context', 'bump'];
+function curveMetricsValue(bond, curve, options) {
+    requireArgumentObject('curveMetrics', 'curve', curve);
+    requireCurveInstance(curve, 'curveMetrics');
+    requireArgumentObject('curveMetrics', 'options', options);
+    ensureKnownKeys('curveMetrics', 'options', options, CURVE_PRICING_OPTIONS_KEYS);
+    requireAnalyticsOptionLadders('curveMetrics', options);
+    requireArgumentObject('curveMetrics', 'bond', bond);
+    requireBondInstance(bond, 'curveMetrics');
+    if (options.context !== undefined &&
+        (options.context === null || typeof options.context !== 'object')) {
+        throw new InputError(`curveMetrics: context must be a projection-context object when provided. Received ${options.context === null ? 'null' : typeof options.context}.`, { code: ErrorCode.InputWrongType, context: { field: 'context' } });
+    }
+    if (options.bump !== undefined &&
+        (typeof options.bump !== 'number' || !Number.isFinite(options.bump))) {
+        throw new InputError(`curveMetrics: bump must be a finite rate shift when provided (1e-4 = one basis point). Received ${options.bump === null ? 'null' : typeof options.bump}.`, { code: ErrorCode.InputWrongType, context: { field: 'bump' } });
+    }
+    const context = options.context ?? {};
+    const bump = options.bump ?? 1e-4;
+    const settle = options.settlementDate;
+    const p0 = dirtyFromCurve(bond, curve, settle, context);
+    const pUp = dirtyFromCurve(bond, curve.shift(bump), settle, context);
+    const pDn = dirtyFromCurve(bond, curve.shift(-bump), settle, context);
+    const effectiveDuration = p0 === 0 ? 0 : (pDn - pUp) / (2 * p0 * bump);
+    const effectiveConvexity = p0 === 0 ? 0 : (pUp + pDn - 2 * p0) / (p0 * bump * bump);
+    const dv01 = effectiveDuration * p0 * 1e-4;
+    const keyRateDurations = curve.pillars.map((pillar, i) => {
+        const up = dirtyFromCurve(bond, curve.bumpPillar(i, bump), settle, context);
+        const dn = dirtyFromCurve(bond, curve.bumpPillar(i, -bump), settle, context);
+        return {
+            tenorYears: pillar.tenorYears,
+            date: pillar.date,
+            duration: p0 === 0 ? 0 : (dn - up) / (2 * p0 * bump),
+        };
+    });
+    const accruedInterest = bond.accrued(settle, context);
+    return {
+        dirtyPrice: p0,
+        cleanPrice: p0 - accruedInterest,
+        accruedInterest,
+        effectiveDuration,
+        effectiveConvexity,
+        dv01,
+        keyRateDurations,
+        assumptions: bondAssumptions(bond, settle, 'curve'),
+        diagnostics: { method: 'finite-difference', warnings: couponRateWarnings(bond) },
+    };
+}
+/**
+ * Price a bond against a discount curve and report effective/key-rate risk from curve shocks.
+ * Facade (dx §2.7): the plain call returns the rich {@link CurveMetrics}; `.explain()` wraps the
+ * same result in the core envelope with the conventions echoed at the top level.
+ */
+export const curveMetrics = bondFacade('curveMetrics', curveMetricsValue, (bond, curve, options) => {
+    const metrics = curveMetricsValue(bond, curve, options);
+    return { value: metrics, assumptions: metrics.assumptions, diagnostics: metrics.diagnostics };
+});
+/** The options shape `priceMultiCurve` accepts (Law 12 — mirrors the parameter type; keep in sync). */
+const MULTI_CURVE_PRICING_OPTIONS_KEYS = [
+    'settlementDate',
+    'discountCurve',
+    'forecastCurve',
+    'knownFixingRate',
+];
+/**
+ * Price a bond with separate discount and forecast curves (multi-curve framework, no shock).
+ *
+ * `knownFixingRate` is the FRN in-progress coupon's observed reset — see
+ * {@link ProjectionContext.knownFixingRate}. It is surfaced here because this is the multi-curve
+ * pricing front door: without it, an FRN settled between two coupon dates could not be priced
+ * through the function most callers reach for.
+ */
+export function priceMultiCurve(bond, options) {
+    // The bond is an OPEN structural artifact (manifest policy, C05): consumed fields run their
+    // ladders, decoration is preserved. The options request stays closed.
+    validateClosedRequest('priceMultiCurve', bond, PRICE_MULTI_CURVE_BOND_SPEC, {
+        argumentName: 'bond',
+        open: true,
+        exampleCall: ANALYTICS_EXAMPLE,
+    });
+    validateClosedRequest('priceMultiCurve', options, PRICE_MULTI_CURVE_OPTIONS_SPEC, {
+        argumentName: 'options',
+        exampleCall: ANALYTICS_EXAMPLE,
+    });
+    requireArgumentObject('priceMultiCurve', 'options', options);
+    ensureKnownKeys('priceMultiCurve', 'options', options, MULTI_CURVE_PRICING_OPTIONS_KEYS);
+    requireArgumentObject('priceMultiCurve', 'bond', bond);
+    requireBondInstance(bond, 'priceMultiCurve');
+    // A missing/raw discountCurve would die on the first discount() call — teach at the boundary.
+    requireArgumentObject('priceMultiCurve', 'options.discountCurve', options.discountCurve);
+    requireCurveInstance(options.discountCurve, 'priceMultiCurve');
+    if (options.forecastCurve !== undefined) {
+        requireCurveInstance(options.forecastCurve, 'priceMultiCurve');
+    }
+    const context = {
+        ...(options.forecastCurve ? { forecastCurve: options.forecastCurve } : {}),
+        ...(options.knownFixingRate !== undefined ? { knownFixingRate: options.knownFixingRate } : {}),
+    };
+    const flows = bond.futureCashflows(options.settlementDate, context);
+    const dfSettle = options.discountCurve.discount(options.settlementDate);
+    let pv = 0;
+    for (const cf of flows) {
+        pv += cf.amount * (options.discountCurve.discount(cf.paymentDate) / dfSettle);
+    }
+    const accruedInterest = bond.accrued(options.settlementDate, context);
+    return {
+        dirtyPrice: pv,
+        cleanPrice: pv - accruedInterest,
+        accruedInterest,
+        assumptions: bondAssumptions(bond, options.settlementDate, 'curve'),
+        diagnostics: { method: 'closed-form', warnings: couponRateWarnings(bond) },
+    };
+}
+function solveYieldToCall(functionName, bond, call, options) {
+    validateClosedRequest(functionName, bond, YIELD_TO_CALL_BOND_SPEC, {
+        argumentName: 'bond',
+        open: true,
+        exampleCall: ANALYTICS_EXAMPLE,
+    });
+    validateClosedRequest(functionName, call, YIELD_TO_CALL_CALL_SPEC, {
+        argumentName: 'call',
+        exampleCall: ANALYTICS_EXAMPLE,
+    });
+    validateClosedRequest(functionName, options, YIELD_TO_CALL_OPTIONS_SPEC, {
+        argumentName: 'options',
+        exampleCall: ANALYTICS_EXAMPLE,
+    });
+    requireBondInstance(bond, functionName);
+    const context = options.context ?? {};
+    const future = bond.futureCashflows(options.settlementDate, context);
+    // Every scheduled flow up to (and including) the call date is received as-is — zeroing pre-call
+    // principal would silently misprice amortizing callables (their principal comes back early).
+    const flows = future
+        .filter((cf) => compareDates(cf.date, call.callDate) <= 0)
+        .map((cf) => ({ ...cf }));
+    let resolvedCallPrice;
+    const callFlow = flows.find((cf) => cf.date === call.callDate);
+    if (callFlow) {
+        // Redemption replaces the scheduled principal at the call date: the issuer repays the WHOLE
+        // balance outstanding over that period (`notional`) — the face value for a bullet bond.
+        const callPrice = call.callPrice ?? callFlow.notional;
+        resolvedCallPrice = callPrice;
+        callFlow.principal = callPrice;
+        callFlow.amount = callFlow.interest + callPrice;
+    }
+    else {
+        // Call between coupon dates: the outstanding balance is the notional accruing over the period
+        // containing the call date — the next scheduled flow's notional.
+        const next = future.find((cf) => compareDates(cf.date, call.callDate) > 0);
+        const callPrice = call.callPrice ?? next?.notional;
+        if (callPrice === undefined) {
+            throw new InputError(`${functionName}: cannot derive the outstanding notional at the call date ${call.callDate} ` +
+                '(no scheduled cash flow on or after it) — pass an explicit call.callPrice.\n' +
+                "  e.g. yieldToCall(bond, { callDate: '2031-01-01', callPrice: 100 }, options)", { code: ErrorCode.InputMissingField, context: { callDate: call.callDate } });
+        }
+        // A mid-period call still pays the coupon ACCRUED since the last coupon date — the issuer
+        // cannot redeem and keep the interest the holder has already earned. Omitting it silently
+        // understated every mid-period YTC (a 6% par bond called a month after a coupon solved to 0%:
+        // pay 100, receive 100, earn nothing). `bond.accrued` is the same partial-period computation
+        // the settlement accrued uses, so the day count and the projected coupon match by construction.
+        resolvedCallPrice = callPrice;
+        const accruedAtCall = bond.accrued(call.callDate, context);
+        flows.push({
+            date: call.callDate,
+            paymentDate: call.callDate,
+            interest: accruedAtCall,
+            principal: callPrice,
+            amount: callPrice + accruedAtCall,
+            notional: next?.notional ?? callPrice,
+        });
+    }
+    if (flows.length === 0) {
+        throw new InputError(`${functionName}: No cash flows up to the call date — cannot solve yield to call.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { callDate: call.callDate },
+        });
+    }
+    const accruedInterest = bond.accrued(options.settlementDate, context);
+    const targetDirty = resolvePriceType(options.priceType) === 'dirty'
+        ? options.price
+        : options.price + accruedInterest;
+    const f = bond.frequency;
+    const objective = (y) => dirtyFromYield(flows, options.settlementDate, y, f, bond.dayCount) - targetDirty;
+    const solved = solveYieldBracketed(objective, f, functionName, {
+        targetPrice: options.price,
+        callDate: call.callDate,
+        settlementDate: options.settlementDate,
+    });
+    return {
+        value: solved.value,
+        iterations: solved.iterations,
+        resolvedCallPrice,
+        accruedInterest,
+        priceType: resolvePriceType(options.priceType),
+    };
+}
+/**
+ * Yield to a call date (H05): the plain call returns the scalar; `.explain()` mirrors
+ * `yieldToMaturity.explain()` — solver facts in diagnostics, the resolved call price and
+ * settlement accrued in the decomposition, and the call/price basis echoed in assumptions.
+ */
+export const yieldToCall = bondFacade('yieldToCall', (bond, call, options) => solveYieldToCall('yieldToCall', bond, call, options).value, ((bond, call, options) => {
+    const solved = solveYieldToCall('yieldToCall.explain', bond, call, options);
+    return {
+        value: solved.value,
+        assumptions: {
+            ...bondAssumptions(bond, options.settlementDate, 'actuarial'),
+            callDate: call.callDate,
+            priceType: solved.priceType,
+        },
+        diagnostics: {
+            method: 'brent',
+            converged: true,
+            iterations: solved.iterations,
+            decomposition: {
+                resolvedCallPrice: solved.resolvedCallPrice,
+                accruedInterest: solved.accruedInterest,
+            },
+            warnings: couponRateWarnings(bond),
+        },
+    };
+}));
+//# sourceMappingURL=bonds.js.map