@insiderfinance/totalfinance 0.1.0

package/modules/valuation/dist/adjusted-present-value.js

@@ -0,0 +1,85 @@
+/**
+ * FC2 — adjusted present value (APV).
+ *
+ * Required semantics (spec, frozen): APV SEPARATES the unlevered operating value from each
+ * financing side effect and their assumptions — the whole point of the method is that the
+ * operating business and the financing consequences are discounted at rates that reflect their
+ * own risk, and the decomposition is reported, never collapsed. Every side effect is labeled,
+ * carries its own discount rate, and is echoed with its present value; the one compounding
+ * convention covers every leg and is echoed.
+ */
+import { requireRepresentableResult, stableSum, ErrorCode, InputError, discountFactor, ensureKnownKeys, requireArgumentArray, requireArgumentObject, requireFiniteFields, } from '../../core/dist/index.js';
+import { requireTimedCashFlows } from './flows.js';
+import { requireCompoundingWhenPresent } from './discounting.js';
+const INPUT_KEYS = [
+    'unleveredCashFlows',
+    'unleveredCostOfCapital',
+    'financingSideEffects',
+    'compounding',
+];
+const SIDE_EFFECT_KEYS = ['label', 'cashFlows', 'annualDiscountRate'];
+const EXAMPLE_CALL = "adjustedPresentValue({ unleveredCashFlows: [{ amount: 100, timeYears: 1 }, { amount: 110, timeYears: 2 }], unleveredCostOfCapital: 0.1, financingSideEffects: [{ label: 'interest tax shield', cashFlows: [{ amount: 8, timeYears: 1 }], annualDiscountRate: 0.05 }] })";
+function requireRateAboveFloor(functionName, field, rate) {
+    if (rate <= -1) {
+        throw new InputError(`${functionName}: ${field} must exceed −100% per year (an annual decimal, e.g. 0.1 for 10%) — at or below −100% the growth factor is not positive. Received ${rate}.`, { code: ErrorCode.InputOutOfRange, context: { field } });
+    }
+}
+function presentValueOfFlows(cashFlows, annualRate, compounding) {
+    return stableSum(cashFlows.map((flow) => flow.amount * discountFactor(annualRate, flow.timeYears, compounding)));
+}
+/**
+ * Adjusted present value: the unlevered operating value at the unlevered cost of capital PLUS the
+ * present value of each financing side effect at its own declared rate. The decomposition is the
+ * result — nothing is netted away silently.
+ */
+export function adjustedPresentValue(input) {
+    const functionName = 'adjustedPresentValue';
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, INPUT_KEYS);
+    requireFiniteFields(functionName, input, ['unleveredCostOfCapital'], {
+        exampleCall: EXAMPLE_CALL,
+        hints: { unleveredCostOfCapital: 'an annual decimal — 0.1 means 10%, not 10' },
+    });
+    requireRateAboveFloor(functionName, 'unleveredCostOfCapital', input.unleveredCostOfCapital);
+    // The shared flow guards name their collection `cashFlows[i]`; the parenthetical names WHICH
+    // collection in this two-collection request, so the error still points at one field.
+    requireTimedCashFlows(`${functionName} (field unleveredCashFlows)`, input.unleveredCashFlows);
+    requireCompoundingWhenPresent(functionName, input.compounding);
+    requireArgumentArray(functionName, 'financingSideEffects', input.financingSideEffects);
+    input.financingSideEffects.forEach((sideEffect, index) => {
+        requireArgumentObject(functionName, `financingSideEffects[${index}]`, sideEffect);
+        ensureKnownKeys(functionName, `financingSideEffects[${index}]`, sideEffect, SIDE_EFFECT_KEYS);
+        if (typeof sideEffect.label !== 'string' || sideEffect.label.length === 0) {
+            throw new InputError(`${functionName}: financingSideEffects[${index}].label must be a non-empty string — an unlabeled side effect cannot be audited in the decomposition. Received ${sideEffect.label === null ? 'null' : typeof sideEffect.label === 'string' ? "''" : typeof sideEffect.label}. e.g. ${EXAMPLE_CALL}`, {
+                code: ErrorCode.InputWrongType,
+                context: { field: `financingSideEffects[${index}].label` },
+            });
+        }
+        requireFiniteFields(functionName, sideEffect, ['annualDiscountRate'], {
+            exampleCall: EXAMPLE_CALL,
+            path: `financingSideEffects[${index}]`,
+        });
+        requireRateAboveFloor(functionName, `financingSideEffects[${index}].annualDiscountRate`, sideEffect.annualDiscountRate);
+        requireTimedCashFlows(`${functionName} (field financingSideEffects[${index}].cashFlows)`, sideEffect.cashFlows);
+    });
+    const compounding = input.compounding ?? 'annual';
+    const unleveredValue = presentValueOfFlows(input.unleveredCashFlows, input.unleveredCostOfCapital, compounding);
+    const financingSideEffects = input.financingSideEffects.map((sideEffect) => ({
+        label: sideEffect.label,
+        presentValue: presentValueOfFlows(sideEffect.cashFlows, sideEffect.annualDiscountRate, compounding),
+        annualDiscountRate: sideEffect.annualDiscountRate,
+    }));
+    const sideEffectTotal = stableSum(financingSideEffects.map((sideEffect) => sideEffect.presentValue));
+    return requireRepresentableResult('adjustedPresentValue', {
+        diagnostics: { warnings: [] },
+        adjustedPresentValue: stableSum([unleveredValue, sideEffectTotal]),
+        unleveredValue,
+        financingSideEffects,
+        assumptions: {
+            unleveredCostOfCapital: input.unleveredCostOfCapital,
+            compounding,
+            sideEffectCount: input.financingSideEffects.length,
+        },
+    });
+}
+//# sourceMappingURL=adjusted-present-value.js.map

package/modules/valuation/dist/adjusted-present-value.js.map

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

package/modules/valuation/dist/capital-budgeting.d.ts

@@ -0,0 +1,84 @@
+/**
+ * FC1 — capital budgeting and depreciation. Depreciation helpers require cost, salvage value,
+ * useful life, and period; they never infer tax rules.
+ */
+import { type InterestCompounding } from '../../core/dist/index.js';
+import { type TimedCashFlow } from './flows.js';
+/** Input for {@link paybackPeriod}. */
+export interface PaybackInput {
+    cashFlows: readonly TimedCashFlow[];
+}
+/**
+ * Input for {@link discountedPaybackPeriod}. A separate interface rather than optional fields on
+ * {@link PaybackInput}: the discounted head REQUIRES its rate at runtime, and a shared type with
+ * `annualDiscountRate?` would license a call the function refuses.
+ */
+export interface DiscountedPaybackInput {
+    cashFlows: readonly TimedCashFlow[];
+    /** Annual rate (decimal). */
+    annualDiscountRate: number;
+    /** Default `'annual'` — documented and echoed. */
+    compounding?: InterestCompounding;
+}
+/**
+ * Years until cumulative cash flow first reaches zero (linear interpolation within the
+ * recovering interval), or `null` when the outlay is never recovered.
+ */
+export declare function paybackPeriod(input: PaybackInput): number | null;
+/** {@link paybackPeriod} on DISCOUNTED flows — the recovery clock respects the time value. */
+export declare function discountedPaybackPeriod(input: DiscountedPaybackInput): number | null;
+/** Input for {@link profitabilityIndex}. */
+export interface ProfitabilityIndexInput {
+    cashFlows: readonly TimedCashFlow[];
+    annualDiscountRate: number;
+    /** Default `'annual'`. */
+    compounding?: InterestCompounding;
+}
+/**
+ * PV of the positive flows ÷ PV of the outlays (positive magnitude): > 1 means value-creating at
+ * the discount rate.
+ */
+export declare function profitabilityIndex(input: ProfitabilityIndexInput): number;
+/** Input for {@link equivalentAnnualAnnuity}. */
+export interface EquivalentAnnualAnnuityInput {
+    cashFlows: readonly TimedCashFlow[];
+    annualDiscountRate: number;
+    /** Project length in years (the annuity horizon). */
+    projectLifeYears: number;
+    /** Default `'annual'`. */
+    compounding?: InterestCompounding;
+}
+/**
+ * The level annual amount whose PV over `projectLifeYears` equals the project NPV — the standard
+ * yardstick for comparing projects of unequal length. The annuity factor honors the SAME declared
+ * `compounding` convention the NPV used: it is `Σ discountFactor(rate, t, compounding)` over the
+ * integer payment years `t = 1..projectLifeYears`, so discounting the returned annuity back over
+ * the project life under that convention recovers the NPV exactly. (Under `'annual'` the sum
+ * equals the classic closed-form annuity factor `(1 − (1 + r)^−L) / r`.)
+ */
+export declare function equivalentAnnualAnnuity(input: EquivalentAnnualAnnuityInput): number;
+/** The explicit depreciation coordinates every method requires. */
+export interface DepreciationInput {
+    /** Acquisition cost (positive). */
+    cost: number;
+    /** Salvage (residual) value at the end of useful life; 0 ≤ salvage < cost. */
+    salvageValue: number;
+    /** Useful life in whole periods (≥ 1). */
+    usefulLifePeriods: number;
+    /** 1-based period being asked about. */
+    period: number;
+}
+/** Declining-balance adds its explicit rate multiplier. */
+export interface DecliningBalanceInput extends DepreciationInput {
+    /** The declining-balance factor (e.g. `1.5`); double-declining uses its own head. */
+    factor: number;
+}
+/** Straight-line: the same charge every period, `(cost − salvage) / life`. */
+export declare function straightLineDepreciation(input: DepreciationInput): number;
+/** Declining-balance charge in `period` at the explicit `factor`, floored at salvage. */
+export declare function decliningBalanceDepreciation(input: DecliningBalanceInput): number;
+/** Double-declining balance: {@link decliningBalanceDepreciation} at factor 2. */
+export declare function doubleDecliningBalanceDepreciation(input: DepreciationInput): number;
+/** Sum-of-years'-digits charge in `period`: `(cost − salvage) · remainingLife / Σ digits`. */
+export declare function sumOfYearsDigitsDepreciation(input: DepreciationInput): number;
+//# sourceMappingURL=capital-budgeting.d.ts.map

package/modules/valuation/dist/capital-budgeting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capital-budgeting.d.ts","sourceRoot":"","sources":["../src/capital-budgeting.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAIL,KAAK,mBAAmB,EAMzB,MAAM,0BAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,aAAa,EAAyB,MAAM,YAAY,CAAC;AAQvE,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IACpC,6BAA6B;IAC7B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAsBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAKhE;AAED,8FAA8F;AAC9F,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM,GAAG,IAAI,CAmBpF;AAED,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,0BAA0B;IAC1B,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,CA6BzE;AAED,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,0BAA0B;IAC1B,WAAW,CAAC,EAAE,mBAAmB,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,4BAA4B,GAAG,MAAM,CAmDnF;AAMD,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,2DAA2D;AAC3D,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;CAChB;AAuDD,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAGzE;AAED,yFAAyF;AACzF,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAiBjF;AAED,kFAAkF;AAClF,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAGnF;AAED,8FAA8F;AAC9F,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAS7E"}

package/modules/valuation/dist/capital-budgeting.js

@@ -0,0 +1,204 @@
+/**
+ * FC1 — capital budgeting and depreciation. Depreciation helpers require cost, salvage value,
+ * useful life, and period; they never infer tax rules.
+ */
+import { requireRepresentableResult, ErrorCode, InputError, assertFiniteValue, discountFactor, ensureKnownKeys, requireArgumentObject, requireFiniteFields, } from '../../core/dist/index.js';
+import { requireTimedCashFlows } from './flows.js';
+import { requireCompoundingWhenPresent } from './discounting.js';
+import { netPresentValue } from './discounting.js';
+function paybackYears(functionName, flows) {
+    const ordered = [...flows].sort((a, b) => a.timeYears - b.timeYears);
+    let cumulative = 0;
+    let previousTime = 0;
+    for (const flow of ordered) {
+        const before = cumulative;
+        cumulative += flow.amount;
+        if (before < 0 && cumulative >= 0) {
+            // Linear interpolation inside the recovering flow's interval.
+            const fraction = flow.amount === 0 ? 0 : -before / flow.amount;
+            return previousTime + (flow.timeYears - previousTime) * fraction;
+        }
+        previousTime = flow.timeYears;
+    }
+    return null; // never recovers
+}
+/**
+ * Years until cumulative cash flow first reaches zero (linear interpolation within the
+ * recovering interval), or `null` when the outlay is never recovered.
+ */
+export function paybackPeriod(input) {
+    requireArgumentObject('paybackPeriod', 'input', input);
+    ensureKnownKeys('paybackPeriod', 'input', input, ['cashFlows']);
+    requireTimedCashFlows('paybackPeriod', input.cashFlows);
+    return paybackYears('paybackPeriod', input.cashFlows);
+}
+/** {@link paybackPeriod} on DISCOUNTED flows — the recovery clock respects the time value. */
+export function discountedPaybackPeriod(input) {
+    requireArgumentObject('discountedPaybackPeriod', 'input', input);
+    ensureKnownKeys('discountedPaybackPeriod', 'input', input, [
+        'cashFlows',
+        'annualDiscountRate',
+        'compounding',
+    ]);
+    requireFiniteFields('discountedPaybackPeriod', input, ['annualDiscountRate'], {
+        exampleCall: 'discountedPaybackPeriod({ cashFlows: [{ amount: -1_000, timeYears: 0 }, { amount: 600, timeYears: 1 }, { amount: 600, timeYears: 2 }], annualDiscountRate: 0.1 })',
+    });
+    requireTimedCashFlows('discountedPaybackPeriod', input.cashFlows);
+    requireCompoundingWhenPresent('discountedPaybackPeriod', input.compounding);
+    const compounding = input.compounding ?? 'annual';
+    const discounted = input.cashFlows.map((flow) => ({
+        amount: flow.amount * discountFactor(input.annualDiscountRate, flow.timeYears, compounding),
+        timeYears: flow.timeYears,
+    }));
+    return paybackYears('discountedPaybackPeriod', discounted);
+}
+/**
+ * PV of the positive flows ÷ PV of the outlays (positive magnitude): > 1 means value-creating at
+ * the discount rate.
+ */
+export function profitabilityIndex(input) {
+    requireArgumentObject('profitabilityIndex', 'input', input);
+    ensureKnownKeys('profitabilityIndex', 'input', input, [
+        'cashFlows',
+        'annualDiscountRate',
+        'compounding',
+    ]);
+    requireFiniteFields('profitabilityIndex', input, ['annualDiscountRate'], {
+        exampleCall: 'profitabilityIndex({ cashFlows: [{ amount: -1_000, timeYears: 0 }, { amount: 700, timeYears: 1 }, { amount: 700, timeYears: 2 }], annualDiscountRate: 0.1 })',
+    });
+    requireTimedCashFlows('profitabilityIndex', input.cashFlows);
+    requireCompoundingWhenPresent('profitabilityIndex', input.compounding);
+    const compounding = input.compounding ?? 'annual';
+    let inflowPresent = 0;
+    let outlayPresent = 0;
+    for (const flow of input.cashFlows) {
+        const value = flow.amount * discountFactor(input.annualDiscountRate, flow.timeYears, compounding);
+        if (value >= 0)
+            inflowPresent += value;
+        else
+            outlayPresent += -value;
+    }
+    if (outlayPresent === 0) {
+        throw new InputError('profitabilityIndex: at least one outlay (negative flow) is required — with no investment there is no index.', { code: ErrorCode.InputOutOfRange, context: { field: 'cashFlows' } });
+    }
+    return requireRepresentableResult('profitabilityIndex', inflowPresent / outlayPresent);
+}
+/**
+ * The level annual amount whose PV over `projectLifeYears` equals the project NPV — the standard
+ * yardstick for comparing projects of unequal length. The annuity factor honors the SAME declared
+ * `compounding` convention the NPV used: it is `Σ discountFactor(rate, t, compounding)` over the
+ * integer payment years `t = 1..projectLifeYears`, so discounting the returned annuity back over
+ * the project life under that convention recovers the NPV exactly. (Under `'annual'` the sum
+ * equals the classic closed-form annuity factor `(1 − (1 + r)^−L) / r`.)
+ */
+export function equivalentAnnualAnnuity(input) {
+    requireArgumentObject('equivalentAnnualAnnuity', 'input', input);
+    ensureKnownKeys('equivalentAnnualAnnuity', 'input', input, [
+        'cashFlows',
+        'annualDiscountRate',
+        'projectLifeYears',
+        'compounding',
+    ]);
+    requireFiniteFields('equivalentAnnualAnnuity', input, ['annualDiscountRate', 'projectLifeYears'], {
+        exampleCall: 'equivalentAnnualAnnuity({ cashFlows: [{ amount: -1_000, timeYears: 0 }, { amount: 700, timeYears: 1 }], annualDiscountRate: 0.1, projectLifeYears: 1 })',
+    });
+    requireTimedCashFlows('equivalentAnnualAnnuity', input.cashFlows);
+    requireCompoundingWhenPresent('equivalentAnnualAnnuity', input.compounding);
+    // Safe integer + a practical bound (2026-08-23 review wave): this horizon drives the annuity-
+    // factor loop one year at a time, so an unsafe "integer" like 2^53 is a non-terminating loop and
+    // 1e308 is a request for effectively infinite work. 100,000 years is beyond any project's life;
+    // nothing real is refused.
+    if (!Number.isSafeInteger(input.projectLifeYears) ||
+        input.projectLifeYears < 1 ||
+        input.projectLifeYears > 100_000) {
+        throw new InputError(`equivalentAnnualAnnuity: projectLifeYears must be an integer in [1, 100_000] (annual annuity horizon). Received ${input.projectLifeYears}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'projectLifeYears' } });
+    }
+    const value = netPresentValue({
+        cashFlows: input.cashFlows,
+        annualDiscountRate: input.annualDiscountRate,
+        ...(input.compounding !== undefined ? { compounding: input.compounding } : {}),
+    });
+    // The annuity factor under the SAME convention the NPV honored — never a hardcoded annual form:
+    // Σ discountFactor(rate, t, compounding) over the integer payment years, so that
+    // EAA × Σ df(t) = NPV exactly under the declared convention. (At rate 0 every factor is 1 and
+    // the sum is projectLifeYears; under 'annual' the sum equals (1 − (1 + r)^−L) / r.)
+    const compounding = input.compounding ?? 'annual';
+    let annuityFactor = 0;
+    for (let year = 1; year <= input.projectLifeYears; year++) {
+        annuityFactor += discountFactor(input.annualDiscountRate, year, compounding);
+    }
+    const annuity = value / annuityFactor;
+    // Law 7: a finite-input overflow must never leave here as a successful non-finite value.
+    assertFiniteValue('equivalentAnnualAnnuity', annuity);
+    return annuity;
+}
+const DEPRECIATION_KEYS = ['cost', 'salvageValue', 'usefulLifePeriods', 'period'];
+function validateDepreciation(functionName, input, extraKeys = []) {
+    requireArgumentObject(functionName, 'input', input);
+    ensureKnownKeys(functionName, 'input', input, [...DEPRECIATION_KEYS, ...extraKeys]);
+    requireFiniteFields(functionName, input, ['cost', 'salvageValue', 'usefulLifePeriods', 'period'], {
+        exampleCall: `${functionName}({ cost: 10_000, salvageValue: 1_000, usefulLifePeriods: 5, period: 2 })`,
+    });
+    if (input.cost <= 0) {
+        throw new InputError(`${functionName}: cost must be > 0. Received ${input.cost}.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { field: 'cost' },
+        });
+    }
+    if (input.salvageValue < 0 || input.salvageValue >= input.cost) {
+        throw new InputError(`${functionName}: salvageValue must satisfy 0 ≤ salvageValue < cost. Received ${input.salvageValue}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'salvageValue' } });
+    }
+    // Safe integer + a practical bound (2026-08-23 review wave): `Number.isInteger(1e308)` is
+    // true, and above 2^53 a period counter stops advancing — an unsafe "integer" here is a
+    // non-terminating declining-balance loop, not a long depreciation schedule. 100,000 periods is
+    // monthly depreciation for 8,333 years; nothing real is refused.
+    if (!Number.isSafeInteger(input.usefulLifePeriods) ||
+        input.usefulLifePeriods < 1 ||
+        input.usefulLifePeriods > 100_000) {
+        throw new InputError(`${functionName}: usefulLifePeriods must be an integer in [1, 100_000]. Received ${input.usefulLifePeriods}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'usefulLifePeriods' } });
+    }
+    if (!Number.isSafeInteger(input.period) ||
+        input.period < 1 ||
+        input.period > input.usefulLifePeriods) {
+        throw new InputError(`${functionName}: period must be an integer in [1, usefulLifePeriods]. Received ${input.period}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'period' } });
+    }
+}
+/** Straight-line: the same charge every period, `(cost − salvage) / life`. */
+export function straightLineDepreciation(input) {
+    validateDepreciation('straightLineDepreciation', input);
+    return (input.cost - input.salvageValue) / input.usefulLifePeriods;
+}
+/** Declining-balance charge in `period` at the explicit `factor`, floored at salvage. */
+export function decliningBalanceDepreciation(input) {
+    validateDepreciation('decliningBalanceDepreciation', input, ['factor']);
+    if (typeof input.factor !== 'number' || !Number.isFinite(input.factor) || input.factor <= 0) {
+        throw new InputError(`decliningBalanceDepreciation: factor must be a finite number > 0 (e.g. 1.5). Received ${input.factor === null ? 'null' : String(input.factor)}.`, { code: ErrorCode.InputOutOfRange, context: { field: 'factor' } });
+    }
+    const rate = input.factor / input.usefulLifePeriods;
+    let bookValue = input.cost;
+    let charge = 0;
+    for (let currentPeriod = 1; currentPeriod <= input.period; currentPeriod++) {
+        charge = Math.min(bookValue * rate, bookValue - input.salvageValue);
+        if (charge < 0)
+            charge = 0;
+        bookValue -= charge;
+    }
+    return charge;
+}
+/** Double-declining balance: {@link decliningBalanceDepreciation} at factor 2. */
+export function doubleDecliningBalanceDepreciation(input) {
+    validateDepreciation('doubleDecliningBalanceDepreciation', input);
+    return decliningBalanceDepreciation({ ...input, factor: 2 });
+}
+/** Sum-of-years'-digits charge in `period`: `(cost − salvage) · remainingLife / Σ digits`. */
+export function sumOfYearsDigitsDepreciation(input) {
+    validateDepreciation('sumOfYearsDigitsDepreciation', input);
+    const life = input.usefulLifePeriods;
+    const digitsSum = (life * (life + 1)) / 2;
+    const remaining = life - input.period + 1;
+    // Ratio first: `remaining / digitsSum` ≤ 1, so the charge can never overflow past the
+    // depreciable base — `(base · remaining)` CAN, at near-MAX costs, and the true charge is
+    // always representable (2026-08-23 review wave).
+    return (input.cost - input.salvageValue) * (remaining / digitsSum);
+}
+//# sourceMappingURL=capital-budgeting.js.map

package/modules/valuation/dist/capital-budgeting.js.map

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

package/modules/valuation/dist/cash-flows.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@insiderfinance/totalfinance/valuation/cash-flows` — the FC1 surface as a lean subpath: discounting, rate
+ * conversion, return solvers, loans and amortization, capital budgeting and depreciation. The
+ * per-element flow guards stay package-internal; the public boundary validates collections.
+ */
+export type { TimedCashFlow, DatedCashFlow } from './flows.js';
+export * from './discounting.js';
+export * from './solvers.js';
+export * from './loans.js';
+export * from './capital-budgeting.js';
+//# sourceMappingURL=cash-flows.d.ts.map

package/modules/valuation/dist/cash-flows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cash-flows.d.ts","sourceRoot":"","sources":["../src/cash-flows.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC/D,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC"}

package/modules/valuation/dist/cash-flows.js

@@ -0,0 +1,10 @@
+/**
+ * `@insiderfinance/totalfinance/valuation/cash-flows` — the FC1 surface as a lean subpath: discounting, rate
+ * conversion, return solvers, loans and amortization, capital budgeting and depreciation. The
+ * per-element flow guards stay package-internal; the public boundary validates collections.
+ */
+export * from './discounting.js';
+export * from './solvers.js';
+export * from './loans.js';
+export * from './capital-budgeting.js';
+//# sourceMappingURL=cash-flows.js.map

package/modules/valuation/dist/cash-flows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cash-flows.js","sourceRoot":"","sources":["../src/cash-flows.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC"}

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

@@ -0,0 +1,101 @@
+/**
+ * FC2 — comparable-company (trading multiples) valuation.
+ *
+ * Required semantics (spec, frozen): the analysis RECORDS the metric definition, the period, the
+ * peer values, the weighting/aggregation method, the outlier policy, and the enterprise/equity
+ * basis — a multiple with no recorded basis is two different numbers to two different readers.
+ * The outlier policy is applied BEFORE aggregation, every excluded peer is named with the reason
+ * it was excluded, and no policy or weight is ever defaulted silently.
+ */
+/** Whether the multiple prices the whole firm or only the equity. REQUIRED — never guessed. */
+export type ComparableValuationBasis = 'enterprise' | 'equity';
+/** How the surviving peer multiples collapse into one. REQUIRED — never guessed. */
+export type ComparableAggregation = 'median' | 'mean' | 'weighted-mean';
+/** One peer observation: the name and its multiple for the SAME metric/period as the subject. */
+export interface ComparablePeer {
+    peerName: string;
+    /** The peer's multiple (e.g. EV/EBITDA of 8.5 is `8.5`). */
+    multiple: number;
+}
+/**
+ * The EXPLICIT outlier policy, applied to peer multiples BEFORE aggregation.
+ *
+ * `'interquartile-range'` excludes peers whose multiple lies outside
+ * `[Q1 − multiplier·IQR, Q3 + multiplier·IQR]`, with Q1/Q3 the standard linear-interpolation
+ * quantiles of the peer multiples. `'none'` keeps every peer — stated, not assumed.
+ */
+export type ComparableOutlierPolicy = {
+    method: 'none';
+} | {
+    method: 'interquartile-range';
+    multiplier: number;
+};
+/** Input for {@link comparableCompanyValuation}. */
+export interface ComparableCompanyValuationInput {
+    /** The metric's name (e.g. `'EV/EBITDA'`). Recorded, never inferred. */
+    metricName: string;
+    /** What the metric MEANS (e.g. `'enterprise value over trailing-twelve-month EBITDA'`). */
+    metricDefinition: string;
+    /** The period the metric covers (e.g. `'TTM 2025-Q4'`). Recorded, never inferred. */
+    period: string;
+    /** `'enterprise'` when the multiple prices the firm, `'equity'` when it prices the equity. */
+    valuationBasis: ComparableValuationBasis;
+    /** The subject company's metric amount the aggregated multiple is applied to. */
+    subjectMetricAmount: number;
+    peers: readonly ComparablePeer[];
+    aggregation: ComparableAggregation;
+    /**
+     * Peer weights, REQUIRED for (and only valid with) `'weighted-mean'`, one per peer in peer
+     * order. Each must be a finite number > 0; they need not sum to 1 — they are normalized and
+     * the normalized weights are echoed in `assumptions.weightsNormalized`.
+     */
+    weights?: readonly number[];
+    /** REQUIRED — an unstated outlier policy is a silent default. Use `{ method: 'none' }` to keep all. */
+    outlierPolicy: ComparableOutlierPolicy;
+}
+/** One peer that survived the outlier policy; `weight` present only under `'weighted-mean'`. */
+export interface ComparablePeerUsed {
+    peerName: string;
+    multiple: number;
+    /** The NORMALIZED weight applied to this peer (present only under `'weighted-mean'`). */
+    weight?: number;
+}
+/** One peer the outlier policy excluded, with the exact reason. */
+export interface ComparablePeerExcluded {
+    peerName: string;
+    multiple: number;
+    reason: string;
+}
+/** Result of {@link comparableCompanyValuation} — every recorded convention echoed. */
+export interface ComparableCompanyValuationResult {
+    diagnostics: {
+        /** One warning per excluded peer. */
+        warnings: string[];
+    };
+    /** `aggregatedMultiple × subjectMetricAmount`, on the declared `valuationBasis`. */
+    impliedValue: number;
+    aggregatedMultiple: number;
+    valuationBasis: ComparableValuationBasis;
+    metricName: string;
+    metricDefinition: string;
+    period: string;
+    /** The peers that survived the outlier policy, in input order. */
+    peersUsed: ComparablePeerUsed[];
+    /** The peers the outlier policy excluded, in input order, each with its reason. */
+    peersExcluded: ComparablePeerExcluded[];
+    aggregation: ComparableAggregation;
+    assumptions: {
+        /** The outlier policy as requested — echoed so the record is self-describing. */
+        outlierPolicy: ComparableOutlierPolicy;
+        /** Present only under `'weighted-mean'`: the normalized weights, aligned with `peersUsed`. */
+        weightsNormalized?: number[];
+    };
+}
+/**
+ * Comparable-company valuation: apply the EXPLICIT outlier policy to the peer multiples, aggregate
+ * the survivors under the declared method, and price the subject's metric on the declared
+ * enterprise/equity basis. Every excluded peer is named with the reason; the metric definition,
+ * period, basis, aggregation, policy, and normalized weights are all echoed in the result.
+ */
+export declare function comparableCompanyValuation(input: ComparableCompanyValuationInput): ComparableCompanyValuationResult;
+//# sourceMappingURL=comparable.d.ts.map

package/modules/valuation/dist/comparable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparable.d.ts","sourceRoot":"","sources":["../src/comparable.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAYH,+FAA+F;AAC/F,MAAM,MAAM,wBAAwB,GAAG,YAAY,GAAG,QAAQ,CAAC;AAE/D,oFAAoF;AACpF,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,MAAM,GAAG,eAAe,CAAC;AAExE,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,qBAAqB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,gBAAgB,EAAE,MAAM,CAAC;IACzB,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,cAAc,EAAE,wBAAwB,CAAC;IACzC,iFAAiF;IACjF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IACjC,WAAW,EAAE,qBAAqB,CAAC;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uGAAuG;IACvG,aAAa,EAAE,uBAAuB,CAAC;CACxC;AAED,gGAAgG;AAChG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uFAAuF;AACvF,MAAM,WAAW,gCAAgC;IAC/C,WAAW,EAAE;QACX,qCAAqC;QACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,wBAAwB,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,mFAAmF;IACnF,aAAa,EAAE,sBAAsB,EAAE,CAAC;IACxC,WAAW,EAAE,qBAAqB,CAAC;IACnC,WAAW,EAAE;QACX,iFAAiF;QACjF,aAAa,EAAE,uBAAuB,CAAC;QACvC,8FAA8F;QAC9F,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;KAC9B,CAAC;CACH;AA0ID;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,+BAA+B,GACrC,gCAAgC,CAsFlC"}