@insiderfinance/totalfinance 0.1.0

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

@@ -0,0 +1,630 @@
+/**
+ * Bond futures & cheapest-to-deliver analytics (spec: `docs/specs/bond-future-ctd.md`, roadmap Tier 2).
+ * A Treasury future settles against a *basket* of deliverable bonds, each scaled by a published
+ * conversion factor; the short delivers whichever is cheapest. This module computes the CME/CBOT
+ * conversion factor, the gross/net basis, carry, and the (repo-independent) implied repo rate for each
+ * deliverable, and picks the cheapest-to-deliver — composing the existing `Bond` machinery (accrued
+ * interest, cash flows) rather than introducing a new instrument model.
+ */
+import { ensureFiniteWhenPresent, CONVENTIONS_VERSION, ErrorCode, InputError, ensureFinite, ensureKnownKeys, ensurePositive, parseIsoDate, requireArgumentObject, warning, } from '../../core/dist/index.js';
+import { ensureBooleanWhenPresent } from './validate.js';
+import { brent } from '../../math/dist/index.js';
+import { compareDates, yearFraction } from './conventions.js';
+import { priceFromYield, yieldMetrics, yieldToMaturity } from './bonds.js';
+const DEFAULT_NOTIONAL_COUPON = 0.06;
+/** The rounding + factor, shared by `conversionFactor` and `bondFuture`. */
+function computeFactor(couponRate, deliveryDate, maturityDate, notionalCoupon, functionName) {
+    const del = parseIsoDate(deliveryDate);
+    const mat = parseIsoDate(maturityDate);
+    // Time from the FIRST day of the delivery month to maturity, in whole months, floored to a quarter.
+    const months = (mat.year - del.year) * 12 + (mat.month - del.month);
+    if (months <= 0) {
+        throw new InputError(`${functionName}: bond maturing ${maturityDate} does not mature after the delivery month of ${deliveryDate}; it is not deliverable.`, { code: ErrorCode.InputOutOfRange, context: { maturityDate, deliveryDate, months } });
+    }
+    const rounded = months - (months % 3);
+    const n = Math.floor(rounded / 12);
+    const z = rounded - 12 * n; // 0, 3, 6, or 9
+    const semi = notionalCoupon / 2;
+    const base = z < 7 ? Math.pow(1 + semi, -2 * n) : Math.pow(1 + semi, -(2 * n + 1));
+    const v = z < 7 ? z : z - 6;
+    const a = Math.pow(1 + semi, -v / 6);
+    const b = (couponRate / 2) * ((6 - v) / 6);
+    const d = (couponRate / notionalCoupon) * (1 - base);
+    const factor = a * (couponRate / 2 + base + d) - b;
+    return { factor, n, z };
+}
+/**
+ * The CME/CBOT conversion factor for a deliverable bond: the price per $1 face that would make it yield
+ * the contract's notional coupon (default 6%) on the first day of the delivery month, with the time to
+ * maturity rounded down to whole quarters. Assumes semiannual coupons (Treasury/Gilt convention).
+ * See `docs/specs/bond-future-ctd.md`.
+ */
+export function conversionFactor(input) {
+    const functionName = 'conversionFactor';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, ['bond', 'deliveryDate', 'notionalCoupon']);
+    requireArgumentObject(functionName, 'bond', input.bond);
+    if (typeof input.deliveryDate !== 'string') {
+        throw new InputError(`${functionName}: deliveryDate (an ISO date string) is required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'deliveryDate' },
+        });
+    }
+    ensureFiniteWhenPresent(input.notionalCoupon, 'notionalCoupon', functionName);
+    const notionalCoupon = input.notionalCoupon ?? DEFAULT_NOTIONAL_COUPON;
+    ensurePositive(notionalCoupon, 'notionalCoupon', functionName);
+    ensureFinite(input.bond.couponRate, 'bond.couponRate', functionName);
+    const { factor, n, z } = computeFactor(input.bond.couponRate, input.deliveryDate, input.bond.maturityDate, notionalCoupon, functionName);
+    const warnings = [];
+    if (input.bond.frequency !== 2) {
+        warnings.push(warning('fixedIncome.cf_non_semiannual', `${functionName}: the conversion-factor formula assumes semiannual coupons, but the bond pays ${input.bond.frequency}×/year — treat the factor as an approximation.`, 'warn', { frequency: input.bond.frequency }));
+    }
+    return {
+        factor,
+        wholeYears: n,
+        extraMonths: z,
+        notionalCoupon,
+        assumptions: { conventionsVersion: CONVENTIONS_VERSION, couponFrequency: 'semiannual' },
+        diagnostics: {
+            engine: 'bond-future-conversion-factor',
+            method: 'cme whole-quarter',
+            converged: true,
+            warnings,
+        },
+    };
+}
+/** {@link DeliverableBond} keys (Law 12 — mirrors the interface above; keep in sync). */
+const DELIVERABLE_BOND_KEYS = ['bond', 'cleanPrice', 'id', 'conversionFactor'];
+/** {@link BondFutureInput} keys (Law 12 — mirrors the interface above; keep in sync). */
+const BOND_FUTURE_INPUT_KEYS = [
+    'futuresPrice',
+    'settlementDate',
+    'deliveryDate',
+    'repoRate',
+    'notionalCoupon',
+    'deliverables',
+];
+/**
+ * A JSON-safe digest of the deliverable basket, for error contexts.
+ *
+ * An error context is a public payload: it is logged, serialized, and shown to an agent. A `Bond`
+ * is a closure-carrying object, so spreading the raw input into `context` put whole bonds (methods,
+ * the entire schedule) in there — the methods vanish through `JSON.stringify`, leaving a shape that
+ * is simultaneously bloated and uninformative, and no way to tell WHICH bond the error meant. The
+ * identifying facts are the id and the maturity, so those are what travel.
+ */
+function summarizeDeliverables(deliverables) {
+    if (!Array.isArray(deliverables))
+        return [];
+    return deliverables.map((entry, i) => {
+        const row = entry;
+        const maturityDate = row?.bond?.maturityDate;
+        return {
+            id: row?.id ?? String(i),
+            ...(typeof maturityDate === 'string' ? { maturityDate } : {}),
+        };
+    });
+}
+/**
+ * Deliverables carry Bond INSTANCES (from `bonds.fixedRate(...)` et al.) — a raw spec object would
+ * crash on the first `accrued()`/`futureCashflows()` call inside the basis loop; teach the fix at
+ * the boundary instead (the same pattern as `requireBondInstance` in bonds).
+ */
+function requireDeliverableBondInstance(functionName, field, bond) {
+    const b = bond;
+    if (typeof b.accrued !== 'function' || typeof b.futureCashflows !== 'function') {
+        throw new InputError(`${functionName}: ${field} must be 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 } });
+    }
+}
+const money = (x) => x.toFixed(3);
+const pct = (x) => `${(x * 100).toFixed(2)}%`;
+/**
+ * Bond-future basis, carry, implied repo rate, and cheapest-to-deliver across a basket. See
+ * `docs/specs/bond-future-ctd.md`.
+ */
+export function bondFuture(input) {
+    const functionName = 'bondFuture';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, BOND_FUTURE_INPUT_KEYS);
+    ensurePositive(input.futuresPrice, 'futuresPrice', functionName);
+    ensureFinite(input.repoRate, 'repoRate', functionName);
+    if (typeof input.settlementDate !== 'string' || typeof input.deliveryDate !== 'string') {
+        throw new InputError(`${functionName}: settlementDate and deliveryDate (ISO date strings) are required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { settlementDate: input.settlementDate, deliveryDate: input.deliveryDate },
+        });
+    }
+    if (compareDates(input.settlementDate, input.deliveryDate) >= 0) {
+        throw new InputError(`${functionName}: deliveryDate ${input.deliveryDate} must be after settlementDate ${input.settlementDate}.`, {
+            code: ErrorCode.InputNegativeTime,
+            context: {
+                settlementDate: input.settlementDate,
+                deliveryDate: input.deliveryDate,
+                futuresPrice: input.futuresPrice,
+                repoRate: input.repoRate,
+                deliverables: summarizeDeliverables(input.deliverables),
+            },
+        });
+    }
+    if (!Array.isArray(input.deliverables) || input.deliverables.length === 0) {
+        throw new InputError(`${functionName}: at least one deliverable bond is required.`, {
+            code: ErrorCode.InputMissingField,
+            context: { field: 'deliverables' },
+        });
+    }
+    ensureFiniteWhenPresent(input.notionalCoupon, 'notionalCoupon', functionName);
+    const notionalCoupon = input.notionalCoupon ?? DEFAULT_NOTIONAL_COUPON;
+    ensurePositive(notionalCoupon, 'notionalCoupon', functionName);
+    const F = input.futuresPrice;
+    const repo = input.repoRate;
+    const settle = input.settlementDate;
+    const delivery = input.deliveryDate;
+    const tau = yearFraction(settle, delivery, 'ACT/360');
+    let nonSemiannual = false;
+    const rows = input.deliverables.map((d, i) => {
+        requireArgumentObject(functionName, `deliverables[${i}]`, d);
+        ensureKnownKeys(functionName, `deliverables[${i}]`, d, DELIVERABLE_BOND_KEYS);
+        requireArgumentObject(functionName, `deliverables[${i}].bond`, d.bond);
+        requireDeliverableBondInstance(functionName, `deliverables[${i}].bond`, d.bond);
+        ensurePositive(d.cleanPrice, `deliverables[${i}].cleanPrice`, functionName);
+        const bond = d.bond;
+        if (bond.frequency !== 2)
+            nonSemiannual = true;
+        let cf;
+        let source;
+        if (d.conversionFactor !== undefined) {
+            ensurePositive(d.conversionFactor, `deliverables[${i}].conversionFactor`, functionName);
+            cf = d.conversionFactor;
+            source = 'supplied';
+        }
+        else {
+            cf = computeFactor(bond.couponRate, delivery, bond.maturityDate, notionalCoupon, functionName).factor;
+            source = 'computed';
+        }
+        const aiS = bond.accrued(settle);
+        const aiD = bond.accrued(delivery);
+        // Interim coupons paid in (settlement, delivery]: futureCashflows already excludes date <= settle.
+        const interim = bond.futureCashflows(settle).filter((f) => compareDates(f.date, delivery) <= 0);
+        const coupons = interim.reduce((s, f) => s + f.amount, 0);
+        const sumCouponTime = interim.reduce((s, f) => s + f.amount * yearFraction(f.paymentDate, delivery, 'ACT/360'), 0);
+        const purchaseCost = d.cleanPrice + aiS;
+        const invoicePrice = F * cf + aiD;
+        const denom = purchaseCost * tau - sumCouponTime;
+        if (!(denom > 0)) {
+            throw new InputError(`${functionName}: degenerate cash-and-carry for deliverable ${d.id ?? i} (financing base ${denom} ≤ 0); implied repo is undefined.`, { code: ErrorCode.InputOutOfRange, context: { id: d.id ?? i, denom, tau } });
+        }
+        const impliedRepoRate = (invoicePrice + coupons - purchaseCost) / denom;
+        const grossBasis = d.cleanPrice - F * cf;
+        const carry = coupons + aiD - aiS - purchaseCost * repo * tau;
+        const netBasis = grossBasis - carry;
+        return {
+            id: d.id ?? String(i),
+            conversionFactor: cf,
+            conversionFactorSource: source,
+            cleanPrice: d.cleanPrice,
+            accruedAtSettlement: aiS,
+            accruedAtDelivery: aiD,
+            interimCoupons: coupons,
+            purchaseCost,
+            invoicePrice,
+            grossBasis,
+            carry,
+            netBasis,
+            impliedRepoRate,
+            isCheapestToDeliver: false,
+        };
+    });
+    // CTD = the max implied-repo-rate deliverable; sort CTD-first.
+    rows.sort((x, y) => y.impliedRepoRate - x.impliedRepoRate);
+    rows[0].isCheapestToDeliver = true;
+    const ctd = rows[0];
+    const warnings = [];
+    if (nonSemiannual) {
+        warnings.push(warning('fixedIncome.cf_non_semiannual', `${functionName}: one or more deliverables do not pay semiannually; their computed conversion factors are approximate (supply an exchange factor to be exact).`, 'warn'));
+    }
+    const summary = `CTD is ${ctd.id} (implied repo ${pct(ctd.impliedRepoRate)}, net basis ${money(ctd.netBasis)}) ` +
+        `of ${rows.length} deliverable${rows.length === 1 ? '' : 's'}; gross basis ${money(ctd.grossBasis)}, ` +
+        `carry ${money(ctd.carry)} over ${tau.toFixed(3)}y to delivery.`;
+    return {
+        deliverables: rows,
+        cheapestToDeliver: ctd,
+        yearsToDelivery: tau,
+        summary,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            futuresPrice: F,
+            repoRate: repo,
+            notionalCoupon,
+            settlementDate: settle,
+            deliveryDate: delivery,
+        },
+        diagnostics: {
+            engine: 'bond-future',
+            method: 'basis + carry + implied-repo CTD',
+            converged: true,
+            warnings,
+        },
+    };
+}
+/** {@link BondFutureHedgeInput} keys (Law 12 — mirrors the interface above; keep in sync). */
+const BOND_FUTURE_HEDGE_INPUT_KEYS = [...BOND_FUTURE_INPUT_KEYS, 'hedgeDv01'];
+/**
+ * Bond-future DV01 hedge ratio and futures-implied yield. Composes {@link bondFuture} (to find the CTD and
+ * the conversion factors) with the bond yield/DV01 analytics: the futures DV01 is the CTD's DV01 divided by
+ * its conversion factor (Hull), so a `hedgeDv01` of risk is offset by `hedgeDv01 / futuresDv01` contracts —
+ * exactly `CF` to hedge the CTD itself. Also reports the CTD yield implied by the forward clean price
+ * `F·CF`. See `docs/specs/bond-future-hedge.md`.
+ */
+export function bondFutureHedge(input) {
+    const functionName = 'bondFutureHedge';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, BOND_FUTURE_HEDGE_INPUT_KEYS);
+    const { hedgeDv01, ...basketInput } = input;
+    if (hedgeDv01 !== undefined)
+        ensureFinite(hedgeDv01, 'hedgeDv01', functionName);
+    // The CTD, conversion factors, and basis come from bondFuture (one source of truth). The basket
+    // input is the hedge input minus `hedgeDv01` — bondFuture rejects keys it does not own (Law 12).
+    const basket = bondFuture(basketInput);
+    const settle = input.settlementDate;
+    const delivery = input.deliveryDate;
+    const F = input.futuresPrice;
+    // Map each result row back to its input bond (row id = deliverable id ?? basket index).
+    const bondById = new Map();
+    input.deliverables.forEach((d, i) => bondById.set(d.id ?? String(i), d.bond));
+    const deliverables = basket.deliverables.map((row) => {
+        const bond = bondById.get(row.id);
+        const y = yieldToMaturity(bond, { settlementDate: settle, price: row.cleanPrice });
+        const dv01 = yieldMetrics(bond, { settlementDate: settle, yield: y }).dv01;
+        return {
+            id: row.id,
+            conversionFactor: row.conversionFactor,
+            yield: y,
+            dv01,
+            futuresDv01ViaBond: dv01 / row.conversionFactor,
+        };
+    });
+    const ctdRow = basket.cheapestToDeliver;
+    const ctd = deliverables.find((d) => d.id === ctdRow.id);
+    const futuresDv01 = ctd.futuresDv01ViaBond; // = ctdDv01 / CF_ctd
+    const ctdBond = bondById.get(ctdRow.id);
+    // The futures-implied forward yield: the CTD's yield at its forward clean price F·CF, as of delivery.
+    const impliedForwardYield = yieldToMaturity(ctdBond, {
+        settlementDate: delivery,
+        price: F * ctdRow.conversionFactor,
+    });
+    return {
+        ctdId: ctd.id,
+        ctdConversionFactor: ctd.conversionFactor,
+        ctdYield: ctd.yield,
+        ctdDv01: ctd.dv01,
+        futuresDv01,
+        impliedForwardYield,
+        ...(hedgeDv01 !== undefined ? { hedgeRatio: hedgeDv01 / futuresDv01 } : {}),
+        deliverables,
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            futuresPrice: F,
+            settlementDate: settle,
+            deliveryDate: delivery,
+        },
+        diagnostics: {
+            engine: 'bond-future-hedge',
+            method: 'ctd dv01 / CF + implied forward yield',
+            converged: true,
+            warnings: basket.diagnostics.warnings,
+        },
+    };
+}
+/** {@link BondFutureCtdFrontierInput} keys (Law 12 — mirrors the interface above; keep in sync). */
+const BOND_FUTURE_CTD_FRONTIER_INPUT_KEYS = [
+    ...BOND_FUTURE_INPUT_KEYS,
+    'yieldShiftsBp',
+    'futuresPrices',
+    'refineSwitches',
+    'switchLocationToleranceBp',
+];
+/** The internal global-tie tolerance (decimal annualized implied-repo rate) — not a caller knob. */
+const REPO_RATE_TIE_TOLERANCE = 1e-10;
+const DEFAULT_SWITCH_LOCATION_TOL_BP = 0.01;
+/** Build an inclusive `[from, to]` range of shifts stepped by `step`; validates the range shape. */
+function buildShiftRange(range, functionName) {
+    const { from, to, step } = range;
+    ensureFinite(from, 'yieldShiftsBp.from', functionName);
+    ensureFinite(to, 'yieldShiftsBp.to', functionName);
+    ensureFinite(step, 'yieldShiftsBp.step', functionName);
+    if (!(step > 0)) {
+        throw new InputError(`${functionName}: yieldShiftsBp.step must be positive, got ${step}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { step },
+        });
+    }
+    if (!(to > from)) {
+        throw new InputError(`${functionName}: yieldShiftsBp.to (${to}) must be greater than yieldShiftsBp.from (${from}).`, { code: ErrorCode.InputOutOfRange, context: { from, to } });
+    }
+    const n = Math.round((to - from) / step);
+    const out = [];
+    for (let i = 0; i <= n; i++)
+        out.push(from + i * step);
+    return out;
+}
+/** Resolve the shift grid; when a futures path is present, an explicit aligned array is required. */
+function resolveYieldShifts(specification, hasFuturesPath, functionName) {
+    if (specification === undefined) {
+        if (hasFuturesPath) {
+            throw new InputError(`${functionName}: futuresPrices requires an explicit yieldShiftsBp array to align one-for-one with; the default range cannot be aligned to a discrete price path.`, { code: ErrorCode.InputWrongType, context: { field: 'yieldShiftsBp' } });
+        }
+        return {
+            shifts: buildShiftRange({ from: -200, to: 200, step: 25 }, functionName),
+            explicit: false,
+        };
+    }
+    if (Array.isArray(specification)) {
+        const arr = specification;
+        if (arr.length === 0) {
+            throw new InputError(`${functionName}: yieldShiftsBp must contain at least one shift.`, {
+                code: ErrorCode.InputMissingField,
+                context: { field: 'yieldShiftsBp' },
+            });
+        }
+        arr.forEach((v, i) => ensureFinite(v, `yieldShiftsBp[${i}]`, functionName));
+        return { shifts: [...arr], explicit: true };
+    }
+    // Not an array: the range object. (`Array.isArray` cannot narrow the `readonly number[]` branch out
+    // of the union, so name the range shape explicitly after the guard above.)
+    const range = specification;
+    requireArgumentObject(functionName, 'yieldShiftsBp', range);
+    ensureKnownKeys(functionName, 'yieldShiftsBp', range, ['from', 'to', 'step']);
+    if (hasFuturesPath) {
+        throw new InputError(`${functionName}: futuresPrices requires an explicit yieldShiftsBp array; a { from, to, step } range does not pin the alignment of a discrete price path.`, { code: ErrorCode.InputWrongType, context: { field: 'yieldShiftsBp' } });
+    }
+    return { shifts: buildShiftRange(range, functionName), explicit: false };
+}
+/**
+ * The cheapest-to-deliver *frontier*: how the CTD identity and the futures risk move under explicit
+ * parallel-yield (and optional futures-price) scenarios. This is a **switching frontier**, not a
+ * valuation of the short's timing/quality delivery option (which stays deferred). It composes
+ * {@link bondFuture} at every node (one source of basis/carry/implied-repo truth), reprices each
+ * deliverable with {@link priceFromYield}, refines held-constant switch brackets by re-evaluating the
+ * *whole* basket (so a narrow third-deliverable window splits into two honest transitions and no
+ * pairwise root off the global frontier is accepted), and reports the delivery-date futures DV01 from
+ * the CTD's futures-implied forward yield — distinct from the spot cash DV01 / CF. See
+ * `docs/specs/wave6-quant-moats.md` §1 and `docs/specs/bond-future-ctd.md`.
+ */
+export function bondFutureCtdFrontier(input) {
+    const functionName = 'bondFutureCtdFrontier';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, BOND_FUTURE_CTD_FRONTIER_INPUT_KEYS);
+    const hasFuturesPath = input.futuresPrices !== undefined;
+    // refineSwitches defaults true, but a discrete futures path forbids interpolated refinement.
+    let refine;
+    if (hasFuturesPath) {
+        if (input.refineSwitches === true) {
+            throw new InputError(`${functionName}: refineSwitches is invalid with a supplied futuresPrices path — a discrete price path does not define values between nodes, so switches cannot be root-refined without inventing an interpolation.`, { code: ErrorCode.InputOutOfRange, context: { refineSwitches: true } });
+        }
+        refine = false;
+    }
+    else {
+        ensureBooleanWhenPresent(input.refineSwitches, functionName, 'refineSwitches');
+        refine = input.refineSwitches ?? true;
+    }
+    const tolBp = input.switchLocationToleranceBp ?? DEFAULT_SWITCH_LOCATION_TOL_BP;
+    if (input.switchLocationToleranceBp !== undefined) {
+        ensureFinite(input.switchLocationToleranceBp, 'switchLocationToleranceBp', functionName);
+        ensurePositive(input.switchLocationToleranceBp, 'switchLocationToleranceBp', functionName);
+    }
+    const { shifts, explicit } = resolveYieldShifts(input.yieldShiftsBp, hasFuturesPath, functionName);
+    // Pair each shift with its futures price, then order by ascending shift and reject duplicates.
+    let nodes;
+    if (hasFuturesPath) {
+        const prices = input.futuresPrices;
+        if (!explicit) {
+            // Unreachable (resolveYieldShifts throws first), but keeps the invariant explicit for readers.
+            throw new InputError(`${functionName}: futuresPrices requires an explicit yieldShiftsBp array.`, {
+                code: ErrorCode.InputWrongType,
+                context: { field: 'yieldShiftsBp' },
+            });
+        }
+        if (prices.length !== shifts.length) {
+            throw new InputError(`${functionName}: futuresPrices (${prices.length}) must align one-for-one with yieldShiftsBp (${shifts.length}).`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { prices: prices.length, shifts: shifts.length },
+            });
+        }
+        prices.forEach((p, i) => ensurePositive(p, `futuresPrices[${i}]`, functionName));
+        nodes = shifts.map((s, i) => ({ shift: s, futuresPrice: prices[i] }));
+    }
+    else {
+        nodes = shifts.map((s) => ({ shift: s, futuresPrice: input.futuresPrice }));
+    }
+    nodes.sort((a, b) => a.shift - b.shift);
+    for (let i = 1; i < nodes.length; i++) {
+        if (nodes[i].shift === nodes[i - 1].shift) {
+            throw new InputError(`${functionName}: yieldShiftsBp contains a duplicate shift (${nodes[i].shift}).`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { shift: nodes[i].shift },
+            });
+        }
+    }
+    // The current (unshifted) CTD, per-deliverable spot yields, and the spot futures risk all come from
+    // bondFutureHedge — one source of truth. Rebuild the basket with only its keys (the frontier-only
+    // controls would be rejected by bondFuture's Law-12 unknown-key guard).
+    const basketInput = {
+        futuresPrice: input.futuresPrice,
+        settlementDate: input.settlementDate,
+        deliveryDate: input.deliveryDate,
+        repoRate: input.repoRate,
+        ...(input.notionalCoupon !== undefined ? { notionalCoupon: input.notionalCoupon } : {}),
+        deliverables: input.deliverables,
+    };
+    const hedge = bondFutureHedge(basketInput);
+    const settle = input.settlementDate;
+    const delivery = input.deliveryDate;
+    const heldFuturesPrice = input.futuresPrice;
+    // Map each deliverable to its id, bond, and current (spot) yield for shifting.
+    const yieldById = new Map(hedge.deliverables.map((d) => [d.id, d.yield]));
+    const scanBonds = basketInput.deliverables.map((d, i) => {
+        const id = d.id ?? String(i);
+        const baseYield = yieldById.get(id);
+        if (baseYield === undefined) {
+            throw new InputError(`${functionName}: could not resolve a spot yield for deliverable ${id}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { id },
+            });
+        }
+        return { deliverable: d, id, baseYield };
+    });
+    /** Reprice the whole basket at a parallel shift + a futures price, via bondFuture (one truth). */
+    function basketAtShift(shiftBp, futuresPrice) {
+        const deliverables = scanBonds.map(({ deliverable, baseYield }) => ({
+            ...deliverable,
+            cleanPrice: priceFromYield(deliverable.bond, {
+                settlementDate: settle,
+                yield: baseYield + shiftBp / 1e4,
+            }).cleanPrice,
+        }));
+        return bondFuture({
+            futuresPrice,
+            settlementDate: settle,
+            deliveryDate: delivery,
+            repoRate: input.repoRate,
+            ...(input.notionalCoupon !== undefined ? { notionalCoupon: input.notionalCoupon } : {}),
+            deliverables,
+        });
+    }
+    const scenarios = nodes.map(({ shift, futuresPrice }) => {
+        const r = basketAtShift(shift, futuresPrice);
+        const ctd = r.cheapestToDeliver;
+        return {
+            yieldShiftBp: shift,
+            futuresPrice,
+            ctdId: ctd.id,
+            netBasis: ctd.netBasis,
+            impliedRepoRate: ctd.impliedRepoRate,
+            deliverables: r.deliverables,
+        };
+    });
+    const switchWarnings = [];
+    /** The global CTD id and every deliverable's implied repo (held-constant policy) at a shift. */
+    function ctdAt(shiftBp) {
+        const r = basketAtShift(shiftBp, heldFuturesPrice);
+        return {
+            id: r.cheapestToDeliver.id,
+            irr: new Map(r.deliverables.map((d) => [d.id, d.impliedRepoRate])),
+        };
+    }
+    /** Root-refine a narrow adjacent-winner bracket, or fall back to an honest grid midpoint. */
+    function rootRefineOrMidpoint(a, b, ctdA, ctdB) {
+        const irrDiff = (shift) => {
+            const { irr } = ctdAt(shift);
+            return (irr.get(ctdA) ?? NaN) - (irr.get(ctdB) ?? NaN);
+        };
+        const root = brent(irrDiff, a, b, {
+            stepTolerance: 1e-12,
+            residualTolerance: REPO_RATE_TIE_TOLERANCE * 1e-3,
+            maximumIterations: 200,
+        });
+        if (root.converged && Number.isFinite(root.value)) {
+            const { irr } = ctdAt(root.value);
+            const irrA = irr.get(ctdA);
+            const irrB = irr.get(ctdB);
+            if (irrA !== undefined &&
+                irrB !== undefined &&
+                Math.abs(irrA - irrB) <= REPO_RATE_TIE_TOLERANCE) {
+                // No third deliverable may beat the tied pair at the root, or it is not on the global frontier.
+                let maxOther = -Infinity;
+                for (const [id, v] of irr)
+                    if (id !== ctdA && id !== ctdB && v > maxOther)
+                        maxOther = v;
+                if (maxOther - Math.max(irrA, irrB) <= REPO_RATE_TIE_TOLERANCE) {
+                    return {
+                        fromCtd: ctdA,
+                        toCtd: ctdB,
+                        bracketBp: [a, b],
+                        estimatedSwitchBp: root.value,
+                        method: 'root-refined',
+                    };
+                }
+            }
+        }
+        switchWarnings.push(warning('fixedIncome.ctd_switch_unrefined', `${functionName}: the ${ctdA}→${ctdB} switch near [${a}, ${b}]bp could not be root-refined to the repo-rate tie tolerance; reporting the bracket midpoint.`, 'info', { fromCtd: ctdA, toCtd: ctdB, bracketBp: [a, b] }));
+        return {
+            fromCtd: ctdA,
+            toCtd: ctdB,
+            bracketBp: [a, b],
+            estimatedSwitchBp: (a + b) / 2,
+            method: 'grid-midpoint',
+        };
+    }
+    /**
+     * Refine a bracket whose endpoints have different CTDs by re-evaluating the WHOLE basket at each
+     * midpoint: if a third deliverable wins in the middle, split into two transitions (so a narrow
+     * intermediate CTD is never skipped); otherwise narrow to the location tolerance and root-refine.
+     */
+    function refineBracket(a, b, ctdA, ctdB) {
+        if (b - a <= tolBp)
+            return [rootRefineOrMidpoint(a, b, ctdA, ctdB)];
+        const mid = (a + b) / 2;
+        const midId = ctdAt(mid).id;
+        if (midId === ctdA)
+            return refineBracket(mid, b, ctdA, ctdB);
+        if (midId === ctdB)
+            return refineBracket(a, mid, ctdA, ctdB);
+        return [...refineBracket(a, mid, ctdA, midId), ...refineBracket(mid, b, midId, ctdB)];
+    }
+    const switches = [];
+    for (let i = 1; i < scenarios.length; i++) {
+        const lo = scenarios[i - 1];
+        const hi = scenarios[i];
+        if (lo.ctdId === hi.ctdId)
+            continue;
+        if (refine) {
+            switches.push(...refineBracket(lo.yieldShiftBp, hi.yieldShiftBp, lo.ctdId, hi.ctdId));
+        }
+        else {
+            switches.push({
+                fromCtd: lo.ctdId,
+                toCtd: hi.ctdId,
+                bracketBp: [lo.yieldShiftBp, hi.yieldShiftBp],
+                estimatedSwitchBp: (lo.yieldShiftBp + hi.yieldShiftBp) / 2,
+                method: 'grid-midpoint',
+            });
+        }
+    }
+    // Delivery-date futures DV01: the CTD's forward DV01 at the delivery date / CF (distinct from spot).
+    const ctdBond = scanBonds.find((s) => s.id === hedge.ctdId).deliverable.bond;
+    const deliveryDateFuturesDv01 = yieldMetrics(ctdBond, { settlementDate: delivery, yield: hedge.impliedForwardYield }).dv01 /
+        hedge.ctdConversionFactor;
+    return {
+        current: {
+            ctdId: hedge.ctdId,
+            ctdYield: hedge.ctdYield,
+            conversionFactor: hedge.ctdConversionFactor,
+        },
+        scenarios,
+        switches,
+        risk: {
+            spotFuturesDv01: hedge.futuresDv01,
+            deliveryDateFuturesDv01,
+            impliedForwardYield: hedge.impliedForwardYield,
+        },
+        assumptions: {
+            conventionsVersion: CONVENTIONS_VERSION,
+            settlementDate: settle,
+            deliveryDate: delivery,
+            futuresPriceScenario: hasFuturesPath ? 'supplied-path' : 'held-constant',
+            yieldShock: 'parallel',
+            yieldShiftsBp: nodes.map((n) => n.shift),
+            refineSwitches: refine,
+            switchLocationToleranceBp: refine ? tolBp : null,
+            repoRateTieTolerance: REPO_RATE_TIE_TOLERANCE,
+        },
+        diagnostics: {
+            engine: 'bond-future-ctd-frontier',
+            method: 'parallel-shift scan + whole-basket switch refinement + delivery-date DV01',
+            converged: true,
+            warnings: [...hedge.diagnostics.warnings, ...switchWarnings],
+        },
+    };
+}
+//# sourceMappingURL=futures.js.map