@insiderfinance/totalfinance 0.1.0

package/modules/commodities/dist/forwards.d.ts

@@ -0,0 +1,274 @@
+/**
+ * FC6 — cost-of-carry forwards and their inverses. Three prices live in this module and the
+ * functions never conflate them:
+ *
+ * - the QUOTED futures/forward price — a market observation the caller supplies;
+ * - the THEORETICAL forward price — what cost of carry says the forward should be
+ *   ({@link commodityForwardPrice});
+ * - the CURRENT CONTRACT VALUE — what an already-struck forward position is worth today
+ *   ({@link commodityForwardValue}).
+ *
+ * Every rate is an ANNUAL decimal and every compounding convention is EXPLICIT — a market
+ * instrument never defaults its convention. Storage cost is a proportional annual rate of the
+ * commodity's value in v1 (not a dollar amount per unit); the field name says so.
+ */
+import { type InterestCompounding } from '../../core/dist/index.js';
+/** Input for {@link commodityForwardPrice} — the FROZEN first-touch field set. */
+export interface CommodityForwardPriceInput {
+    /** Spot price of the commodity, > 0, in the quote currency per unit. */
+    spotPrice: number;
+    /** Time to delivery in years, ≥ 0 (zero prices the forward at spot exactly). */
+    timeToDeliveryYears: number;
+    /** Annual financing (interest) rate, decimal. */
+    annualFinancingRate: number;
+    /**
+     * Annual storage cost as a PROPORTIONAL rate of the commodity's value, decimal — not a dollar
+     * amount per unit (v1 models storage as a continuous proportional drag, like a negative yield).
+     */
+    annualStorageCostRate: number;
+    /** Annual convenience yield, decimal — the benefit of holding the physical commodity. */
+    annualConvenienceYield: number;
+    /** REQUIRED compounding convention — a market instrument never defaults its convention. */
+    compounding: InterestCompounding;
+}
+/**
+ * THEORETICAL cost-of-carry forward price: `spotPrice × G(netCarryRate, timeToDeliveryYears)`
+ * where `netCarryRate = annualFinancingRate + annualStorageCostRate − annualConvenienceYield` and
+ * `G` is the compounding growth factor. For `'continuous'` compounding that is exactly
+ * `spotPrice × e^((f + s − c) × t)`.
+ *
+ * A bare-number primitive (like valuation's `freeCashFlowToFirm`): what carry says the forward
+ * SHOULD be, not a quoted futures price and not a contract value.
+ */
+export declare function commodityForwardPrice(input: CommodityForwardPriceInput): number;
+/** Input for {@link commodityForwardValue}. */
+export interface CommodityForwardValueInput {
+    /** The forward price STRUCK on the existing contract (the delivery price agreed at inception). */
+    contractForwardPrice: number;
+    /**
+     * The CURRENT forward price for the same delivery date — a market quote or a theoretical price
+     * from {@link commodityForwardPrice}; either way, a forward PRICE, not a contract value.
+     */
+    currentForwardPrice: number;
+    /** Number of units underlying the contract, > 0. */
+    quantity: number;
+    /**
+     * EXPLICIT discount factor from the delivery date back to the valuation instant, > 0 — the
+     * matched-conventions law: the factor carries its own curve, day count, and compounding, so this
+     * function never re-derives one from a rate it would have to guess conventions for.
+     */
+    discountFactorToDelivery: number;
+    /** Which side of the contract is being valued. */
+    perspective: 'long' | 'short';
+}
+/** Result of {@link commodityForwardValue}. */
+export interface CommodityForwardValueResult {
+    /** The CURRENT VALUE of the existing contract to the stated side (quote currency). */
+    contractValue: number;
+    assumptions: {
+        perspective: 'long' | 'short';
+        /** The factor as supplied — its conventions belong to the caller's curve. */
+        discountFactorToDelivery: number;
+        /** The fixed valuation prose: ±(current − contract) × quantity × factor, long positive. */
+        valuationConvention: string;
+    };
+    diagnostics: {
+        warnings: string[];
+    };
+}
+/**
+ * CURRENT VALUE of an existing forward contract:
+ * `±(currentForwardPrice − contractForwardPrice) × quantity × discountFactorToDelivery`, positive
+ * for `'long'` and negated for `'short'`.
+ *
+ * The three quantities this module keeps distinct meet here: `contractForwardPrice` is the price
+ * STRUCK on the contract, `currentForwardPrice` is today's forward PRICE (quoted or theoretical),
+ * and the result is the contract's VALUE — zero at inception when struck at the fair forward.
+ */
+export declare function commodityForwardValue(input: CommodityForwardValueInput): CommodityForwardValueResult;
+/** Input for {@link commodityCarry}. */
+export interface CommodityCarryInput {
+    /** Spot price, > 0. */
+    spotPrice: number;
+    /** The observed forward (or futures) price for the delivery date, > 0. */
+    forwardPrice: number;
+    /** Time to delivery in years, > 0 — carry over zero time is undefined, not zero. */
+    timeToDeliveryYears: number;
+    /** REQUIRED compounding convention used to annualize the implied carry. */
+    compounding: InterestCompounding;
+    /** Optional supplied component: annual financing rate, decimal. */
+    annualFinancingRate?: number;
+    /** Optional supplied component: annual proportional storage cost rate, decimal. */
+    annualStorageCostRate?: number;
+    /** Optional supplied component: annual convenience yield, decimal. */
+    annualConvenienceYield?: number;
+}
+/** Result of {@link commodityCarry}. */
+export interface CommodityCarryResult {
+    /**
+     * The annualized total carry implied by the spot/forward pair: the rate `r` with
+     * `spotPrice × G(r, timeToDeliveryYears) = forwardPrice` (for `'continuous'`,
+     * `ln(forwardPrice / spotPrice) / timeToDeliveryYears`).
+     */
+    annualizedCarryRate: number;
+    /** The supplied components, echoed — present when at least one was supplied. */
+    components?: {
+        annualFinancingRate?: number;
+        annualStorageCostRate?: number;
+        annualConvenienceYield?: number;
+    };
+    /**
+     * `annualizedCarryRate − (financing + storage − convenience)` — the cost-of-carry parity law
+     * made visible. Present exactly when all three components were supplied.
+     */
+    impliedResidual?: number;
+    assumptions: {
+        compounding: InterestCompounding;
+        /** The fixed carry definition prose: the rate whose growth factor maps spot to forward. */
+        carryDefinition: string;
+    };
+    diagnostics: {
+        warnings: string[];
+    };
+}
+/**
+ * The annualized TOTAL carry a spot/forward pair implies, by inverting the compounding growth
+ * factor. When all three components (financing, storage, convenience) are supplied, the result
+ * also reports `impliedResidual = annualizedCarryRate − (f + s − c)` and warns when the residual
+ * exceeds 1e-9 — a parity-priced forward has residual zero, and a nonzero residual is the parity
+ * law made visible, never silently absorbed into a component.
+ */
+export declare function commodityCarry(input: CommodityCarryInput): CommodityCarryResult;
+/** Input for {@link impliedConvenienceYield}. */
+export interface ImpliedConvenienceYieldInput {
+    /** Spot price, > 0. */
+    spotPrice: number;
+    /** The observed forward (or futures) price, > 0. */
+    forwardPrice: number;
+    /** Time to delivery in years, > 0. */
+    timeToDeliveryYears: number;
+    /** Annual financing rate, decimal. */
+    annualFinancingRate: number;
+    /** Annual proportional storage cost rate, decimal. */
+    annualStorageCostRate: number;
+    /** REQUIRED compounding convention. */
+    compounding: InterestCompounding;
+}
+/** Result of {@link impliedConvenienceYield}. */
+export interface ImpliedConvenienceYieldResult {
+    /** `annualFinancingRate + annualStorageCostRate − annualizedCarry` — the yield the pair implies. */
+    impliedAnnualConvenienceYield: number;
+    assumptions: {
+        compounding: InterestCompounding;
+        /** The fixed inversion prose: convenience = financing + storage − implied carry. */
+        inversion: string;
+    };
+    diagnostics: {
+        warnings: string[];
+    };
+}
+/**
+ * The convenience yield the spot/forward pair implies, given the other carry components — the
+ * inverse of {@link commodityForwardPrice} solved for `annualConvenienceYield`. The remaining
+ * inputs identify it uniquely: `c = f + s − annualizedCarry`.
+ */
+export declare function impliedConvenienceYield(input: ImpliedConvenienceYieldInput): ImpliedConvenienceYieldResult;
+/** Input for {@link impliedStorageCost}. */
+export interface ImpliedStorageCostInput {
+    /** Spot price, > 0. */
+    spotPrice: number;
+    /** The observed forward (or futures) price, > 0. */
+    forwardPrice: number;
+    /** Time to delivery in years, > 0. */
+    timeToDeliveryYears: number;
+    /** Annual financing rate, decimal. */
+    annualFinancingRate: number;
+    /** Annual convenience yield, decimal. */
+    annualConvenienceYield: number;
+    /** REQUIRED compounding convention. */
+    compounding: InterestCompounding;
+}
+/** Result of {@link impliedStorageCost}. */
+export interface ImpliedStorageCostResult {
+    /** `annualizedCarry − annualFinancingRate + annualConvenienceYield` — the rate the pair implies. */
+    impliedAnnualStorageCostRate: number;
+    assumptions: {
+        compounding: InterestCompounding;
+        /** The fixed inversion prose: storage = implied carry − financing + convenience. */
+        inversion: string;
+    };
+    diagnostics: {
+        warnings: string[];
+    };
+}
+/**
+ * The proportional storage cost rate the spot/forward pair implies, given the other carry
+ * components — the spec's "when the remaining inputs identify it uniquely", which these do:
+ * `s = annualizedCarry − f + c`.
+ */
+export declare function impliedStorageCost(input: ImpliedStorageCostInput): ImpliedStorageCostResult;
+/** Input for {@link futuresHedgeRatio}. */
+export interface FuturesHedgeRatioInput {
+    /** The exposure being hedged, in commodity units (sign carries the direction). */
+    exposureQuantity: number;
+    /** Units of the commodity per futures contract, > 0. */
+    futuresContractSize: number;
+    /**
+     * The minimum-variance hedge ratio (a regression beta or hedge effectiveness), default 1 — a
+     * one-to-one hedge, echoed as such in the assumptions.
+     */
+    betaOrHedgeEffectiveness?: number;
+}
+/** Result of {@link futuresHedgeRatio}. */
+export interface FuturesHedgeRatioResult {
+    /**
+     * `exposureQuantity × betaOrHedgeEffectiveness / futuresContractSize` — a REAL number, not
+     * rounded: rounding to whole contracts is the caller's execution decision, disclosed in the
+     * assumptions rather than taken silently.
+     */
+    contractsRequired: number;
+    assumptions: {
+        betaOrHedgeEffectiveness: number;
+        hedgeRatioBasis: 'one-to-one' | 'caller-supplied beta or hedge effectiveness';
+        /** The fixed rounding prose: the count is real-valued; rounding is the caller's decision. */
+        rounding: string;
+    };
+    diagnostics: {
+        warnings: string[];
+    };
+}
+/**
+ * Futures contracts required to hedge an exposure:
+ * `exposureQuantity × betaOrHedgeEffectiveness / futuresContractSize`. The count is NOT rounded —
+ * whether to round up, down, or trade the fraction via a mini contract is an execution decision
+ * that belongs to the caller, and the assumptions say so.
+ */
+export declare function futuresHedgeRatio(input: FuturesHedgeRatioInput): FuturesHedgeRatioResult;
+/** Input for {@link commodityBasis}. */
+export interface CommodityBasisInput {
+    /** Spot price, > 0. */
+    spotPrice: number;
+    /** The quoted futures price, > 0. */
+    futuresPrice: number;
+}
+/** Result of {@link commodityBasis}. */
+export interface CommodityBasisResult {
+    /** `spotPrice − futuresPrice` — the basis in price units. */
+    basis: number;
+    /** `spotPrice / futuresPrice − 1` — the basis as a fraction of the futures price. */
+    basisFraction: number;
+    assumptions: {
+        /** The fixed basis definition prose: price difference and fraction, both named. */
+        definition: string;
+    };
+    diagnostics: {
+        warnings: string[];
+    };
+}
+/**
+ * The basis between spot and a quoted futures price. `basis` (a price difference) and
+ * `basisFraction` (a dimensionless ratio) are DIFFERENT quantities and both deserve names — the
+ * library's naming law already blesses exactly this pair.
+ */
+export declare function commodityBasis(input: CommodityBasisInput): CommodityBasisResult;
+//# sourceMappingURL=forwards.d.ts.map

package/modules/commodities/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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"}

package/modules/commodities/dist/forwards.js

@@ -0,0 +1,359 @@
+/**
+ * FC6 — cost-of-carry forwards and their inverses. Three prices live in this module and the
+ * functions never conflate them:
+ *
+ * - the QUOTED futures/forward price — a market observation the caller supplies;
+ * - the THEORETICAL forward price — what cost of carry says the forward should be
+ *   ({@link commodityForwardPrice});
+ * - the CURRENT CONTRACT VALUE — what an already-struck forward position is worth today
+ *   ({@link commodityForwardValue}).
+ *
+ * Every rate is an ANNUAL decimal and every compounding convention is EXPLICIT — a market
+ * instrument never defaults its convention. Storage cost is a proportional annual rate of the
+ * commodity's value in v1 (not a dollar amount per unit); the field name says so.
+ */
+import { requireFiniteComputation } from './internal.js';
+import { requireRepresentableResult, ErrorCode, InputError, compoundFactor, compoundingPeriodsPerYear, ensureKnownKeys, requireArgumentObject, requireFiniteFields, } from '../../core/dist/index.js';
+// ---------------------------------------------------------------------------------------------------
+// Shared validation
+// ---------------------------------------------------------------------------------------------------
+/**
+ * The REQUIRED-compounding ladder. Valuation's `requireCompoundingWhenPresent` lets `undefined`
+ * through because its callers document a default; a commodity forward has no default convention,
+ * so absence is a missing field here, taught with the frozen first-touch call.
+ */
+function requireInterestCompounding(functionName, compounding, exampleCall) {
+    if (compounding === undefined) {
+        throw new InputError(`${functionName}: compounding is required — a market instrument never defaults its convention.\n  e.g. ${exampleCall}`, {
+            code: ErrorCode.InputMissingField,
+            context: { function: functionName, field: 'compounding' },
+        });
+    }
+    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 }. Received ${compounding === null ? 'null' : typeof compounding === 'number' ? `the retired bare number ${compounding} — pass { type: 'periodic', periodsPerYear: ${compounding} }` : JSON.stringify(compounding)}.`, { code: ErrorCode.InputInvalidEnum, context: { function: functionName, field: 'compounding' } });
+}
+function requirePositive(functionName, field, value, why) {
+    if (value <= 0) {
+        throw new InputError(`${functionName}: ${field} must be > 0 — ${why} Received ${value}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field },
+        });
+    }
+}
+function requireNonNegative(functionName, field, value, why) {
+    if (value < 0) {
+        throw new InputError(`${functionName}: ${field} must be ≥ 0 — ${why} Received ${value}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { function: functionName, field },
+        });
+    }
+}
+/**
+ * Invert the compounding growth factor: the annual rate `r` with
+ * `G(r, years) = growthFactor` under the stated convention. The exact inverse of core's
+ * `compoundFactor`, form by form:
+ *
+ * - continuous: `r = ln(G) / years`
+ * - simple: `r = (G − 1) / years`
+ * - periodic with `m` periods per year: `r = m × (G^(1/(m·years)) − 1)`
+ */
+function annualRateFromGrowthFactor(growthFactor, years, compounding) {
+    const periods = compoundingPeriodsPerYear(compounding);
+    if (periods === null) {
+        return compounding === 'simple' ? (growthFactor - 1) / years : Math.log(growthFactor) / years;
+    }
+    return periods * (Math.pow(growthFactor, 1 / (periods * years)) - 1);
+}
+const COMMODITY_FORWARD_PRICE_EXAMPLE = "commodityForwardPrice({ spotPrice: 72, timeToDeliveryYears: 0.5, annualFinancingRate: 0.05, annualStorageCostRate: 0.02, annualConvenienceYield: 0.01, compounding: 'continuous' })";
+/**
+ * THEORETICAL cost-of-carry forward price: `spotPrice × G(netCarryRate, timeToDeliveryYears)`
+ * where `netCarryRate = annualFinancingRate + annualStorageCostRate − annualConvenienceYield` and
+ * `G` is the compounding growth factor. For `'continuous'` compounding that is exactly
+ * `spotPrice × e^((f + s − c) × t)`.
+ *
+ * A bare-number primitive (like valuation's `freeCashFlowToFirm`): what carry says the forward
+ * SHOULD be, not a quoted futures price and not a contract value.
+ */
+export function commodityForwardPrice(input) {
+    requireArgumentObject('commodityForwardPrice', 'input', input);
+    ensureKnownKeys('commodityForwardPrice', 'input', input, [
+        'spotPrice',
+        'timeToDeliveryYears',
+        'annualFinancingRate',
+        'annualStorageCostRate',
+        'annualConvenienceYield',
+        'compounding',
+    ]);
+    requireFiniteFields('commodityForwardPrice', input, [
+        'spotPrice',
+        'timeToDeliveryYears',
+        'annualFinancingRate',
+        'annualStorageCostRate',
+        'annualConvenienceYield',
+    ], { exampleCall: COMMODITY_FORWARD_PRICE_EXAMPLE });
+    requirePositive('commodityForwardPrice', 'spotPrice', input.spotPrice, 'a non-positive spot has no cost-of-carry forward.');
+    requireNonNegative('commodityForwardPrice', 'timeToDeliveryYears', input.timeToDeliveryYears, 'delivery cannot precede the valuation instant.');
+    requireInterestCompounding('commodityForwardPrice', input.compounding, COMMODITY_FORWARD_PRICE_EXAMPLE);
+    const netCarryRate = input.annualFinancingRate + input.annualStorageCostRate - input.annualConvenienceYield;
+    return requireFiniteComputation('commodityForwardPrice', input.spotPrice * compoundFactor(netCarryRate, input.timeToDeliveryYears, input.compounding));
+}
+/**
+ * CURRENT VALUE of an existing forward contract:
+ * `±(currentForwardPrice − contractForwardPrice) × quantity × discountFactorToDelivery`, positive
+ * for `'long'` and negated for `'short'`.
+ *
+ * The three quantities this module keeps distinct meet here: `contractForwardPrice` is the price
+ * STRUCK on the contract, `currentForwardPrice` is today's forward PRICE (quoted or theoretical),
+ * and the result is the contract's VALUE — zero at inception when struck at the fair forward.
+ */
+export function commodityForwardValue(input) {
+    requireArgumentObject('commodityForwardValue', 'input', input);
+    ensureKnownKeys('commodityForwardValue', 'input', input, [
+        'contractForwardPrice',
+        'currentForwardPrice',
+        'quantity',
+        'discountFactorToDelivery',
+        'perspective',
+    ]);
+    requireFiniteFields('commodityForwardValue', input, ['contractForwardPrice', 'currentForwardPrice', 'quantity', 'discountFactorToDelivery'], {
+        exampleCall: "commodityForwardValue({ contractForwardPrice: 70, currentForwardPrice: 74, quantity: 1000, discountFactorToDelivery: 0.98, perspective: 'long' })",
+    });
+    requirePositive('commodityForwardValue', 'quantity', input.quantity, 'value a short position with perspective, not a negative quantity.');
+    requirePositive('commodityForwardValue', 'discountFactorToDelivery', input.discountFactorToDelivery, 'a discount factor is a positive price of future money.');
+    if (input.perspective !== 'long' && input.perspective !== 'short') {
+        const received = input.perspective;
+        throw new InputError(`commodityForwardValue: perspective must be 'long' | 'short'. Received ${received === null ? 'null' : JSON.stringify(received)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'perspective' } });
+    }
+    const sign = input.perspective === 'long' ? 1 : -1;
+    return requireRepresentableResult('commodityForwardValue', {
+        contractValue: sign *
+            (input.currentForwardPrice - input.contractForwardPrice) *
+            input.quantity *
+            input.discountFactorToDelivery,
+        assumptions: {
+            perspective: input.perspective,
+            discountFactorToDelivery: input.discountFactorToDelivery,
+            valuationConvention: 'contractValue = ±(currentForwardPrice − contractForwardPrice) × quantity × discountFactorToDelivery; positive sign for the long side',
+        },
+        diagnostics: { warnings: [] },
+    });
+}
+const COMMODITY_CARRY_EXAMPLE = "commodityCarry({ spotPrice: 72, forwardPrice: 74.19, timeToDeliveryYears: 0.5, compounding: 'continuous', annualFinancingRate: 0.05, annualStorageCostRate: 0.02, annualConvenienceYield: 0.01 })";
+/**
+ * The annualized TOTAL carry a spot/forward pair implies, by inverting the compounding growth
+ * factor. When all three components (financing, storage, convenience) are supplied, the result
+ * also reports `impliedResidual = annualizedCarryRate − (f + s − c)` and warns when the residual
+ * exceeds 1e-9 — a parity-priced forward has residual zero, and a nonzero residual is the parity
+ * law made visible, never silently absorbed into a component.
+ */
+export function commodityCarry(input) {
+    requireArgumentObject('commodityCarry', 'input', input);
+    ensureKnownKeys('commodityCarry', 'input', input, [
+        'spotPrice',
+        'forwardPrice',
+        'timeToDeliveryYears',
+        'compounding',
+        'annualFinancingRate',
+        'annualStorageCostRate',
+        'annualConvenienceYield',
+    ]);
+    requireFiniteFields('commodityCarry', input, ['spotPrice', 'forwardPrice', 'timeToDeliveryYears'], { exampleCall: COMMODITY_CARRY_EXAMPLE });
+    requirePositive('commodityCarry', 'spotPrice', input.spotPrice, 'carry needs a positive spot.');
+    requirePositive('commodityCarry', 'forwardPrice', input.forwardPrice, 'carry needs a positive forward.');
+    requirePositive('commodityCarry', 'timeToDeliveryYears', input.timeToDeliveryYears, 'carry over zero time is undefined, not zero.');
+    requireInterestCompounding('commodityCarry', input.compounding, COMMODITY_CARRY_EXAMPLE);
+    const componentFields = [
+        'annualFinancingRate',
+        'annualStorageCostRate',
+        'annualConvenienceYield',
+    ];
+    for (const field of componentFields) {
+        const value = input[field];
+        if (value !== undefined && (typeof value !== 'number' || !Number.isFinite(value))) {
+            throw new InputError(`commodityCarry: ${field} must be a finite decimal when provided. Received ${value === null ? 'null' : String(value)}.`, { code: ErrorCode.InputWrongType, context: { field } });
+        }
+    }
+    const annualizedCarryRate = annualRateFromGrowthFactor(input.forwardPrice / input.spotPrice, input.timeToDeliveryYears, input.compounding);
+    const suppliedCount = componentFields.filter((field) => input[field] !== undefined).length;
+    const warnings = [];
+    const result = {
+        annualizedCarryRate,
+        assumptions: {
+            compounding: input.compounding,
+            carryDefinition: 'annualizedCarryRate solves spotPrice × G(rate, timeToDeliveryYears) = forwardPrice under the stated compounding; positive carry means the forward stands above spot',
+        },
+        diagnostics: { warnings },
+    };
+    if (suppliedCount > 0) {
+        result.components = {
+            ...(input.annualFinancingRate !== undefined
+                ? { annualFinancingRate: input.annualFinancingRate }
+                : {}),
+            ...(input.annualStorageCostRate !== undefined
+                ? { annualStorageCostRate: input.annualStorageCostRate }
+                : {}),
+            ...(input.annualConvenienceYield !== undefined
+                ? { annualConvenienceYield: input.annualConvenienceYield }
+                : {}),
+        };
+    }
+    if (suppliedCount === 3) {
+        const impliedResidual = annualizedCarryRate -
+            (input.annualFinancingRate + input.annualStorageCostRate - input.annualConvenienceYield);
+        result.impliedResidual = impliedResidual;
+        if (Math.abs(impliedResidual) > 1e-9) {
+            warnings.push(`impliedResidual ${impliedResidual} exceeds 1e-9 — the observed forward is not parity-priced by the supplied financing/storage/convenience components (cost-of-carry parity made visible).`);
+        }
+    }
+    else if (suppliedCount > 0) {
+        warnings.push('impliedResidual is absent: the carry decomposition needs all three of annualFinancingRate, annualStorageCostRate, and annualConvenienceYield — a residual against a partial component set would silently blame the missing component.');
+    }
+    return requireRepresentableResult('commodityCarry', result);
+}
+const IMPLIED_CONVENIENCE_YIELD_EXAMPLE = "impliedConvenienceYield({ spotPrice: 72, forwardPrice: 74.19, timeToDeliveryYears: 0.5, annualFinancingRate: 0.05, annualStorageCostRate: 0.02, compounding: 'continuous' })";
+/**
+ * The convenience yield the spot/forward pair implies, given the other carry components — the
+ * inverse of {@link commodityForwardPrice} solved for `annualConvenienceYield`. The remaining
+ * inputs identify it uniquely: `c = f + s − annualizedCarry`.
+ */
+export function impliedConvenienceYield(input) {
+    requireArgumentObject('impliedConvenienceYield', 'input', input);
+    ensureKnownKeys('impliedConvenienceYield', 'input', input, [
+        'spotPrice',
+        'forwardPrice',
+        'timeToDeliveryYears',
+        'annualFinancingRate',
+        'annualStorageCostRate',
+        'compounding',
+    ]);
+    requireFiniteFields('impliedConvenienceYield', input, [
+        'spotPrice',
+        'forwardPrice',
+        'timeToDeliveryYears',
+        'annualFinancingRate',
+        'annualStorageCostRate',
+    ], { exampleCall: IMPLIED_CONVENIENCE_YIELD_EXAMPLE });
+    requirePositive('impliedConvenienceYield', 'spotPrice', input.spotPrice, 'the inversion needs a positive spot.');
+    requirePositive('impliedConvenienceYield', 'forwardPrice', input.forwardPrice, 'the inversion needs a positive forward.');
+    requirePositive('impliedConvenienceYield', 'timeToDeliveryYears', input.timeToDeliveryYears, 'carry over zero time is undefined, not zero.');
+    requireInterestCompounding('impliedConvenienceYield', input.compounding, IMPLIED_CONVENIENCE_YIELD_EXAMPLE);
+    const annualizedCarry = annualRateFromGrowthFactor(input.forwardPrice / input.spotPrice, input.timeToDeliveryYears, input.compounding);
+    return requireRepresentableResult('impliedConvenienceYield', {
+        impliedAnnualConvenienceYield: input.annualFinancingRate + input.annualStorageCostRate - annualizedCarry,
+        assumptions: {
+            compounding: input.compounding,
+            inversion: 'impliedAnnualConvenienceYield = annualFinancingRate + annualStorageCostRate − annualizedCarry, where annualizedCarry inverts spotPrice × G(rate, timeToDeliveryYears) = forwardPrice',
+        },
+        diagnostics: { warnings: [] },
+    });
+}
+const IMPLIED_STORAGE_COST_EXAMPLE = "impliedStorageCost({ spotPrice: 72, forwardPrice: 74.19, timeToDeliveryYears: 0.5, annualFinancingRate: 0.05, annualConvenienceYield: 0.01, compounding: 'continuous' })";
+/**
+ * The proportional storage cost rate the spot/forward pair implies, given the other carry
+ * components — the spec's "when the remaining inputs identify it uniquely", which these do:
+ * `s = annualizedCarry − f + c`.
+ */
+export function impliedStorageCost(input) {
+    requireArgumentObject('impliedStorageCost', 'input', input);
+    ensureKnownKeys('impliedStorageCost', 'input', input, [
+        'spotPrice',
+        'forwardPrice',
+        'timeToDeliveryYears',
+        'annualFinancingRate',
+        'annualConvenienceYield',
+        'compounding',
+    ]);
+    requireFiniteFields('impliedStorageCost', input, [
+        'spotPrice',
+        'forwardPrice',
+        'timeToDeliveryYears',
+        'annualFinancingRate',
+        'annualConvenienceYield',
+    ], { exampleCall: IMPLIED_STORAGE_COST_EXAMPLE });
+    requirePositive('impliedStorageCost', 'spotPrice', input.spotPrice, 'the inversion needs a positive spot.');
+    requirePositive('impliedStorageCost', 'forwardPrice', input.forwardPrice, 'the inversion needs a positive forward.');
+    requirePositive('impliedStorageCost', 'timeToDeliveryYears', input.timeToDeliveryYears, 'carry over zero time is undefined, not zero.');
+    requireInterestCompounding('impliedStorageCost', input.compounding, IMPLIED_STORAGE_COST_EXAMPLE);
+    const annualizedCarry = annualRateFromGrowthFactor(input.forwardPrice / input.spotPrice, input.timeToDeliveryYears, input.compounding);
+    return requireRepresentableResult('impliedStorageCost', {
+        impliedAnnualStorageCostRate: annualizedCarry - input.annualFinancingRate + input.annualConvenienceYield,
+        assumptions: {
+            compounding: input.compounding,
+            inversion: 'impliedAnnualStorageCostRate = annualizedCarry − annualFinancingRate + annualConvenienceYield, where annualizedCarry inverts spotPrice × G(rate, timeToDeliveryYears) = forwardPrice',
+        },
+        diagnostics: { warnings: [] },
+    });
+}
+/**
+ * Futures contracts required to hedge an exposure:
+ * `exposureQuantity × betaOrHedgeEffectiveness / futuresContractSize`. The count is NOT rounded —
+ * whether to round up, down, or trade the fraction via a mini contract is an execution decision
+ * that belongs to the caller, and the assumptions say so.
+ */
+export function futuresHedgeRatio(input) {
+    requireArgumentObject('futuresHedgeRatio', 'input', input);
+    ensureKnownKeys('futuresHedgeRatio', 'input', input, [
+        'exposureQuantity',
+        'futuresContractSize',
+        'betaOrHedgeEffectiveness',
+    ]);
+    requireFiniteFields('futuresHedgeRatio', input, ['exposureQuantity', 'futuresContractSize'], {
+        exampleCall: 'futuresHedgeRatio({ exposureQuantity: 25_000, futuresContractSize: 1_000, betaOrHedgeEffectiveness: 0.92 })',
+    });
+    requirePositive('futuresHedgeRatio', 'futuresContractSize', input.futuresContractSize, 'a contract covers a positive quantity.');
+    if (input.betaOrHedgeEffectiveness !== undefined &&
+        (typeof input.betaOrHedgeEffectiveness !== 'number' ||
+            !Number.isFinite(input.betaOrHedgeEffectiveness))) {
+        throw new InputError(`futuresHedgeRatio: betaOrHedgeEffectiveness must be a finite number when provided. Received ${input.betaOrHedgeEffectiveness === null ? 'null' : String(input.betaOrHedgeEffectiveness)}.`, { code: ErrorCode.InputWrongType, context: { field: 'betaOrHedgeEffectiveness' } });
+    }
+    const beta = input.betaOrHedgeEffectiveness ?? 1;
+    return requireRepresentableResult('futuresHedgeRatio', {
+        contractsRequired: (input.exposureQuantity * beta) / input.futuresContractSize,
+        assumptions: {
+            betaOrHedgeEffectiveness: beta,
+            hedgeRatioBasis: input.betaOrHedgeEffectiveness === undefined
+                ? 'one-to-one'
+                : 'caller-supplied beta or hedge effectiveness',
+            rounding: 'contractsRequired is a real number; rounding to whole contracts is the caller’s execution decision',
+        },
+        diagnostics: { warnings: [] },
+    });
+}
+/**
+ * The basis between spot and a quoted futures price. `basis` (a price difference) and
+ * `basisFraction` (a dimensionless ratio) are DIFFERENT quantities and both deserve names — the
+ * library's naming law already blesses exactly this pair.
+ */
+export function commodityBasis(input) {
+    requireArgumentObject('commodityBasis', 'input', input);
+    ensureKnownKeys('commodityBasis', 'input', input, ['spotPrice', 'futuresPrice']);
+    requireFiniteFields('commodityBasis', input, ['spotPrice', 'futuresPrice'], { exampleCall: 'commodityBasis({ spotPrice: 72, futuresPrice: 73.5 })' });
+    requirePositive('commodityBasis', 'spotPrice', input.spotPrice, 'basis needs a positive spot.');
+    requirePositive('commodityBasis', 'futuresPrice', input.futuresPrice, 'basis needs a positive futures price.');
+    return requireRepresentableResult('commodityBasis', {
+        basis: input.spotPrice - input.futuresPrice,
+        basisFraction: input.spotPrice / input.futuresPrice - 1,
+        assumptions: {
+            definition: 'basis = spotPrice − futuresPrice (positive when spot trades above the future); basisFraction = spotPrice / futuresPrice − 1 — two DIFFERENT quantities, both named',
+        },
+        diagnostics: { warnings: [] },
+    });
+}
+//# sourceMappingURL=forwards.js.map