@insiderfinance/totalfinance 0.1.0

package/modules/valuation/dist/loans.js

@@ -0,0 +1,518 @@
+/**
+ * FC1 — annuities, loans, and amortization schedules.
+ *
+ * Required semantics (spec, frozen): payment timing is EXPLICIT (`'end'` or `'beginning'` of
+ * period); balloon/residual value is explicit; schedule rows expose opening balance, payment,
+ * interest, principal, fees when supplied, and closing balance; the unrounded schedule reconciles
+ * exactly within tolerance and any rounding policy is explicit; payment components are SIGNED.
+ *
+ * Sign convention (the 2026-08-23 review resolution): for a nonnegative periodic rate every
+ * component is a positive magnitude, exactly as before. A NEGATIVE periodic rate is economically
+ * real (the accepted domain is rate > −100%) and produces a NEGATIVE interest component — the
+ * borrower is credited interest — with a principal component EXCEEDING the payment, so the
+ * reconciliation identities (`payment = interest + principal`, `closing = opening − principal`)
+ * hold with signs intact. The docs used to promise unconditional positivity while the code
+ * returned signed components; the components are the honest quantity, so the docs now say signed.
+ */
+import { ConvergenceError, ErrorCode, InputError, assertFiniteValue, ensureKnownKeys, requireArgumentObject, requireFiniteFields, requireRepresentableResult, } from '../../core/dist/index.js';
+/**
+ * The most periods any loan head accepts (2026-08-23 review, P0 "unbounded work"): 100,000 is
+ * monthly for 8,333 years — generous for any real loan — while the old `Number.isInteger` gate
+ * admitted values like 1e308 (`Number.isInteger(1e308)` is `true`), and the schedule heads
+ * materialize one row per period, so an absurd count is a request for effectively infinite
+ * synchronous work (above 2^53, `period++` stops changing and the loop cannot even terminate).
+ * The derived period coordinates (`period`, `fromPeriod`, `toPeriod`) are bounded by
+ * `numberOfPeriods`, so this one cap bounds every loan loop. (Module-private: the teaching errors
+ * state the bound, and a new runtime export would widen the public surface for a limit.)
+ */
+const MAX_LOAN_PERIODS = 100_000;
+const LOAN_KEYS = [
+    'principal',
+    'periodicInterestRate',
+    'numberOfPeriods',
+    'paymentTiming',
+    'balloon',
+];
+const LOAN_TERMS_EXAMPLE = "principal: 250_000, periodicInterestRate: 0.06 / 12, numberOfPeriods: 360, paymentTiming: 'end'";
+/**
+ * A WORKING example for whichever head reached the shared terms validator. The teaching names the
+ * REPORTED function, so the example must be pasteable for that function — the period/range heads
+ * require fields the bare terms example would omit.
+ */
+function loanExampleCall(functionName) {
+    switch (functionName) {
+        case 'loanInterestPayment':
+        case 'loanPrincipalPayment':
+            return `${functionName}({ ${LOAN_TERMS_EXAMPLE}, period: 12 })`;
+        case 'cumulativeLoanInterest':
+        case 'cumulativeLoanPrincipal':
+            return `${functionName}({ ${LOAN_TERMS_EXAMPLE}, fromPeriod: 1, toPeriod: 12 })`;
+        default:
+            return `${functionName}({ ${LOAN_TERMS_EXAMPLE} })`;
+    }
+}
+function validateLoanTerms(functionName, input) {
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, LOAN_KEYS);
+    requireFiniteFields(functionName, input, ['principal', 'periodicInterestRate', 'numberOfPeriods'], { exampleCall: () => loanExampleCall(functionName) });
+    if (input.paymentTiming !== 'end' && input.paymentTiming !== 'beginning') {
+        throw new InputError(`${functionName}: paymentTiming must be 'end' | 'beginning' — timing changes every number, so it is never guessed. Received ${input.paymentTiming === null ? 'null' : JSON.stringify(input.paymentTiming)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'paymentTiming' } });
+    }
+    if (input.principal <= 0) {
+        throw new InputError(`${functionName}: principal must be > 0 (the amount borrowed). Received ${input.principal}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'principal' } });
+    }
+    // Safe integer AND a work cap (2026-08-23 review, P0): `Number.isInteger(1e308)` is `true`, so
+    // the old check let a caller request one schedule row per "period" of an astronomically large
+    // count — effectively infinite synchronous work, and literally non-terminating above 2^53.
+    if (!Number.isSafeInteger(input.numberOfPeriods) ||
+        input.numberOfPeriods < 1 ||
+        input.numberOfPeriods > MAX_LOAN_PERIODS) {
+        throw new InputError(`${functionName}: numberOfPeriods must be an integer in [1, ${MAX_LOAN_PERIODS.toLocaleString('en-US')}] — the schedule materializes one row per period, and ${MAX_LOAN_PERIODS.toLocaleString('en-US')} periods is monthly for ${(MAX_LOAN_PERIODS / 12).toLocaleString('en-US', { maximumFractionDigits: 0 })} years, beyond any real loan. Received ${input.numberOfPeriods}.\n  e.g. ${loanExampleCall(functionName)}`, { code: ErrorCode.InputOutOfRange, context: { field: 'numberOfPeriods' } });
+    }
+    if (input.periodicInterestRate <= -1) {
+        throw new InputError(`${functionName}: periodicInterestRate must exceed −100% per period. Received ${input.periodicInterestRate}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'periodicInterestRate' } });
+    }
+    const balloon = input.balloon ?? 0;
+    if (input.balloon !== undefined) {
+        if (typeof input.balloon !== 'number' || !Number.isFinite(input.balloon)) {
+            throw new InputError(`${functionName}: balloon must be a finite number when provided (the explicit residual balance). Received ${input.balloon === null ? 'null' : typeof input.balloon}.`, { code: ErrorCode.InputWrongType, context: { field: 'balloon' } });
+        }
+        if (input.balloon < 0 || input.balloon >= input.principal) {
+            throw new InputError(`${functionName}: balloon must satisfy 0 ≤ balloon < principal. Received ${input.balloon}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'balloon' } });
+        }
+    }
+    return { balloon };
+}
+/** The timing factor: an annuity-due payment is worth one extra period of interest. */
+function timingFactor(rate, timing) {
+    return timing === 'beginning' ? 1 + rate : 1;
+}
+/**
+ * The RAW closed-form level payment, computed overflow-stably (2026-08-23 review, finding 1). The
+ * naive form `(principal · growth − balloon) / (annuity · timingFactor)` overflows its NUMERATOR
+ * at a principal near `Number.MAX_VALUE` even when the payment itself is representable, and turns
+ * a huge candidate rate into Infinity / Infinity = NaN inside the rate solver. Three regimes, all
+ * algebraically identical:
+ *
+ *   1. `growth` rounds to exactly 1 (a denormal-scale rate): the annuity quotient degenerates to
+ *      0/rate = 0, so the rate-0 limit `(principal − balloon) / (periods · timingFactor)` is the
+ *      stable value the closed form is approaching;
+ *   2. the ordinary regime: divide the numerator THROUGH by the annuity factor first —
+ *      `principal · (growth / annuityTiming) − balloon / annuityTiming` — so a near-MAX_VALUE
+ *      principal only overflows when the true payment does;
+ *   3. `annuityTiming` overflows (huge growth over a small rate, or growth itself infinite):
+ *      divide the closed form through by `growth` — `1/growth` underflows to 0 exactly where the
+ *      balloon term vanishes, and the payment tends to `principal · rate / timingFactor`.
+ *
+ * May return a NON-FINITE value (an honest signed limit, e.g. rate → −1 under 'beginning' timing
+ * where the whole payment falls at a vanishing timing factor): the PUBLIC head refuses that with a
+ * typed teaching via {@link requireRepresentableResult}; the rate solver's bracket expansion
+ * consumes it as an ordinary objective value.
+ */
+function levelPaymentValue(principal, rate, periods, timing, balloon) {
+    if (rate === 0) {
+        return (principal - balloon) / periods;
+    }
+    const growth = Math.pow(1 + rate, periods);
+    if (growth === 1) {
+        return (principal - balloon) / (periods * timingFactor(rate, timing));
+    }
+    const annuityTiming = ((growth - 1) / rate) * timingFactor(rate, timing);
+    if (Number.isFinite(growth) && Number.isFinite(annuityTiming) && annuityTiming !== 0) {
+        return principal * (growth / annuityTiming) - balloon / annuityTiming;
+    }
+    const inverseGrowth = Number.isFinite(growth) ? 1 / growth : 0;
+    const ratePerTiming = rate / timingFactor(rate, timing);
+    return ((principal - balloon * inverseGrowth) * ratePerTiming) / (1 - inverseGrowth);
+}
+/**
+ * The level payment that amortizes `principal` down to `balloon` over `numberOfPeriods` at the
+ * periodic rate, under the explicit payment timing. Positive for every nonnegative-rate loan;
+ * SIGNED in general — a negative periodic rate can decay the principal below a balloon on its
+ * own, making the level payment zero or negative (the lender pays the borrower to hold the
+ * schedule to its residual). A payment the arithmetic cannot represent (IEEE-754 overflow at
+ * extreme magnitudes) is a typed refusal, never Infinity/NaN (2026-08-23 review, finding 1).
+ */
+export function annuityPayment(input) {
+    const { balloon } = validateLoanTerms('annuityPayment', input);
+    return requireRepresentableResult('annuityPayment', levelPaymentValue(input.principal, input.periodicInterestRate, input.numberOfPeriods, input.paymentTiming, balloon));
+}
+const SCHEDULE_KEYS = [...LOAN_KEYS, 'periodicFee'];
+/**
+ * The full amortization schedule. Unrounded by design — the rows reconcile exactly (each closing
+ * balance = opening − principal; Σ principal = principal − balloon) and any display rounding is
+ * the caller's explicit, documented policy applied afterwards.
+ */
+export function amortizationSchedule(input) {
+    requireArgumentObject('amortizationSchedule', 'input', input);
+    ensureKnownKeys('amortizationSchedule', 'input', input, SCHEDULE_KEYS);
+    const { periodicFee, ...terms } = input;
+    const { balloon } = validateLoanTerms('amortizationSchedule', terms);
+    if (periodicFee !== undefined &&
+        (typeof periodicFee !== 'number' || !Number.isFinite(periodicFee) || periodicFee < 0)) {
+        throw new InputError(`amortizationSchedule: periodicFee must be a finite number ≥ 0 when provided. Received ${periodicFee === null ? 'null' : String(periodicFee)}.`, { code: ErrorCode.InputWrongType, context: { field: 'periodicFee' } });
+    }
+    const payment = annuityPayment(terms);
+    const rate = input.periodicInterestRate;
+    const rows = [];
+    let balance = input.principal;
+    let totalInterest = 0;
+    for (let period = 1; period <= input.numberOfPeriods; period++) {
+        // Beginning-timing payments reduce the balance BEFORE the period accrues interest.
+        const interestBase = input.paymentTiming === 'beginning' ? balance - payment : balance;
+        const interest = interestBase * rate;
+        const closing = balance - (payment - interest);
+        rows.push({
+            period,
+            openingBalance: balance,
+            payment,
+            interest,
+            principal: payment - interest,
+            ...(periodicFee !== undefined ? { fee: periodicFee } : {}),
+            closingBalance: closing,
+        });
+        totalInterest += interest;
+        balance = closing;
+    }
+    // 2026-08-23 review, finding 1: a schedule whose running balances or totals overflow IEEE-754
+    // doubles is a typed refusal, never rows carrying Infinity/NaN.
+    return requireRepresentableResult('amortizationSchedule', {
+        rows,
+        payment,
+        totalInterest,
+        totalPrincipal: input.principal - balloon,
+        balloon,
+        rounding: 'none',
+    });
+}
+const PERIOD_KEYS = [...LOAN_KEYS, 'period'];
+function validatePeriod(functionName, input) {
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, PERIOD_KEYS);
+    const { period, ...terms } = input;
+    validateLoanTerms(functionName, terms);
+    // Safe integer (2026-08-23 review, P0): above 2^53 an "integer" period can no longer be exact.
+    // The upper work bound is inherited — period ≤ numberOfPeriods ≤ MAX_LOAN_PERIODS.
+    if (!Number.isSafeInteger(period) || period < 1 || period > input.numberOfPeriods) {
+        throw new InputError(`${functionName}: period must be an integer in [1, numberOfPeriods]. Received ${String(period)}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'period' } });
+    }
+}
+/**
+ * Interest portion of the payment in one period — SIGNED: positive for a nonnegative rate,
+ * negative when the periodic rate is negative (the period credits interest to the borrower).
+ */
+export function loanInterestPayment(input) {
+    validatePeriod('loanInterestPayment', input);
+    const { period, ...terms } = input;
+    return requireRepresentableResult('loanInterestPayment', amortizationSchedule(terms).rows[period - 1].interest);
+}
+/**
+ * Balance reduction in one period (`payment − interest`) — SIGNED: exceeds the payment when the
+ * periodic rate (and so the interest component) is negative.
+ */
+export function loanPrincipalPayment(input) {
+    validatePeriod('loanPrincipalPayment', input);
+    const { period, ...terms } = input;
+    return requireRepresentableResult('loanPrincipalPayment', amortizationSchedule(terms).rows[period - 1].principal);
+}
+const RANGE_KEYS = [...LOAN_KEYS, 'fromPeriod', 'toPeriod'];
+function validateRange(functionName, input) {
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, RANGE_KEYS);
+    const { fromPeriod, toPeriod, ...terms } = input;
+    validateLoanTerms(functionName, terms);
+    // Safe integers (2026-08-23 review, P0): the range loop is bounded by these two, and above 2^53
+    // an "integer" bound can no longer be exact. The work cap is inherited — toPeriod ≤
+    // numberOfPeriods ≤ MAX_LOAN_PERIODS.
+    if (!Number.isSafeInteger(fromPeriod) ||
+        !Number.isSafeInteger(toPeriod) ||
+        fromPeriod < 1 ||
+        toPeriod < fromPeriod ||
+        toPeriod > input.numberOfPeriods) {
+        throw new InputError(`${functionName}: 1 ≤ fromPeriod ≤ toPeriod ≤ numberOfPeriods must hold. Received fromPeriod=${String(fromPeriod)}, toPeriod=${String(toPeriod)}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'fromPeriod' } });
+    }
+}
+/**
+ * Total interest across an inclusive period range — SIGNED: positive for a nonnegative rate,
+ * negative when the periodic rate is negative (interest credited to the borrower).
+ */
+export function cumulativeLoanInterest(input) {
+    validateRange('cumulativeLoanInterest', input);
+    const { fromPeriod, toPeriod, ...terms } = input;
+    const { rows } = amortizationSchedule(terms);
+    let total = 0;
+    for (let period = fromPeriod; period <= toPeriod; period++)
+        total += rows[period - 1].interest;
+    // 2026-08-23 review, finding 1: finite rows can still SUM past Number.MAX_VALUE — refuse.
+    return requireRepresentableResult('cumulativeLoanInterest', total);
+}
+/**
+ * Total balance reduction across an inclusive period range — SIGNED: exceeds the payments made
+ * when the periodic rate is negative (each period's principal component exceeds its payment).
+ */
+export function cumulativeLoanPrincipal(input) {
+    validateRange('cumulativeLoanPrincipal', input);
+    const { fromPeriod, toPeriod, ...terms } = input;
+    const { rows } = amortizationSchedule(terms);
+    let total = 0;
+    for (let period = fromPeriod; period <= toPeriod; period++)
+        total += rows[period - 1].principal;
+    // 2026-08-23 review, finding 1: finite rows can still SUM past Number.MAX_VALUE — refuse.
+    return requireRepresentableResult('cumulativeLoanPrincipal', total);
+}
+const NUMBER_OF_PERIODS_EXAMPLE = "loanNumberOfPeriods({ principal: 250_000, periodicInterestRate: 0.06 / 12, payment: 1_498.88, paymentTiming: 'end' })";
+/** Periods (possibly fractional) for `payment` to amortize `principal` down to `balloon`. */
+export function loanNumberOfPeriods(input) {
+    requireArgumentObject('loanNumberOfPeriods', 'input', input);
+    ensureKnownKeys('loanNumberOfPeriods', 'input', input, [
+        'principal',
+        'periodicInterestRate',
+        'payment',
+        'paymentTiming',
+        'balloon',
+    ]);
+    requireFiniteFields('loanNumberOfPeriods', input, ['principal', 'periodicInterestRate', 'payment'], { exampleCall: NUMBER_OF_PERIODS_EXAMPLE });
+    if (input.paymentTiming !== 'end' && input.paymentTiming !== 'beginning') {
+        throw new InputError(`loanNumberOfPeriods: paymentTiming must be 'end' | 'beginning'. Received ${JSON.stringify(input.paymentTiming)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'paymentTiming' } });
+    }
+    // The economic domain — the same laws validateLoanTerms states for every forward head. Outside
+    // it, the closed form still produces a NUMBER (0 periods at rate −100%, negative periods for a
+    // negative principal) — a plausible wrong answer, which is exactly what must never leave here.
+    if (input.principal <= 0) {
+        throw new InputError(`loanNumberOfPeriods: principal must be > 0 (the amount borrowed). Received ${input.principal}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'principal' } });
+    }
+    if (input.periodicInterestRate <= -1) {
+        throw new InputError(`loanNumberOfPeriods: periodicInterestRate must exceed −100% per period. Received ${input.periodicInterestRate}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'periodicInterestRate' } });
+    }
+    // A nonpositive payment is a DOMAIN refusal, checked before any arithmetic (the 2026-08-23
+    // review): the input contract documents the level payment as a positive magnitude, and letting
+    // zero or a negative payment reach the closed form used to surface as the SOLVER's "no positive,
+    // finite number of periods" refusal — a solver outcome for what was never a solvable question.
+    if (input.payment <= 0) {
+        throw new InputError(`loanNumberOfPeriods: payment must be > 0 (the level payment is a positive magnitude — a zero or negative payment can never amortize a positive principal). Received ${input.payment}.\n  e.g. ${NUMBER_OF_PERIODS_EXAMPLE}`, { code: ErrorCode.InputOutOfRange, context: { field: 'payment' } });
+    }
+    // Null is a wrong-typed value, not omission (the 350c2796 ruling): `?? 0` must never launder it.
+    if (input.balloon !== undefined &&
+        (typeof input.balloon !== 'number' || !Number.isFinite(input.balloon) || input.balloon < 0)) {
+        throw new InputError(`loanNumberOfPeriods: balloon must be a finite number ≥ 0 when provided. Received ${input.balloon === null ? 'null' : String(input.balloon)}.`, { code: ErrorCode.InputWrongType, context: { field: 'balloon' } });
+    }
+    if (input.balloon !== undefined && input.balloon >= input.principal) {
+        throw new InputError(`loanNumberOfPeriods: balloon must satisfy 0 ≤ balloon < principal — a residual at or above the amount borrowed leaves nothing to amortize. Received balloon ${input.balloon} against principal ${input.principal}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'balloon' } });
+    }
+    const balloon = input.balloon ?? 0;
+    const rate = input.periodicInterestRate;
+    const effectivePayment = input.payment * timingFactor(rate, input.paymentTiming);
+    let periods;
+    if (rate === 0) {
+        periods = (input.principal - balloon) / input.payment;
+    }
+    else {
+        const perPeriodInterest = input.principal * rate;
+        if (effectivePayment <= perPeriodInterest) {
+            throw new InputError(`loanNumberOfPeriods: the payment (${input.payment}) does not cover one period's interest (${perPeriodInterest.toFixed(2)}) — the balance never falls.`, { code: ErrorCode.InputOutOfRange, context: { field: 'payment' } });
+        }
+        periods =
+            Math.log((effectivePayment - balloon * rate) / (effectivePayment - input.principal * rate)) /
+                Math.log(1 + rate);
+    }
+    // Verify before returning: the result must be a finite positive period count AND satisfy the
+    // amortization identity `principal·(1+r)^n − effectivePayment·((1+r)^n − 1)/r = balloon`
+    // (rate 0: `principal − n·payment = balloon`). A closed form fed degenerate-but-finite inputs
+    // can emit a plausible wrong number — a solver refuses instead.
+    let identityHolds = false;
+    if (Number.isFinite(periods) && periods > 0) {
+        if (rate === 0) {
+            const residual = input.principal - input.payment * periods - balloon;
+            identityHolds =
+                Math.abs(residual) <= 1e-8 * Math.max(1, Math.abs(input.principal), Math.abs(balloon));
+        }
+        else {
+            const growth = Math.pow(1 + rate, periods);
+            const amortized = (effectivePayment * (growth - 1)) / rate;
+            const projectedBalloon = input.principal * growth - amortized;
+            const scale = Math.max(1, Math.abs(input.principal * growth), Math.abs(amortized));
+            identityHolds =
+                Number.isFinite(projectedBalloon) && Math.abs(projectedBalloon - balloon) <= 1e-8 * scale;
+        }
+    }
+    if (!identityHolds) {
+        throw new ConvergenceError(`loanNumberOfPeriods: no positive, finite number of periods satisfies the amortization identity for these terms (the closed form produced ${periods}) — the payment cannot amortize this principal down to the balloon at this rate. Check the payment against the principal, rate, and balloon.\n  e.g. loanNumberOfPeriods({ principal: 250_000, periodicInterestRate: 0.06 / 12, payment: 1_498.88, paymentTiming: 'end' })`, {
+            code: ErrorCode.SolverNoConvergence,
+            context: { field: 'payment', computedPeriods: periods },
+        });
+    }
+    // Law 7: a finite-input overflow must never leave here as a successful non-finite value.
+    assertFiniteValue('loanNumberOfPeriods', periods);
+    return periods;
+}
+/**
+ * The largest upper probe the bracket expansion may reach before refusing: essentially the whole
+ * representable positive range. Stopping AT a cap is only ever a refusal with a teaching error —
+ * never a returned number — so the cap can be generous without risking a plausible wrong answer.
+ */
+const RATE_BRACKET_CEILING = 1e308;
+/** The closest the lower probe's growth factor `1 + rate` may get to 0 before refusing. */
+const RATE_BRACKET_GROWTH_FLOOR = 1e-12;
+const PERIODIC_RATE_EXAMPLE = "loanPeriodicInterestRate({ principal: 250_000, numberOfPeriods: 360, payment: 1_498.88, paymentTiming: 'end' })";
+/**
+ * The per-period rate that makes `payment` amortize `principal` — a PROVEN bracket on the monotone
+ * payment-in-rate map (geometric expansion until the sign changes, over the full economic domain
+ * `rate > −1`), then bisection, then a residual check that the found rate actually reproduces the
+ * payment. The closed form for one period shows the rate can be astronomically large
+ * (`payment / principal − 1`), so the expansion never stops at an arbitrary cap and returns —
+ * failing to bracket is a refusal with a teaching error, never a number.
+ *
+ * One shape is refused BEFORE the solver: a one-period `'beginning'` loan with no balloon pays its
+ * single installment at time zero, so the rate never touches a cash flow — the rate is
+ * unidentifiable when `payment === principal` (every rate satisfies the identity) and no rate
+ * solves it otherwise. See the inline teaching errors for both sub-cases.
+ */
+export function loanPeriodicInterestRate(input) {
+    requireArgumentObject('loanPeriodicInterestRate', 'input', input);
+    ensureKnownKeys('loanPeriodicInterestRate', 'input', input, [
+        'principal',
+        'numberOfPeriods',
+        'payment',
+        'paymentTiming',
+        'balloon',
+    ]);
+    requireFiniteFields('loanPeriodicInterestRate', input, ['principal', 'numberOfPeriods', 'payment'], { exampleCall: PERIODIC_RATE_EXAMPLE });
+    if (input.paymentTiming !== 'end' && input.paymentTiming !== 'beginning') {
+        throw new InputError(`loanPeriodicInterestRate: paymentTiming must be 'end' | 'beginning'. Received ${JSON.stringify(input.paymentTiming)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'paymentTiming' } });
+    }
+    // The economic domain — the same laws validateLoanTerms states for every forward head, checked
+    // HERE so the teaching error names the function the caller typed, not an internal helper.
+    if (input.principal <= 0) {
+        throw new InputError(`loanPeriodicInterestRate: principal must be > 0 (the amount borrowed). Received ${input.principal}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'principal' } });
+    }
+    // ONE law for every loan head (2026-08-23 review, P0): the solver feeds this count to the same
+    // level-payment algebra the forward heads validate, so it takes the same safe-integer + work cap
+    // — `Number.isInteger(1e308)` is `true`, and an uncapped count is a request for unbounded work.
+    if (!Number.isSafeInteger(input.numberOfPeriods) ||
+        input.numberOfPeriods < 1 ||
+        input.numberOfPeriods > MAX_LOAN_PERIODS) {
+        throw new InputError(`loanPeriodicInterestRate: numberOfPeriods must be an integer in [1, ${MAX_LOAN_PERIODS.toLocaleString('en-US')}] — ${MAX_LOAN_PERIODS.toLocaleString('en-US')} periods is monthly for ${(MAX_LOAN_PERIODS / 12).toLocaleString('en-US', { maximumFractionDigits: 0 })} years, beyond any real loan. Received ${input.numberOfPeriods}.\n  e.g. ${PERIODIC_RATE_EXAMPLE}`, { code: ErrorCode.InputOutOfRange, context: { field: 'numberOfPeriods' } });
+    }
+    // A nonpositive payment is a DOMAIN refusal, checked before any arithmetic (the 2026-08-23
+    // review): the input contract documents the level payment as a positive magnitude, so it must
+    // never read as a solver outcome.
+    if (input.payment <= 0) {
+        throw new InputError(`loanPeriodicInterestRate: payment must be > 0 (the level payment is a positive magnitude). Received ${input.payment}.\n  e.g. ${PERIODIC_RATE_EXAMPLE}`, { code: ErrorCode.InputOutOfRange, context: { field: 'payment' } });
+    }
+    if (input.balloon !== undefined &&
+        (typeof input.balloon !== 'number' ||
+            !Number.isFinite(input.balloon) ||
+            input.balloon < 0 ||
+            input.balloon >= input.principal)) {
+        throw new InputError(`loanPeriodicInterestRate: balloon must be a finite number satisfying 0 ≤ balloon < principal when provided. Received ${input.balloon === null ? 'null' : String(input.balloon)}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'balloon' } });
+    }
+    // The unidentifiable shape, refused BEFORE the solver (the 2026-08-23 review): a one-period
+    // 'beginning' (annuity-due) loan with no balloon pays its single installment at time ZERO,
+    // before any interest can accrue, so the amortization identity reads payment = principal at
+    // EVERY rate > −100% — the rate never touches a cash flow. Two sub-cases, neither solvable:
+    //  - payment === principal: every rate satisfies the identity, so no unique rate exists (the
+    //    bisection used to return 0 here as if zero were THE implied rate);
+    //  - payment !== principal: NO rate satisfies it — the identity is rate-free and already false.
+    // The bracket solver must not run at all: it would either canonize an arbitrary rate or grind a
+    // full bracket expansion to refuse what the algebra already knows. (A balloon restores
+    // identifiability — the residual is discounted through `balloon / (1 + rate)` — so this gate is
+    // strictly the no-balloon shape.)
+    if (input.numberOfPeriods === 1 &&
+        input.paymentTiming === 'beginning' &&
+        (input.balloon ?? 0) === 0) {
+        if (input.payment === input.principal) {
+            throw new InputError(`loanPeriodicInterestRate: the rate is UNIDENTIFIABLE for a one-period 'beginning' (annuity-due) loan with no balloon — the single payment falls at time zero, before any interest accrues, so payment = principal holds at EVERY rate > −100% and no unique rate exists. Identify the rate from terms the rate can touch: use 'end' timing, more than one period, or a balloon.\n  e.g. ${PERIODIC_RATE_EXAMPLE}`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { field: 'paymentTiming', reason: 'rate_unidentifiable' },
+            });
+        }
+        throw new InputError(`loanPeriodicInterestRate: NO rate solves a one-period 'beginning' (annuity-due) loan with no balloon unless payment equals principal exactly — the single payment falls at time zero, before any interest accrues, so the identity reads payment = principal at every rate and the rate cannot reconcile the difference. Received payment ${input.payment} against principal ${input.principal}.\n  e.g. ${PERIODIC_RATE_EXAMPLE}`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { field: 'payment', reason: 'no_rate_exists' },
+        });
+    }
+    /**
+     * The level payment at a candidate rate — the same {@link levelPaymentValue} closed form the
+     * public {@link annuityPayment} head returns, WITHOUT the head's representability refusal
+     * (2026-08-23 review, finding 1: the head now refuses a non-finite payment with a typed
+     * teaching, but the bracket expansion legitimately probes rates whose payment overflows — for
+     * 'end' timing the payment tends to `principal · rate / timingFactor`, unbounded in the probe —
+     * and a ±Infinity objective value is exactly how the expansion learns it has overshot). A
+     * non-finite value on the SMALL-growth side (rate → −1 with a vanishing timing factor) is
+     * likewise an honest signed limit the bisection consumes directly.
+     */
+    const paymentAtRate = (rate) => levelPaymentValue(input.principal, rate, input.numberOfPeriods, input.paymentTiming, input.balloon ?? 0);
+    // Monotone increasing in rate: a higher rate needs a higher level payment for the same terms.
+    const objective = (rate) => paymentAtRate(rate) - input.payment;
+    const atZeroRate = objective(0);
+    let low;
+    let high;
+    if (atZeroRate === 0) {
+        low = 0;
+        high = 0;
+    }
+    else if (atZeroRate < 0) {
+        // The payment exceeds the zero-rate level payment → the implied rate is positive. Expand the
+        // upper probe geometrically until the payment function changes sign.
+        low = 0;
+        high = 1;
+        while (objective(high) < 0) {
+            low = high;
+            high *= 2;
+            if (high > RATE_BRACKET_CEILING) {
+                throw new ConvergenceError(`loanPeriodicInterestRate: no per-period rate reproduces the payment ${input.payment} — the level payment stays below the target across the entire searched domain (0, ${RATE_BRACKET_CEILING}] within the economically meaningful range rate > −1. For 'beginning' timing the level payment is bounded above by the principal (the first payment falls before any interest accrues), so a payment at or above the principal has no implied rate.`, {
+                    code: ErrorCode.SolverNoConvergence,
+                    context: { field: 'payment', searchedDomain: `(0, ${RATE_BRACKET_CEILING}]` },
+                });
+            }
+        }
+    }
+    else {
+        // The payment is below the zero-rate level payment → the implied rate is negative. Probe
+        // toward −100% by halving the growth factor 1 + rate until the sign changes; the arithmetic
+        // itself ends at −100%, so reaching the floor without a sign change is a refusal.
+        high = 0;
+        let growthFactor = 0.5;
+        low = growthFactor - 1;
+        while (objective(low) > 0) {
+            high = low;
+            growthFactor /= 2;
+            low = growthFactor - 1;
+            if (growthFactor < RATE_BRACKET_GROWTH_FLOOR) {
+                throw new ConvergenceError(`loanPeriodicInterestRate: no per-period rate reproduces the payment ${input.payment} — the level payment stays above the target across the entire searched domain (−1 + ${RATE_BRACKET_GROWTH_FLOOR}, 0] within the economically meaningful range rate > −1.`, {
+                    code: ErrorCode.SolverNoConvergence,
+                    context: { field: 'payment', searchedDomain: `(−1 + ${RATE_BRACKET_GROWTH_FLOOR}, 0]` },
+                });
+            }
+        }
+    }
+    for (let iteration = 0; iteration < 200 && low < high; iteration++) {
+        const mid = low + (high - low) / 2;
+        if (mid === low || mid === high)
+            break; // the interval is at floating-point resolution
+        const value = objective(mid);
+        if (value === 0) {
+            low = mid;
+            high = mid;
+            break;
+        }
+        if (value < 0)
+            low = mid;
+        else
+            high = mid;
+    }
+    const impliedRate = low + (high - low) / 2;
+    // Verify the root before returning it: the found rate must actually reproduce the payment.
+    const reproducedPayment = paymentAtRate(impliedRate);
+    const relativeResidual = Math.abs(reproducedPayment - input.payment) / Math.max(1, Math.abs(input.payment));
+    if (!Number.isFinite(impliedRate) || !(relativeResidual <= 1e-6)) {
+        throw new ConvergenceError(`loanPeriodicInterestRate: the bracketed root did not reproduce the payment — loanPayment(rate ${impliedRate}) = ${reproducedPayment} against the requested ${input.payment} (relative residual ${relativeResidual}, tolerance 1e-6). This is a refusal rather than a plausible wrong number; please report it with your inputs.`, {
+            code: ErrorCode.SolverNoConvergence,
+            context: { field: 'payment', impliedRate, relativeResidual },
+        });
+    }
+    // Law 7: a finite-input overflow must never leave here as a successful non-finite value.
+    assertFiniteValue('loanPeriodicInterestRate', impliedRate);
+    return impliedRate;
+}
+//# sourceMappingURL=loans.js.map

package/modules/valuation/dist/loans.js.map

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

package/modules/valuation/dist/probabilistic.d.ts

@@ -0,0 +1,88 @@
+/**
+ * FC2 — the probabilistic DCF. Explicit marginal distributions over named DCF variables, explicit
+ * dependence, explicit sample count and seed. It never turns an unlabeled base case into a
+ * stochastic forecast: every randomized variable is declared, everything else stays fixed, and the
+ * same seed reproduces the run exactly.
+ */
+import { type DiscountedCashFlowInput, type DiscountedCashFlowResult } from './discounted-cash-flow.js';
+/** An explicit marginal distribution. */
+export type MarginalDistribution = {
+    type: 'normal';
+    mean: number;
+    standardDeviation: number;
+} | {
+    type: 'uniform';
+    from: number;
+    to: number;
+} | {
+    type: 'triangular';
+    minimum: number;
+    mode: number;
+    maximum: number;
+};
+/** One randomized DCF variable. `'cash-flow-scale'` shocks the whole stream proportionally. */
+export interface RandomizedVariable {
+    variable: 'annual-discount-rate' | 'perpetual-growth-rate' | 'cash-flow-scale';
+    distribution: MarginalDistribution;
+}
+/** Input for {@link probabilisticDiscountedCashFlow}. */
+export interface ProbabilisticDiscountedCashFlowInput {
+    discountedCashFlowInput: DiscountedCashFlowInput;
+    distributions: readonly RandomizedVariable[];
+    /**
+     * Correlation matrix over `distributions` (Gaussian dependence, applied before the marginal
+     * transforms). Omitted → independent.
+     */
+    correlationMatrix?: readonly (readonly number[])[];
+    sampleCount: number;
+    seed: number;
+}
+/** Result of {@link probabilisticDiscountedCashFlow}. */
+export interface ProbabilisticDiscountedCashFlowResult {
+    diagnostics: {
+        /** One warning per rejected-sample reason (count included). */
+        warnings: string[];
+    };
+    /** The value the distribution describes (per the base input's valuation basis). */
+    valueDescribed: 'enterpriseValue' | 'equityValue';
+    sampleCount: number;
+    seed: number;
+    /** Samples whose drawn variables kept the model inside its domain. */
+    validSampleCount: number;
+    /** Samples the model's own laws rejected (e.g. growth ≥ rate), with the reasons tallied. */
+    rejectedSamples: {
+        count: number;
+        reasons: Record<string, number>;
+    };
+    mean: number;
+    standardDeviation: number;
+    quantiles: {
+        p05: number;
+        p10: number;
+        p25: number;
+        p50: number;
+        p75: number;
+        p90: number;
+        p95: number;
+    };
+    minimum: number;
+    maximum: number;
+    /** Left-tail diagnostics: the sampled probability that the value falls at or below zero. */
+    probabilityAtOrBelowZero: number;
+    /** The exact seeded assumptions, echoed for reproduction. */
+    assumptions: {
+        distributions: readonly RandomizedVariable[];
+        correlationMatrix: readonly (readonly number[])[] | 'independent';
+        dependence: 'gaussian-copula-over-declared-correlations';
+        baseCase: DiscountedCashFlowResult;
+    };
+}
+/**
+ * Monte-Carlo DCF over the DECLARED randomized variables: Gaussian dependence per the supplied
+ * correlations, inverse-CDF marginal transforms, one direct {@link discountedCashFlow} call per
+ * sample. A draw the model's own domain rejects (e.g. growth at or above the rate) is counted and
+ * excluded with its reason — never clamped into validity. With every distribution degenerate the
+ * run collapses to the deterministic result exactly.
+ */
+export declare function probabilisticDiscountedCashFlow(input: ProbabilisticDiscountedCashFlowInput): ProbabilisticDiscountedCashFlowResult;
+//# sourceMappingURL=probabilistic.d.ts.map