@insiderfinance/totalfinance 0.1.0

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

@@ -0,0 +1,310 @@
+/**
+ * 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 { requireRepresentableResult, ErrorCode, InputError, compoundFactor, ensureEnum, ensureKnownKeys, requireArgumentObject, requireFiniteFields, } from '../../core/dist/index.js';
+import { requireFiniteComputation } from './internal.js';
+import { requireCurrencyCode, requireCurrencyPairQuote, } from './spot.js';
+// ---------------------------------------------------------------------------------------------------
+// Shared boundary helpers
+// ---------------------------------------------------------------------------------------------------
+/**
+ * The seven-form compounding ladder, taught at this package's boundary. Core owns the
+ * {@link InterestCompounding} vocabulary and the factor arithmetic but exports no validator, and
+ * the FC0 dependency graph forbids the `@insiderfinance/totalfinance/valuation` edge that carries one — so the ladder
+ * is restated here rather than imported.
+ */
+function requireCompoundingWhenPresent(functionName, compounding) {
+    if (compounding === undefined)
+        return;
+    if (compounding === 'simple' ||
+        compounding === 'continuous' ||
+        compounding === 'annual' ||
+        compounding === 'semiannual' ||
+        compounding === 'quarterly' ||
+        compounding === 'monthly')
+        return;
+    if (typeof compounding === 'object' &&
+        compounding !== null &&
+        compounding.type === 'periodic') {
+        const periods = compounding.periodsPerYear;
+        if (typeof periods === 'number' && Number.isFinite(periods) && periods > 0)
+            return;
+        throw new InputError(`${functionName}: compounding.periodsPerYear must be a finite number > 0. Received ${String(periods)}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field: 'compounding' },
+        });
+    }
+    throw new InputError(`${functionName}: compounding must be 'simple' | 'continuous' | 'annual' | 'semiannual' | 'quarterly' | 'monthly' or { type: 'periodic', periodsPerYear } when provided. Received ${compounding === null ? 'null' : JSON.stringify(compounding)}.`, { code: ErrorCode.InputInvalidEnum, context: { function: functionName, field: 'compounding' } });
+}
+/** Both quotes must name the SAME pair in the SAME direction, else a teaching error. */
+function requireSamePair(functionName, firstLabel, firstQuote, secondLabel, secondQuote) {
+    if (firstQuote.baseCurrency !== secondQuote.baseCurrency ||
+        firstQuote.quoteCurrency !== secondQuote.quoteCurrency) {
+        throw new InputError(`${functionName}: ${firstLabel} (${firstQuote.baseCurrency}/${firstQuote.quoteCurrency}) and ${secondLabel} (${secondQuote.baseCurrency}/${secondQuote.quoteCurrency}) must quote the SAME currency pair in the SAME direction. Use invertCurrencyPairQuote to flip one explicitly first.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                function: functionName,
+                [firstLabel]: `${firstQuote.baseCurrency}/${firstQuote.quoteCurrency}`,
+                [secondLabel]: `${secondQuote.baseCurrency}/${secondQuote.quoteCurrency}`,
+            },
+        });
+    }
+}
+const PERSPECTIVES = ['buyer-of-base', 'seller-of-base'];
+/** The forward-value sign convention prose, shared by every valuation result below. */
+const SIGN_CONVENTION = 'buyer-of-base gains when the settlement-relevant rate exceeds the contracted rate: value = ±(rate − contractRate.quotePerBase) × notionalBaseAmount × discountFactorToSettlement, positive sign for buyer-of-base, negative for seller-of-base, in the quote currency';
+/** Validate the shared notional/discount-factor block and return the warning list it seeds. */
+function requireValuationAmounts(functionName, input, exampleCall) {
+    requireFiniteFields(functionName, input, ['notionalBaseAmount', 'discountFactorToSettlement'], {
+        exampleCall,
+        hints: {
+            discountFactorToSettlement: 'an explicit QUOTE-currency discount factor to the settlement date — a factor, not a rate, so conventions cannot mismatch silently',
+        },
+    });
+    if (input.notionalBaseAmount <= 0) {
+        throw new InputError(`${functionName}: notionalBaseAmount must be > 0 — direction is carried by perspective ('buyer-of-base' | 'seller-of-base'), never by a signed notional. Received ${input.notionalBaseAmount}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                function: functionName,
+                field: 'notionalBaseAmount',
+                value: input.notionalBaseAmount,
+            },
+        });
+    }
+    if (input.discountFactorToSettlement <= 0) {
+        throw new InputError(`${functionName}: discountFactorToSettlement must be > 0 (a discount factor, e.g. 0.97). Received ${input.discountFactorToSettlement}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                function: functionName,
+                field: 'discountFactorToSettlement',
+                value: input.discountFactorToSettlement,
+            },
+        });
+    }
+    const warnings = [];
+    if (input.discountFactorToSettlement > 1) {
+        warnings.push(`discountFactorToSettlement ${input.discountFactorToSettlement} exceeds 1 — consistent only with a negative quote-currency rate to settlement; verify the factor.`);
+    }
+    return warnings;
+}
+const COVERED_INTEREST_PARITY_KEYS = [
+    'spotRate',
+    'domesticAnnualRate',
+    'foreignAnnualRate',
+    'timeYears',
+    'compounding',
+];
+const COVERED_INTEREST_PARITY_EXAMPLE = "coveredInterestParityForward({ spotRate: { baseCurrency: 'EUR', quoteCurrency: 'USD', quotePerBase: 1.08 }, domesticAnnualRate: 0.05, foreignAnnualRate: 0.03, timeYears: 0.75, compounding: 'continuous' })";
+/**
+ * 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 function coveredInterestParityForward(input) {
+    requireArgumentObject('coveredInterestParityForward', 'input', input);
+    ensureKnownKeys('coveredInterestParityForward', 'input', input, COVERED_INTEREST_PARITY_KEYS);
+    requireCurrencyPairQuote('coveredInterestParityForward', 'spotRate', input.spotRate);
+    requireFiniteFields('coveredInterestParityForward', input, ['domesticAnnualRate', 'foreignAnnualRate', 'timeYears'], {
+        exampleCall: COVERED_INTEREST_PARITY_EXAMPLE,
+        hints: {
+            domesticAnnualRate: "the QUOTE currency's annual rate (decimal) — USD in EUR/USD",
+            foreignAnnualRate: "the BASE currency's annual rate (decimal) — EUR in EUR/USD",
+        },
+    });
+    if (input.timeYears < 0) {
+        throw new InputError(`coveredInterestParityForward: timeYears must be >= 0. Received ${input.timeYears}.`, {
+            code: ErrorCode.InputNegativeTime,
+            context: {
+                function: 'coveredInterestParityForward',
+                field: 'timeYears',
+                value: input.timeYears,
+            },
+        });
+    }
+    requireCompoundingWhenPresent('coveredInterestParityForward', input.compounding);
+    const compounding = input.compounding === undefined ? 'annual' : input.compounding;
+    const quotePerBase = (input.spotRate.quotePerBase *
+        compoundFactor(input.domesticAnnualRate, input.timeYears, compounding)) /
+        compoundFactor(input.foreignAnnualRate, input.timeYears, compounding);
+    return requireFiniteComputation('coveredInterestParityForward', {
+        forwardRate: {
+            baseCurrency: input.spotRate.baseCurrency,
+            quoteCurrency: input.spotRate.quoteCurrency,
+            quotePerBase,
+        },
+        assumptions: {
+            rateRoles: 'domestic = quote currency, foreign = base currency',
+            compounding,
+            timeYears: input.timeYears,
+        },
+        diagnostics: { warnings: [] },
+    });
+}
+const FORWARD_POINTS_KEYS = ['spotRate', 'forwardRate', 'pointSize'];
+const FORWARD_POINTS_EXAMPLE = "foreignExchangeForwardPoints({ spotRate: { baseCurrency: 'EUR', quoteCurrency: 'USD', quotePerBase: 1.08 }, forwardRate: { baseCurrency: 'EUR', quoteCurrency: 'USD', quotePerBase: 1.0952 }, pointSize: 0.0001 })";
+/**
+ * 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 function foreignExchangeForwardPoints(input) {
+    requireArgumentObject('foreignExchangeForwardPoints', 'input', input);
+    ensureKnownKeys('foreignExchangeForwardPoints', 'input', input, FORWARD_POINTS_KEYS);
+    requireCurrencyPairQuote('foreignExchangeForwardPoints', 'spotRate', input.spotRate);
+    requireCurrencyPairQuote('foreignExchangeForwardPoints', 'forwardRate', input.forwardRate);
+    requireSamePair('foreignExchangeForwardPoints', 'spotRate', input.spotRate, 'forwardRate', input.forwardRate);
+    requireFiniteFields('foreignExchangeForwardPoints', input, ['pointSize'], {
+        exampleCall: FORWARD_POINTS_EXAMPLE,
+        hints: {
+            pointSize: 'quotePerBase units per point — e.g. 0.0001 for EUR/USD; never guessed from symbol spelling',
+        },
+    });
+    if (input.pointSize <= 0) {
+        throw new InputError(`foreignExchangeForwardPoints: pointSize must be > 0 (quotePerBase units per point — e.g. 0.0001 for EUR/USD). Received ${input.pointSize}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                function: 'foreignExchangeForwardPoints',
+                field: 'pointSize',
+                value: input.pointSize,
+            },
+        });
+    }
+    return requireRepresentableResult('foreignExchangeForwardPoints', {
+        forwardPoints: (input.forwardRate.quotePerBase - input.spotRate.quotePerBase) / input.pointSize,
+        assumptions: {
+            pointSize: input.pointSize,
+            pointSizeSource: 'explicit',
+            formula: 'forwardPoints = (forwardRate.quotePerBase − spotRate.quotePerBase) / pointSize',
+        },
+        diagnostics: { warnings: [] },
+    });
+}
+const FORWARD_VALUE_KEYS = [
+    'contractRate',
+    'currentForwardRate',
+    'notionalBaseAmount',
+    'discountFactorToSettlement',
+    'perspective',
+];
+const FORWARD_VALUE_EXAMPLE = "foreignExchangeForwardValue({ contractRate: { baseCurrency: 'EUR', quoteCurrency: 'USD', quotePerBase: 1.08 }, currentForwardRate: { baseCurrency: 'EUR', quoteCurrency: 'USD', quotePerBase: 1.0952 }, notionalBaseAmount: 1_000_000, discountFactorToSettlement: 0.97, perspective: 'buyer-of-base' })";
+/**
+ * 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 function foreignExchangeForwardValue(input) {
+    requireArgumentObject('foreignExchangeForwardValue', 'input', input);
+    ensureKnownKeys('foreignExchangeForwardValue', 'input', input, FORWARD_VALUE_KEYS);
+    requireCurrencyPairQuote('foreignExchangeForwardValue', 'contractRate', input.contractRate);
+    requireCurrencyPairQuote('foreignExchangeForwardValue', 'currentForwardRate', input.currentForwardRate);
+    requireSamePair('foreignExchangeForwardValue', 'contractRate', input.contractRate, 'currentForwardRate', input.currentForwardRate);
+    const warnings = requireValuationAmounts('foreignExchangeForwardValue', input, FORWARD_VALUE_EXAMPLE);
+    ensureEnum(input.perspective, PERSPECTIVES, 'perspective', 'foreignExchangeForwardValue');
+    const sign = input.perspective === 'buyer-of-base' ? 1 : -1;
+    const forwardValueInQuoteCurrency = sign *
+        (input.currentForwardRate.quotePerBase - input.contractRate.quotePerBase) *
+        input.notionalBaseAmount *
+        input.discountFactorToSettlement;
+    return requireFiniteComputation('foreignExchangeForwardValue', {
+        forwardValueInQuoteCurrency,
+        assumptions: {
+            perspective: input.perspective,
+            signConvention: SIGN_CONVENTION,
+            discountFactorSource: 'caller-supplied quote-currency discount factor to the settlement date',
+        },
+        diagnostics: { warnings },
+    });
+}
+/**
+ * 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 function foreignExchangeSwapValue(input) {
+    requireArgumentObject('foreignExchangeSwapValue', 'input', input);
+    ensureKnownKeys('foreignExchangeSwapValue', 'input', input, ['nearLeg', 'farLeg']);
+    requireArgumentObject('foreignExchangeSwapValue', 'nearLeg', input.nearLeg);
+    requireArgumentObject('foreignExchangeSwapValue', 'farLeg', input.farLeg);
+    const nearLeg = foreignExchangeForwardValue(input.nearLeg);
+    const farLeg = foreignExchangeForwardValue(input.farLeg);
+    requireSamePair('foreignExchangeSwapValue', 'nearLeg.contractRate', input.nearLeg.contractRate, 'farLeg.contractRate', input.farLeg.contractRate);
+    const nearLegValue = nearLeg.forwardValueInQuoteCurrency;
+    const farLegValue = farLeg.forwardValueInQuoteCurrency;
+    return requireFiniteComputation('foreignExchangeSwapValue', {
+        swapValueInQuoteCurrency: nearLegValue + farLegValue,
+        nearLegValue,
+        farLegValue,
+        assumptions: {
+            composition: 'swapValueInQuoteCurrency = nearLegValue + farLegValue; each leg valued with foreignExchangeForwardValue under its own perspective and discount factor',
+            nearLegPerspective: input.nearLeg.perspective,
+            farLegPerspective: input.farLeg.perspective,
+            signConvention: SIGN_CONVENTION,
+        },
+        diagnostics: {
+            warnings: [
+                ...nearLeg.diagnostics.warnings.map((message) => `nearLeg: ${message}`),
+                ...farLeg.diagnostics.warnings.map((message) => `farLeg: ${message}`),
+            ],
+        },
+    });
+}
+const NON_DELIVERABLE_FORWARD_KEYS = [
+    'contractRate',
+    'fixingRate',
+    'notionalBaseAmount',
+    'settlementCurrency',
+    'discountFactorToSettlement',
+    'perspective',
+];
+const NON_DELIVERABLE_FORWARD_EXAMPLE = "nonDeliverableForwardValue({ contractRate: { baseCurrency: 'BRL', quoteCurrency: 'USD', quotePerBase: 0.185 }, fixingRate: { baseCurrency: 'BRL', quoteCurrency: 'USD', quotePerBase: 0.19 }, notionalBaseAmount: 1_000_000, settlementCurrency: 'USD', discountFactorToSettlement: 0.98, perspective: 'buyer-of-base' })";
+/**
+ * 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 function nonDeliverableForwardValue(input) {
+    requireArgumentObject('nonDeliverableForwardValue', 'input', input);
+    ensureKnownKeys('nonDeliverableForwardValue', 'input', input, NON_DELIVERABLE_FORWARD_KEYS);
+    requireCurrencyPairQuote('nonDeliverableForwardValue', 'contractRate', input.contractRate);
+    requireCurrencyPairQuote('nonDeliverableForwardValue', 'fixingRate', input.fixingRate);
+    requireSamePair('nonDeliverableForwardValue', 'contractRate', input.contractRate, 'fixingRate', input.fixingRate);
+    requireCurrencyCode('nonDeliverableForwardValue', 'settlementCurrency', input.settlementCurrency);
+    if (input.settlementCurrency !== input.contractRate.quoteCurrency) {
+        throw new InputError(`nonDeliverableForwardValue: v1 settles in the pair's quote currency only — '${input.contractRate.quoteCurrency}' for ${input.contractRate.baseCurrency}/${input.contractRate.quoteCurrency}. Received settlementCurrency '${input.settlementCurrency}'. Convert the settled amount explicitly with convertCurrency if another currency is needed.\n  e.g. ${NON_DELIVERABLE_FORWARD_EXAMPLE}`, {
+            code: ErrorCode.InputOutOfRange,
+            context: {
+                function: 'nonDeliverableForwardValue',
+                field: 'settlementCurrency',
+                value: input.settlementCurrency,
+                required: input.contractRate.quoteCurrency,
+            },
+        });
+    }
+    const warnings = requireValuationAmounts('nonDeliverableForwardValue', input, NON_DELIVERABLE_FORWARD_EXAMPLE);
+    ensureEnum(input.perspective, PERSPECTIVES, 'perspective', 'nonDeliverableForwardValue');
+    const sign = input.perspective === 'buyer-of-base' ? 1 : -1;
+    const nonDeliverableForwardValueInSettlementCurrency = sign *
+        (input.fixingRate.quotePerBase - input.contractRate.quotePerBase) *
+        input.notionalBaseAmount *
+        input.discountFactorToSettlement;
+    return requireFiniteComputation('nonDeliverableForwardValue', {
+        nonDeliverableForwardValueInSettlementCurrency,
+        assumptions: {
+            fixingSource: 'caller-supplied fixing rate',
+            settlementCurrency: input.settlementCurrency,
+            settlementConstraint: "v1 settles in the pair's quote currency only",
+            perspective: input.perspective,
+            signConvention: SIGN_CONVENTION,
+        },
+        diagnostics: { warnings },
+    });
+}
+//# sourceMappingURL=forwards.js.map

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * `@insiderfinance/totalfinance/foreign-exchange` — foreign-exchange foundations (FC5): the currency-pair quote
+ * contract, conversion and cross rates, covered-interest-parity forwards and their valuation, and
+ * currency exposure/hedging. A pair always identifies base and quote currency (`quotePerBase` =
+ * quote units per ONE base unit); inversion is explicit; pip/point sizes are supplied, never
+ * guessed; valuation takes explicit discount factors so conventions cannot mismatch silently.
+ */
+export * from './spot.js';
+export * from './forwards.js';
+export * from './exposure.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

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

@@ -0,0 +1,11 @@
+/**
+ * `@insiderfinance/totalfinance/foreign-exchange` — foreign-exchange foundations (FC5): the currency-pair quote
+ * contract, conversion and cross rates, covered-interest-parity forwards and their valuation, and
+ * currency exposure/hedging. A pair always identifies base and quote currency (`quotePerBase` =
+ * quote units per ONE base unit); inversion is explicit; pip/point sizes are supplied, never
+ * guessed; valuation takes explicit discount factors so conventions cannot mismatch silently.
+ */
+export * from './spot.js';
+export * from './forwards.js';
+export * from './exposure.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

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

@@ -0,0 +1,6 @@
+/**
+ * Law 7's overflow refusal — DELEGATED to core's shared finalizer (2026-08-23 review wave: the
+ * commodity and FX copies were consolidated; one walker, one message, one law).
+ */
+export { requireRepresentableResult as requireFiniteComputation } from '../../core/dist/index.js';
+//# sourceMappingURL=internal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,0BAA0B,IAAI,wBAAwB,EAAE,MAAM,0BAAoB,CAAC"}

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

@@ -0,0 +1,6 @@
+/**
+ * Law 7's overflow refusal — DELEGATED to core's shared finalizer (2026-08-23 review wave: the
+ * commodity and FX copies were consolidated; one walker, one message, one law).
+ */
+export { requireRepresentableResult as requireFiniteComputation } from '../../core/dist/index.js';
+//# sourceMappingURL=internal.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,0BAA0B,IAAI,wBAAwB,EAAE,MAAM,0BAAoB,CAAC"}

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

@@ -0,0 +1,150 @@
+/**
+ * FC5 — spot foreign exchange: the currency-pair quote contract, quote inversion, cross rates
+ * through one common currency, conversion, and pip values. One law above all: a pair always
+ * identifies its base and quote currency, and `quotePerBase` is units of QUOTE currency per ONE
+ * unit of BASE currency. Nothing here guesses a direction, a pip size, or a missing pair — every
+ * inversion is explicit and disclosed in the result's assumptions.
+ */
+/**
+ * One foreign-exchange quote. `quotePerBase` is the price of ONE unit of `baseCurrency` expressed
+ * in `quoteCurrency` — EUR/USD 1.08 is `{ baseCurrency: 'EUR', quoteCurrency: 'USD',
+ * quotePerBase: 1.08 }`: one euro costs 1.08 dollars.
+ */
+export interface CurrencyPairQuote {
+    /** Uppercase three-letter ISO-style code of the currency being priced (ONE unit of this). */
+    baseCurrency: string;
+    /** Uppercase three-letter ISO-style code of the currency the price is expressed in. */
+    quoteCurrency: string;
+    /** Units of quote currency per ONE base unit; must be finite and > 0. */
+    quotePerBase: number;
+}
+/**
+ * Validate one currency-code field at a public boundary: a string matching `/^[A-Z]{3}$/`
+ * (uppercase three-letter ISO-4217 style). A lowercase spelling is answered with the exact
+ * uppercase fix rather than a bare rejection.
+ */
+export declare function requireCurrencyCode(functionName: string, field: string, value: unknown): asserts value is string;
+/**
+ * Validate a {@link CurrencyPairQuote} at a public boundary (Law 12 closed request): known keys,
+ * two DISTINCT uppercase currency codes, and a finite `quotePerBase` > 0. The guard validates its
+ * own `functionName` and `label` first — invoked without them, every error it teaches would blame
+ * "undefined" (see `requireFundamentalPeriod` for the precedent).
+ */
+export declare function requireCurrencyPairQuote(functionName: string, label: string, quote: CurrencyPairQuote): asserts quote is CurrencyPairQuote;
+/** Diagnostics every FC5 analysis result carries (the FC2 result grammar). */
+export interface ForeignExchangeDiagnostics {
+    warnings: string[];
+}
+/** Input for {@link invertCurrencyPairQuote}. */
+export interface InvertCurrencyPairQuoteInput {
+    quote: CurrencyPairQuote;
+}
+/** Result of {@link invertCurrencyPairQuote}. */
+export interface InvertCurrencyPairQuoteResult {
+    /** The flipped pair: base and quote swapped, `quotePerBase` reciprocated. */
+    quote: CurrencyPairQuote;
+    assumptions: {
+        inversion: '1 / quotePerBase';
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * Flip a quote's direction: EUR/USD 1.08 becomes USD/EUR 1/1.08. Inverting twice returns the
+ * original pair (the quote-direction identity, tested at 1e-12).
+ */
+export declare function invertCurrencyPairQuote(input: InvertCurrencyPairQuoteInput): InvertCurrencyPairQuoteResult;
+/** Input for {@link crossRate}. */
+export interface CrossRateInput {
+    firstQuote: CurrencyPairQuote;
+    secondQuote: CurrencyPairQuote;
+    /** Base currency of the derived cross pair — one of the two non-shared currencies. */
+    crossBaseCurrency: string;
+    /** Quote currency of the derived cross pair — the other non-shared currency. */
+    crossQuoteCurrency: string;
+}
+/** Result of {@link crossRate}. */
+export interface CrossRateResult {
+    /** The derived cross pair, oriented as requested. */
+    quote: CurrencyPairQuote;
+    assumptions: {
+        /** The ONE currency the two supplied quotes share — the leg the cross goes through. */
+        throughCurrency: string;
+        /** The exact arithmetic, with each leg's source quote and orientation named. */
+        derivation: string;
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * Derive a cross pair through the ONE currency the two supplied quotes share (EUR/USD × USD/JPY →
+ * EUR/JPY). Every orientation case is handled by explicit inversion, and the derivation prose in
+ * the assumptions shows each leg's price, source quote, and orientation. Quotes sharing zero or
+ * both currencies are rejected with the currencies named — there is no cross to derive.
+ */
+export declare function crossRate(input: CrossRateInput): CrossRateResult;
+/** Input for {@link convertCurrency} — the FC5 canonical first-touch shape. */
+export interface ConvertCurrencyInput {
+    /** Amount of `fromCurrency` to convert (any finite sign — a liability converts like an asset). */
+    amount: number;
+    fromCurrency: string;
+    toCurrency: string;
+    /** A quote connecting the two currencies, in EITHER orientation — inverted internally, disclosed. */
+    spotRate: CurrencyPairQuote;
+}
+/** Result of {@link convertCurrency}. */
+export interface ConvertCurrencyResult {
+    convertedAmount: number;
+    assumptions: {
+        fromCurrency: string;
+        toCurrency: string;
+        /** The caller's quote, echoed verbatim. */
+        quoteUsed: CurrencyPairQuote;
+        /** `'direct'`: multiplied by `quotePerBase`; `'inverted'`: divided by it. */
+        orientation: 'direct' | 'inverted';
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * Convert an amount between two currencies at the supplied spot quote. The quote must connect the
+ * two currencies; when it is oriented the other way the conversion divides instead of multiplies
+ * and the result discloses `orientation: 'inverted'`. Converting there and back with the same
+ * quote returns the original amount (the round-trip identity, tested at 1e-12). A same-currency
+ * conversion with a quote supplied is rejected — the identity conversion needs no quote.
+ */
+export declare function convertCurrency(input: ConvertCurrencyInput): ConvertCurrencyResult;
+/** Input for {@link pipValue}. */
+export interface PipValueInput {
+    quote: CurrencyPairQuote;
+    /**
+     * The size of one pip in quote-currency units per base unit (e.g. `0.0001` for EUR/USD,
+     * `0.01` for USD/JPY). REQUIRED — never guessed from symbol spelling (FC5 law).
+     */
+    pipSize: number;
+    /** Position notional, expressed in `notionalCurrency` units. */
+    notionalAmount: number;
+    /** Which currency the notional is stated in — must be the pair's base or quote currency. */
+    notionalCurrency: string;
+}
+/** Result of {@link pipValue}. */
+export interface PipValueResult {
+    /** Value of a one-pip move in the QUOTE currency. */
+    pipValueInQuoteCurrency: number;
+    /** The same value converted to the base currency at the supplied spot quote. */
+    pipValueInBaseCurrency: number;
+    assumptions: {
+        pipSize: number;
+        pipSizeSource: 'explicit';
+        notionalCurrency: string;
+        /** How the notional was read: already in base units, or converted from quote units at spot. */
+        notionalCurrencyRole: 'base' | 'quote';
+        baseConversion: 'pip value in base currency = pip value in quote currency / quotePerBase (converted at the supplied spot quote)';
+    };
+    diagnostics: ForeignExchangeDiagnostics;
+}
+/**
+ * Value of one pip for a position. A pip moves `quotePerBase` by `pipSize`, so a notional of `N`
+ * BASE units gains/loses `pipSize × N` quote-currency units per pip; a notional stated in the
+ * quote currency is first restated in base units at the supplied spot quote. `pipSize` is always
+ * explicit — a symbol's spelling never decides it.
+ */
+export declare function pipValue(input: PipValueInput): PipValueResult;
+//# sourceMappingURL=spot.d.ts.map

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

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