@insiderfinance/totalfinance 0.1.0

package/modules/foreign-exchange/dist/exposure.d.ts

@@ -0,0 +1,140 @@
+/**
+ * FC5 — currency exposure and hedging (the `./risk` subpath): aggregate exposure by currency in a
+ * declared base currency, the hedge ratio, and the spot/forward hedged P&L decomposition. The
+ * missing-pair law governs everything here: a position whose currency has no supplied connecting
+ * quote is EXCLUDED with its reason — it is never converted at a guessed rate.
+ */
+import { type CurrencyPairQuote, type ForeignExchangeDiagnostics } from './spot.js';
+/** One position handed to {@link currencyExposure}. */
+export interface CurrencyExposurePosition {
+    /** The caller's identifier for the position — echoed in exclusions so they stay attributable. */
+    positionLabel: string;
+    /** Uppercase three-letter code of the currency the position is denominated in. */
+    currency: string;
+    /** Market value in the position's OWN currency (negative for shorts/liabilities). */
+    marketValueInPositionCurrency: number;
+}
+/** Input for {@link currencyExposure}. */
+export interface CurrencyExposureInput {
+    positions: CurrencyExposurePosition[];
+    /** The reporting currency every value is restated into. */
+    baseCurrency: string;
+    /**
+     * Enough quotes to connect every position currency to the base currency, in either orientation.
+     * A currency with no connecting quote has its positions excluded WITH reason — never guessed.
+     */
+    spotRates: CurrencyPairQuote[];
+}
+/** One aggregated per-currency exposure row. */
+export interface CurrencyExposureRow {
+    currency: string;
+    positionCount: number;
+    /** Sum of position values in the row's own currency. */
+    valueInCurrency: number;
+    /** The same sum restated in the base currency at the supplied quote. */
+    valueInBaseCurrency: number;
+    /** Share of `totalBaseValue`; `null` (with a warning) when the total is exactly zero. */
+    exposureFraction: number | null;
+}
+/** One excluded position, with the reason it could not participate. */
+export interface ExcludedCurrencyExposurePosition {
+    positionLabel: string;
+    reason: string;
+}
+/** How one currency was restated into the base currency. */
+export interface CurrencyExposureQuoteUse {
+    currency: string;
+    /** The caller's quote, echoed verbatim. */
+    quote: CurrencyPairQuote;
+    /** `'direct'`: multiplied by `quotePerBase`; `'inverted'`: divided by it. */
+    orientation: 'direct' | 'inverted';
+}
+/** Result of {@link currencyExposure}. */
+export interface CurrencyExposureResult {
+    /** Sum of every INCLUDED position's value in the base currency. */
+    totalBaseValue: number;
+    /** Per-currency rows in first-appearance order, included currencies only. */
+    byCurrency: CurrencyExposureRow[];
+    excludedPositions: ExcludedCurrencyExposurePosition[];
+    assumptions: {
+        baseCurrency: string;
+        /** The fixed policy prose: a position with no connecting quote is excluded with its reason. */
+        missingPairPolicy: string;
+        /** Which quote restated each non-base currency, and in which orientation. */
+        quotesUsed: CurrencyExposureQuoteUse[];
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * Aggregate positions into per-currency exposure in one declared base currency. Base-currency
+ * positions pass through unconverted; every other currency is restated with
+ * {@link convertCurrency} at the supplied quote in whichever orientation connects it (disclosed in
+ * `assumptions.quotesUsed`). A currency with no connecting quote is excluded position-by-position
+ * WITH the reason, and `exposureFraction` is each included currency's share of `totalBaseValue`.
+ */
+export declare function currencyExposure(input: CurrencyExposureInput): CurrencyExposureResult;
+/** Input for {@link hedgeRatio}. */
+export interface HedgeRatioInput {
+    /** The exposure being hedged, in base-currency units (sign allowed — a short exposure is negative). */
+    exposureBaseAmount: number;
+    /** The hedge's notional, in the same base-currency units. */
+    hedgeNotionalBaseAmount: number;
+}
+/** Result of {@link hedgeRatio}. */
+export interface HedgeRatioResult {
+    /** `hedgeNotionalBaseAmount / exposureBaseAmount`; `null` when the exposure is exactly zero. */
+    hedgeRatio: number | null;
+    /** Present exactly when `hedgeRatio` is null. */
+    hedgeRatioAbsentReason?: string;
+    assumptions: {
+        exposureBaseAmount: number;
+        hedgeNotionalBaseAmount: number;
+        definition: 'hedgeRatio = hedgeNotionalBaseAmount / exposureBaseAmount';
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * The simple hedge ratio: `hedgeNotionalBaseAmount / exposureBaseAmount`, both amounts echoed. A
+ * zero exposure has no ratio — the result is `null` with the reason, never Infinity or NaN.
+ */
+export declare function hedgeRatio(input: HedgeRatioInput): HedgeRatioResult;
+/** Input for {@link spotForwardHedgedProfitAndLoss}. */
+export interface SpotForwardHedgedProfitAndLossInput {
+    /** The spot when the position was opened. */
+    initialSpotRate: CurrencyPairQuote;
+    /** The spot at measurement, SAME pair, SAME direction. */
+    finalSpotRate: CurrencyPairQuote;
+    /** The forward locked when the hedge was placed. REQUIRED whenever `hedgedFraction` > 0. */
+    forwardRateAtHedge?: CurrencyPairQuote;
+    /** Fraction of the notional hedged at the forward, in [0, 1]. */
+    hedgedFraction: number;
+    /** Position size in BASE-currency units; positive = long the base currency, negative flips every sign. */
+    notionalBaseAmount: number;
+}
+/** The exact decomposition prose, frozen so tests and docs can quote it. */
+export declare const HEDGED_PROFIT_AND_LOSS_DECOMPOSITION: "totalProfitAndLossInQuoteCurrency = (1 \u2212 hedgedFraction) \u00D7 (finalSpotRate.quotePerBase \u2212 initialSpotRate.quotePerBase) \u00D7 notionalBaseAmount + hedgedFraction \u00D7 (forwardRateAtHedge.quotePerBase \u2212 initialSpotRate.quotePerBase) \u00D7 notionalBaseAmount, every term in the quote currency";
+/** Result of {@link spotForwardHedgedProfitAndLoss}. */
+export interface SpotForwardHedgedProfitAndLossResult {
+    totalProfitAndLossInQuoteCurrency: number;
+    /** `(1 − hedgedFraction) × (finalSpot − initialSpot) × notional` — the part left floating. */
+    unhedgedComponent: number;
+    /** `hedgedFraction × (forwardRateAtHedge − initialSpot) × notional` — the part locked at the forward. */
+    hedgedComponent: number;
+    assumptions: {
+        decomposition: typeof HEDGED_PROFIT_AND_LOSS_DECOMPOSITION;
+        hedgedFraction: number;
+        /** The fixed direction prose: positive notional is long the base; negative flips every sign. */
+        notionalDirection: string;
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * P&L of a base-currency position that hedged `hedgedFraction` of its notional at a forward. The
+ * decomposition is exact and disclosed: the unhedged part rides the spot move
+ * `(finalSpot − initialSpot)`, the hedged part locked `(forwardRateAtHedge − initialSpot)` the
+ * moment the hedge was placed, and the total is their notional-weighted sum in the QUOTE currency.
+ * `hedgedFraction: 0` is the pure spot P&L; `hedgedFraction: 1` is fully locked at the forward and
+ * indifferent to the final spot. `forwardRateAtHedge` is REQUIRED whenever `hedgedFraction` > 0.
+ */
+export declare function spotForwardHedgedProfitAndLoss(input: SpotForwardHedgedProfitAndLossInput): SpotForwardHedgedProfitAndLossResult;
+//# sourceMappingURL=exposure.d.ts.map

package/modules/foreign-exchange/dist/exposure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exposure.d.ts","sourceRoot":"","sources":["../src/exposure.ts"],"names":[],"mappings":"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"}

package/modules/foreign-exchange/dist/exposure.js

@@ -0,0 +1,253 @@
+/**
+ * FC5 — currency exposure and hedging (the `./risk` subpath): aggregate exposure by currency in a
+ * declared base currency, the hedge ratio, and the spot/forward hedged P&L decomposition. The
+ * missing-pair law governs everything here: a position whose currency has no supplied connecting
+ * quote is EXCLUDED with its reason — it is never converted at a guessed rate.
+ */
+import { requireRepresentableResult, ErrorCode, InputError, ensureKnownKeys, missingFieldError, requireArgumentArray, requireArgumentObject, requireFiniteFields, } from '../../core/dist/index.js';
+import { convertCurrency, requireCurrencyCode, requireCurrencyPairQuote, } from './spot.js';
+const CURRENCY_EXPOSURE_KEYS = ['positions', 'baseCurrency', 'spotRates'];
+const POSITION_KEYS = ['positionLabel', 'currency', 'marketValueInPositionCurrency'];
+const CURRENCY_EXPOSURE_EXAMPLE = "currencyExposure({ positions: [{ positionLabel: 'bund-etf', currency: 'EUR', marketValueInPositionCurrency: 1_000 }], baseCurrency: 'USD', spotRates: [{ baseCurrency: 'EUR', quoteCurrency: 'USD', quotePerBase: 1.08 }] })";
+/**
+ * Aggregate positions into per-currency exposure in one declared base currency. Base-currency
+ * positions pass through unconverted; every other currency is restated with
+ * {@link convertCurrency} at the supplied quote in whichever orientation connects it (disclosed in
+ * `assumptions.quotesUsed`). A currency with no connecting quote is excluded position-by-position
+ * WITH the reason, and `exposureFraction` is each included currency's share of `totalBaseValue`.
+ */
+export function currencyExposure(input) {
+    requireArgumentObject('currencyExposure', 'input', input);
+    ensureKnownKeys('currencyExposure', 'input', input, CURRENCY_EXPOSURE_KEYS);
+    requireArgumentArray('currencyExposure', 'positions', input.positions);
+    requireCurrencyCode('currencyExposure', 'baseCurrency', input.baseCurrency);
+    requireArgumentArray('currencyExposure', 'spotRates', input.spotRates);
+    input.positions.forEach((position, index) => {
+        requireArgumentObject('currencyExposure', `positions[${index}]`, position);
+        ensureKnownKeys('currencyExposure', `positions[${index}]`, position, POSITION_KEYS);
+        if (typeof position.positionLabel !== 'string' || position.positionLabel.length === 0) {
+            throw new InputError(`currencyExposure: positions[${index}].positionLabel must be a non-empty string — exclusions are reported by label, and an unlabelled position could not be attributed. Received ${position.positionLabel === null ? 'null' : position.positionLabel === undefined ? 'undefined' : typeof position.positionLabel === 'string' ? "''" : typeof position.positionLabel}.`, {
+                code: ErrorCode.InputWrongType,
+                context: { function: 'currencyExposure', field: `positions[${index}].positionLabel` },
+            });
+        }
+        requireCurrencyCode('currencyExposure', `positions[${index}].currency`, position.currency);
+        requireFiniteFields('currencyExposure', position, ['marketValueInPositionCurrency'], {
+            exampleCall: CURRENCY_EXPOSURE_EXAMPLE,
+            path: `positions[${index}]`,
+        });
+    });
+    input.spotRates.forEach((quote, index) => {
+        requireCurrencyPairQuote('currencyExposure', `spotRates[${index}]`, quote);
+    });
+    const warnings = [];
+    const excludedPositions = [];
+    const quotesUsed = [];
+    // Group by currency in first-appearance order.
+    const currencyOrder = [];
+    const positionsByCurrency = new Map();
+    for (const position of input.positions) {
+        const group = positionsByCurrency.get(position.currency);
+        if (group === undefined) {
+            currencyOrder.push(position.currency);
+            positionsByCurrency.set(position.currency, [position]);
+        }
+        else {
+            group.push(position);
+        }
+    }
+    const includedRows = [];
+    for (const currency of currencyOrder) {
+        const group = positionsByCurrency.get(currency);
+        const valueInCurrency = group.reduce((sum, position) => sum + position.marketValueInPositionCurrency, 0);
+        if (currency === input.baseCurrency) {
+            includedRows.push({
+                currency,
+                positionCount: group.length,
+                valueInCurrency,
+                valueInBaseCurrency: valueInCurrency,
+            });
+            continue;
+        }
+        const connecting = input.spotRates.filter((quote) => (quote.baseCurrency === currency && quote.quoteCurrency === input.baseCurrency) ||
+            (quote.baseCurrency === input.baseCurrency && quote.quoteCurrency === currency));
+        if (connecting.length === 0) {
+            const reason = `no spot rate supplied connecting ${currency} to base currency ${input.baseCurrency} — the position is excluded, never converted at a guessed rate.`;
+            for (const position of group) {
+                excludedPositions.push({ positionLabel: position.positionLabel, reason });
+            }
+            warnings.push(`${group.length} position${group.length === 1 ? '' : 's'} in ${currency} excluded: ${reason}`);
+            continue;
+        }
+        if (connecting.length > 1) {
+            // Identical duplicates are safe to deduplicate; quotes that DISAGREE are refused — a warning
+            // is not consent, and "first wins" made the result depend on array order (review finding).
+            const distinct = new Map();
+            for (const candidate of connecting) {
+                distinct.set(`${candidate.baseCurrency}/${candidate.quoteCurrency}@${candidate.quotePerBase}`, candidate);
+            }
+            if (distinct.size > 1) {
+                throw new InputError(`currencyExposure: ${connecting.length} supplied quotes connect ${currency} to ${input.baseCurrency} and they disagree (${[...distinct.keys()].join('; ')}) — the conversion would depend on array order. Supply exactly one quote per currency pair (in either orientation), or resolve the conflict before calling.`, {
+                    code: ErrorCode.InputOutOfRange,
+                    context: {
+                        function: 'currencyExposure',
+                        currency,
+                        quotes: [...distinct.keys()],
+                    },
+                });
+            }
+            warnings.push(`${connecting.length} identical quotes connect ${currency} to ${input.baseCurrency} — deduplicated; supply each pair once.`);
+        }
+        const quote = connecting[0];
+        const conversion = convertCurrency({
+            amount: valueInCurrency,
+            fromCurrency: currency,
+            toCurrency: input.baseCurrency,
+            spotRate: quote,
+        });
+        quotesUsed.push({
+            currency,
+            quote: conversion.assumptions.quoteUsed,
+            orientation: conversion.assumptions.orientation,
+        });
+        includedRows.push({
+            currency,
+            positionCount: group.length,
+            valueInCurrency,
+            valueInBaseCurrency: conversion.convertedAmount,
+        });
+    }
+    const totalBaseValue = includedRows.reduce((sum, row) => sum + row.valueInBaseCurrency, 0);
+    if (totalBaseValue === 0 && includedRows.length > 0) {
+        warnings.push('totalBaseValue is exactly 0 (included positions cancel) — exposure fractions are undefined and reported as null.');
+    }
+    const byCurrency = includedRows.map((row) => ({
+        ...row,
+        exposureFraction: totalBaseValue === 0 ? null : row.valueInBaseCurrency / totalBaseValue,
+    }));
+    return requireRepresentableResult('currencyExposure', {
+        totalBaseValue,
+        byCurrency,
+        excludedPositions,
+        assumptions: {
+            baseCurrency: input.baseCurrency,
+            missingPairPolicy: 'a position whose currency has no supplied connecting quote is excluded with its reason — never converted at a guessed rate',
+            quotesUsed,
+        },
+        diagnostics: { warnings },
+    });
+}
+const HEDGE_RATIO_EXAMPLE = 'hedgeRatio({ exposureBaseAmount: 1_000_000, hedgeNotionalBaseAmount: 750_000 })';
+/**
+ * The simple hedge ratio: `hedgeNotionalBaseAmount / exposureBaseAmount`, both amounts echoed. A
+ * zero exposure has no ratio — the result is `null` with the reason, never Infinity or NaN.
+ */
+export function hedgeRatio(input) {
+    requireArgumentObject('hedgeRatio', 'input', input);
+    ensureKnownKeys('hedgeRatio', 'input', input, ['exposureBaseAmount', 'hedgeNotionalBaseAmount']);
+    requireFiniteFields('hedgeRatio', input, ['exposureBaseAmount', 'hedgeNotionalBaseAmount'], {
+        exampleCall: HEDGE_RATIO_EXAMPLE,
+    });
+    const assumptions = {
+        exposureBaseAmount: input.exposureBaseAmount,
+        hedgeNotionalBaseAmount: input.hedgeNotionalBaseAmount,
+        definition: 'hedgeRatio = hedgeNotionalBaseAmount / exposureBaseAmount',
+    };
+    if (input.exposureBaseAmount === 0) {
+        return {
+            hedgeRatio: null,
+            hedgeRatioAbsentReason: 'exposureBaseAmount is 0 — a hedge ratio divides by the exposure, and a zero exposure needs no hedge; any nonzero hedge is unbounded relative to it.',
+            assumptions,
+            diagnostics: { warnings: [] },
+        };
+    }
+    return requireRepresentableResult('hedgeRatio', {
+        hedgeRatio: input.hedgeNotionalBaseAmount / input.exposureBaseAmount,
+        assumptions,
+        diagnostics: { warnings: [] },
+    });
+}
+/** The exact decomposition prose, frozen so tests and docs can quote it. */
+export const HEDGED_PROFIT_AND_LOSS_DECOMPOSITION = 'totalProfitAndLossInQuoteCurrency = (1 − hedgedFraction) × (finalSpotRate.quotePerBase − initialSpotRate.quotePerBase) × notionalBaseAmount + hedgedFraction × (forwardRateAtHedge.quotePerBase − initialSpotRate.quotePerBase) × notionalBaseAmount, every term in the quote currency';
+const HEDGED_PROFIT_AND_LOSS_KEYS = [
+    'initialSpotRate',
+    'finalSpotRate',
+    'forwardRateAtHedge',
+    'hedgedFraction',
+    'notionalBaseAmount',
+];
+const HEDGED_PROFIT_AND_LOSS_EXAMPLE = "spotForwardHedgedProfitAndLoss({ initialSpotRate: { baseCurrency: 'EUR', quoteCurrency: 'USD', quotePerBase: 1.08 }, finalSpotRate: { baseCurrency: 'EUR', quoteCurrency: 'USD', quotePerBase: 1.12 }, forwardRateAtHedge: { baseCurrency: 'EUR', quoteCurrency: 'USD', quotePerBase: 1.095 }, hedgedFraction: 0.5, notionalBaseAmount: 1_000_000 })";
+/**
+ * P&L of a base-currency position that hedged `hedgedFraction` of its notional at a forward. The
+ * decomposition is exact and disclosed: the unhedged part rides the spot move
+ * `(finalSpot − initialSpot)`, the hedged part locked `(forwardRateAtHedge − initialSpot)` the
+ * moment the hedge was placed, and the total is their notional-weighted sum in the QUOTE currency.
+ * `hedgedFraction: 0` is the pure spot P&L; `hedgedFraction: 1` is fully locked at the forward and
+ * indifferent to the final spot. `forwardRateAtHedge` is REQUIRED whenever `hedgedFraction` > 0.
+ */
+export function spotForwardHedgedProfitAndLoss(input) {
+    requireArgumentObject('spotForwardHedgedProfitAndLoss', 'input', input);
+    ensureKnownKeys('spotForwardHedgedProfitAndLoss', 'input', input, HEDGED_PROFIT_AND_LOSS_KEYS);
+    requireCurrencyPairQuote('spotForwardHedgedProfitAndLoss', 'initialSpotRate', input.initialSpotRate);
+    requireCurrencyPairQuote('spotForwardHedgedProfitAndLoss', 'finalSpotRate', input.finalSpotRate);
+    requireSamePairForProfitAndLoss('finalSpotRate', input.finalSpotRate, input.initialSpotRate);
+    requireFiniteFields('spotForwardHedgedProfitAndLoss', input, ['hedgedFraction', 'notionalBaseAmount'], {
+        exampleCall: HEDGED_PROFIT_AND_LOSS_EXAMPLE,
+    });
+    if (input.hedgedFraction < 0 || input.hedgedFraction > 1) {
+        throw new InputError(`spotForwardHedgedProfitAndLoss: hedgedFraction must lie in [0, 1] — it is the fraction of the notional locked at the forward. Received ${input.hedgedFraction}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                function: 'spotForwardHedgedProfitAndLoss',
+                field: 'hedgedFraction',
+                value: input.hedgedFraction,
+            },
+        });
+    }
+    const warnings = [];
+    if (input.forwardRateAtHedge === undefined) {
+        if (input.hedgedFraction > 0) {
+            throw missingFieldError('spotForwardHedgedProfitAndLoss', 'forwardRateAtHedge', HEDGED_PROFIT_AND_LOSS_EXAMPLE, 'required whenever hedgedFraction > 0 — the hedged part locks this rate, and it is never inferred');
+        }
+    }
+    else {
+        requireCurrencyPairQuote('spotForwardHedgedProfitAndLoss', 'forwardRateAtHedge', input.forwardRateAtHedge);
+        requireSamePairForProfitAndLoss('forwardRateAtHedge', input.forwardRateAtHedge, input.initialSpotRate);
+        if (input.hedgedFraction === 0) {
+            warnings.push('forwardRateAtHedge does not affect the result — hedgedFraction is 0, so nothing is locked at it.');
+        }
+    }
+    const spotMove = input.finalSpotRate.quotePerBase - input.initialSpotRate.quotePerBase;
+    const unhedgedComponent = (1 - input.hedgedFraction) * spotMove * input.notionalBaseAmount;
+    const hedgedComponent = input.hedgedFraction === 0 || input.forwardRateAtHedge === undefined
+        ? 0
+        : input.hedgedFraction *
+            (input.forwardRateAtHedge.quotePerBase - input.initialSpotRate.quotePerBase) *
+            input.notionalBaseAmount;
+    return requireRepresentableResult('spotForwardHedgedProfitAndLoss', {
+        totalProfitAndLossInQuoteCurrency: unhedgedComponent + hedgedComponent,
+        unhedgedComponent,
+        hedgedComponent,
+        assumptions: {
+            decomposition: HEDGED_PROFIT_AND_LOSS_DECOMPOSITION,
+            hedgedFraction: input.hedgedFraction,
+            notionalDirection: 'a positive notionalBaseAmount is long the base currency; a negative notional is the short and flips every sign',
+        },
+        diagnostics: { warnings },
+    });
+}
+/** Same-pair check against the initial spot, phrased for this boundary. */
+function requireSamePairForProfitAndLoss(label, quote, initialSpotRate) {
+    if (quote.baseCurrency !== initialSpotRate.baseCurrency ||
+        quote.quoteCurrency !== initialSpotRate.quoteCurrency) {
+        throw new InputError(`spotForwardHedgedProfitAndLoss: ${label} (${quote.baseCurrency}/${quote.quoteCurrency}) and initialSpotRate (${initialSpotRate.baseCurrency}/${initialSpotRate.quoteCurrency}) must quote the SAME currency pair in the SAME direction. Use invertCurrencyPairQuote to flip one explicitly first.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                function: 'spotForwardHedgedProfitAndLoss',
+                [label]: `${quote.baseCurrency}/${quote.quoteCurrency}`,
+                initialSpotRate: `${initialSpotRate.baseCurrency}/${initialSpotRate.quoteCurrency}`,
+            },
+        });
+    }
+}
+//# sourceMappingURL=exposure.js.map

package/modules/foreign-exchange/dist/exposure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exposure.js","sourceRoot":"","sources":["../src/exposure.ts"],"names":[],"mappings":"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"}

package/modules/foreign-exchange/dist/forwards.d.ts

@@ -0,0 +1,159 @@
+/**
+ * FC5 — foreign-exchange forwards: covered interest parity, forward points, forward and swap
+ * valuation, and non-deliverable forwards. Rate roles are FIXED and echoed: the DOMESTIC rate
+ * belongs to the QUOTE currency (the currency the price is expressed in) and the FOREIGN rate to
+ * the BASE currency. Valuation accepts an explicit quote-currency discount factor — never a rate —
+ * so day-count and compounding conventions cannot mismatch silently (the matched-conventions law).
+ */
+import { type InterestCompounding } from '../../core/dist/index.js';
+import { type CurrencyPairQuote, type ForeignExchangeDiagnostics } from './spot.js';
+/** Input for {@link coveredInterestParityForward}. */
+export interface CoveredInterestParityForwardInput {
+    spotRate: CurrencyPairQuote;
+    /** Annual rate (decimal) of the QUOTE currency — the 'domestic' leg (USD in EUR/USD). */
+    domesticAnnualRate: number;
+    /** Annual rate (decimal) of the BASE currency — the 'foreign' leg (EUR in EUR/USD). */
+    foreignAnnualRate: number;
+    timeYears: number;
+    /** Default `'annual'` — the FC1 ordinary-flow convention, echoed in the assumptions. */
+    compounding?: InterestCompounding;
+}
+/** Result of {@link coveredInterestParityForward}. */
+export interface CoveredInterestParityForwardResult {
+    /** The parity forward for the SAME pair as the spot quote. */
+    forwardRate: CurrencyPairQuote;
+    assumptions: {
+        rateRoles: 'domestic = quote currency, foreign = base currency';
+        compounding: InterestCompounding;
+        timeYears: number;
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * The no-arbitrage forward: `forward = spot × growthFactor(domestic) / growthFactor(foreign)`. The
+ * DOMESTIC rate is the QUOTE currency's rate and the FOREIGN rate is the BASE currency's rate —
+ * investing the converted amount at the domestic rate must equal investing one base unit at the
+ * foreign rate and converting at this forward (the covered-interest-parity round trip, tested at
+ * 1e-12). Under continuous compounding this is exactly `spot × e^((domestic − foreign) × t)`.
+ */
+export declare function coveredInterestParityForward(input: CoveredInterestParityForwardInput): CoveredInterestParityForwardResult;
+/** Input for {@link foreignExchangeForwardPoints}. */
+export interface ForeignExchangeForwardPointsInput {
+    spotRate: CurrencyPairQuote;
+    /** The forward for the SAME pair in the SAME direction. */
+    forwardRate: CurrencyPairQuote;
+    /** The size of one point in quotePerBase units (e.g. `0.0001` for EUR/USD). REQUIRED — never guessed. */
+    pointSize: number;
+}
+/** Result of {@link foreignExchangeForwardPoints}. */
+export interface ForeignExchangeForwardPointsResult {
+    forwardPoints: number;
+    assumptions: {
+        pointSize: number;
+        pointSizeSource: 'explicit';
+        formula: 'forwardPoints = (forwardRate.quotePerBase − spotRate.quotePerBase) / pointSize';
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * Forward points: `(forward − spot) / pointSize`. Positive when the base currency trades at a
+ * forward premium. `pointSize` is always explicit — a symbol's spelling never decides it.
+ */
+export declare function foreignExchangeForwardPoints(input: ForeignExchangeForwardPointsInput): ForeignExchangeForwardPointsResult;
+/** Input for {@link foreignExchangeForwardValue} — also one leg of {@link foreignExchangeSwapValue}. */
+export interface ForeignExchangeForwardValueInput {
+    /** The rate contracted at inception, for the pair being valued. */
+    contractRate: CurrencyPairQuote;
+    /** Today's forward to the SAME settlement date, SAME pair, SAME direction. */
+    currentForwardRate: CurrencyPairQuote;
+    /** Contract size in BASE-currency units; direction is carried by `perspective`, so this is > 0. */
+    notionalBaseAmount: number;
+    /**
+     * An explicit discount factor in the QUOTE currency to the settlement date. A factor, not a
+     * rate — the matched-conventions law: accepting a rate here would let day-count and compounding
+     * conventions mismatch silently against the forward's own quotation.
+     */
+    discountFactorToSettlement: number;
+    /** Which side is being valued: the buyer of the base currency, or the seller. */
+    perspective: 'buyer-of-base' | 'seller-of-base';
+}
+/** Result of {@link foreignExchangeForwardValue}. */
+export interface ForeignExchangeForwardValueResult {
+    /** Present value of the position in the QUOTE currency; zero at the contracted fair forward. */
+    forwardValueInQuoteCurrency: number;
+    assumptions: {
+        perspective: 'buyer-of-base' | 'seller-of-base';
+        signConvention: string;
+        discountFactorSource: 'caller-supplied quote-currency discount factor to the settlement date';
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * Mark-to-market of an outstanding forward: `±(currentForward − contract) × notionalBase ×
+ * discountFactorToSettlement`, positive sign for `'buyer-of-base'`, negative for
+ * `'seller-of-base'`, in the QUOTE currency. At `currentForwardRate === contractRate` the value is
+ * exactly zero under unchanged inputs (the FC5 acceptance law).
+ */
+export declare function foreignExchangeForwardValue(input: ForeignExchangeForwardValueInput): ForeignExchangeForwardValueResult;
+/** Input for {@link foreignExchangeSwapValue}: two forward legs on the SAME pair. */
+export interface ForeignExchangeSwapValueInput {
+    nearLeg: ForeignExchangeForwardValueInput;
+    farLeg: ForeignExchangeForwardValueInput;
+}
+/** Result of {@link foreignExchangeSwapValue}. */
+export interface ForeignExchangeSwapValueResult {
+    /** `nearLegValue + farLegValue`, in the pair's QUOTE currency. */
+    swapValueInQuoteCurrency: number;
+    nearLegValue: number;
+    farLegValue: number;
+    assumptions: {
+        composition: 'swapValueInQuoteCurrency = nearLegValue + farLegValue; each leg valued with foreignExchangeForwardValue under its own perspective and discount factor';
+        nearLegPerspective: 'buyer-of-base' | 'seller-of-base';
+        farLegPerspective: 'buyer-of-base' | 'seller-of-base';
+        signConvention: string;
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * Value of a foreign-exchange swap as the sum of its two forward legs, each valued with
+ * {@link foreignExchangeForwardValue} (composed, not copied). Both legs must quote the SAME pair;
+ * a classic swap holds opposite perspectives on the two legs, but that is the caller's economics
+ * and is not enforced — each leg's perspective is echoed.
+ */
+export declare function foreignExchangeSwapValue(input: ForeignExchangeSwapValueInput): ForeignExchangeSwapValueResult;
+/** Input for {@link nonDeliverableForwardValue}. */
+export interface NonDeliverableForwardValueInput {
+    /** The rate contracted at inception. */
+    contractRate: CurrencyPairQuote;
+    /** The OBSERVED fixing for the SAME pair — caller-supplied, never fetched or guessed. */
+    fixingRate: CurrencyPairQuote;
+    /** Contract size in BASE-currency units; direction is carried by `perspective`, so this is > 0. */
+    notionalBaseAmount: number;
+    /** Where cash settles. v1 supports ONLY the pair's quote currency; anything else is rejected. */
+    settlementCurrency: string;
+    /** An explicit discount factor in the settlement (quote) currency to the settlement date. */
+    discountFactorToSettlement: number;
+    perspective: 'buyer-of-base' | 'seller-of-base';
+}
+/** Result of {@link nonDeliverableForwardValue}. */
+export interface NonDeliverableForwardValueResult {
+    /** The discounted cash settlement, in the settlement (= quote) currency. */
+    nonDeliverableForwardValueInSettlementCurrency: number;
+    assumptions: {
+        fixingSource: 'caller-supplied fixing rate';
+        settlementCurrency: string;
+        /** The fixed v1 constraint prose: settlement in the pair's quote currency only. */
+        settlementConstraint: string;
+        perspective: 'buyer-of-base' | 'seller-of-base';
+        signConvention: string;
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * Cash-settled value of a non-deliverable forward at its OBSERVED fixing: `±(fixing − contract) ×
+ * notionalBase × discountFactorToSettlement`, in the settlement currency. The fixing is the
+ * caller's — this function never selects a fixing source. v1 settles only in the pair's quote
+ * currency; other settlement currencies are rejected with the constraint named.
+ */
+export declare function nonDeliverableForwardValue(input: NonDeliverableForwardValueInput): NonDeliverableForwardValueResult;
+//# sourceMappingURL=forwards.d.ts.map

package/modules/foreign-exchange/dist/forwards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwards.d.ts","sourceRoot":"","sources":["../src/forwards.ts"],"names":[],"mappings":"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"}