@insiderfinance/totalfinance 0.1.0

package/modules/valuation/etc/valuation.api.md

@@ -0,0 +1,162 @@
+# @insiderfinance/totalfinance/valuation — public API
+
+> Generated by `tools/api-report`. Do not edit by hand. Run `pnpm api:update` after intentional
+> public API changes; `pnpm api:check` fails on undocumented drift.
+
+## Exports (155)
+
+- `const datedInternalRateOfReturn`: ((input: DatedInternalRateOfReturnInput) => number | null) & { explain: (input: DatedInternalRateOfReturnInput) => InternalRateOfReturnReport; }
+- `const internalRateOfReturn`: ((input: InternalRateOfReturnInput) => number | null) & { explain: (input: InternalRateOfReturnInput) => InternalRateOfReturnReport; }
+- `function adjustedPresentValue`: (input: AdjustedPresentValueInput) => AdjustedPresentValueResult
+- `function afterTaxCostOfDebt`: (input: AfterTaxCostOfDebtInput) => number
+- `function amortizationSchedule`: (input: AmortizationScheduleInput) => AmortizationScheduleResult
+- `function annuityPayment`: (input: LoanTermsInput) => number
+- `function capitalAssetPricingExpectedReturn`: (input: CapitalAssetPricingInput) => number
+- `function comparableCompanyValuation`: (input: ComparableCompanyValuationInput) => ComparableCompanyValuationResult
+- `function costOfEquity`: (input: CostOfEquityInput) => number
+- `function cumulativeLoanInterest`: (input: LoanRangeInput) => number
+- `function cumulativeLoanPrincipal`: (input: LoanRangeInput) => number
+- `function datedNetPresentValue`: (input: DatedNetPresentValueInput) => number
+- `function decliningBalanceDepreciation`: (input: DecliningBalanceInput) => number
+- `function discountCashFlows`: (input: DiscountCashFlowsInput) => { rows: DiscountedCashFlowRow[]; presentValueTotal: number; }
+- `function discountedCashFlow`: (input: DiscountedCashFlowInput) => DiscountedCashFlowResult
+- `function discountedCashFlowFromStatements`: (input: DiscountedCashFlowFromStatementsInput) => DiscountedCashFlowFromStatementsResult
+- `function discountedCashFlowScenarioAnalysis`: (input: ScenarioAnalysisInput) => ScenarioAnalysisResult
+- `function discountedCashFlowSensitivityTable`: (input: SensitivityTableInput) => SensitivityTableResult
+- `function discountedPaybackPeriod`: (input: DiscountedPaybackInput) => number | null
+- `function dividendDiscountValuation`: (input: DividendDiscountInput) => DividendDiscountResult
+- `function doubleDecliningBalanceDepreciation`: (input: DepreciationInput) => number
+- `function effectiveAnnualRate`: (input: EffectiveAnnualRateInput) => number
+- `function enterpriseToEquityValue`: (input: EnterpriseToEquityValueInput) => number
+- `function equivalentAnnualAnnuity`: (input: EquivalentAnnualAnnuityInput) => number
+- `function equivalentInterestRate`: (input: EquivalentInterestRateInput) => number
+- `function freeCashFlowToEquity`: (input: FreeCashFlowToEquityInput) => number
+- `function freeCashFlowToFirm`: (input: FreeCashFlowToFirmInput) => number
+- `function futureValue`: (input: FutureValueInput) => number
+- `function leveragedBuyoutAnalysis`: (input: LeveragedBuyoutAnalysisInput) => LeveragedBuyoutAnalysisResult
+- `function loanInterestPayment`: (input: LoanPeriodInput) => number
+- `function loanNumberOfPeriods`: (input: LoanNumberOfPeriodsInput) => number
+- `function loanPeriodicInterestRate`: (input: LoanPeriodicInterestRateInput) => number
+- `function loanPrincipalPayment`: (input: LoanPeriodInput) => number
+- `function modifiedInternalRateOfReturn`: (input: ModifiedInternalRateOfReturnInput) => number
+- `function netPresentValue`: (input: NetPresentValueInput) => number
+- `function nominalAnnualRate`: (input: NominalAnnualRateInput) => number
+- `function operatingForecast`: (input: OperatingForecastInput) => OperatingForecastResult
+- `function paybackPeriod`: (input: PaybackInput) => number | null
+- `function presentValue`: (input: PresentValueInput) => number
+- `function probabilisticDiscountedCashFlow`: (input: ProbabilisticDiscountedCashFlowInput) => ProbabilisticDiscountedCashFlowResult
+- `function profitabilityIndex`: (input: ProfitabilityIndexInput) => number
+- `function projectFinancialStatements`: (input: ProjectStatementsInput) => ProjectStatementsResult
+- `function requireCompoundingWhenPresent`: (functionName: string, compounding: unknown) => asserts compounding is InterestCompounding | undefined
+- `function requireDayCountWhenPresent`: (functionName: string, dayCount: unknown) => asserts dayCount is DayCount | undefined
+- `function residualIncomeValuation`: (input: ResidualIncomeInput) => ResidualIncomeResult
+- `function reverseDiscountedCashFlow`: (input: ReverseDiscountedCashFlowInput) => ReverseDiscountedCashFlowResult
+- `function straightLineDepreciation`: (input: DepreciationInput) => number
+- `function sumOfYearsDigitsDepreciation`: (input: DepreciationInput) => number
+- `function terminalValue`: (input: TerminalValueInput) => number
+- `function weightedAverageCostOfCapital`: (input: WeightedAverageCostOfCapitalInput) => WeightedAverageCostOfCapitalResult
+- `interface AdjustedPresentValueInput`: AdjustedPresentValueInput
+- `interface AdjustedPresentValueResult`: AdjustedPresentValueResult
+- `interface AfterTaxCostOfDebtInput`: AfterTaxCostOfDebtInput
+- `interface AmortizationRow`: AmortizationRow
+- `interface AmortizationScheduleInput`: AmortizationScheduleInput
+- `interface AmortizationScheduleResult`: AmortizationScheduleResult
+- `interface CapitalAssetPricingInput`: CapitalAssetPricingInput
+- `interface CapitalComponent`: CapitalComponent
+- `interface ComparableCompanyValuationInput`: ComparableCompanyValuationInput
+- `interface ComparableCompanyValuationResult`: ComparableCompanyValuationResult
+- `interface ComparablePeer`: ComparablePeer
+- `interface ComparablePeerExcluded`: ComparablePeerExcluded
+- `interface ComparablePeerUsed`: ComparablePeerUsed
+- `interface DatedCashFlow`: DatedCashFlow
+- `interface DatedInternalRateOfReturnInput`: DatedInternalRateOfReturnInput
+- `interface DatedNetPresentValueInput`: DatedNetPresentValueInput
+- `interface DecliningBalanceInput`: DecliningBalanceInput
+- `interface DepreciationInput`: DepreciationInput
+- `interface DiscountCashFlowsInput`: DiscountCashFlowsInput
+- `interface DiscountedCashFlowAssumptions`: DiscountedCashFlowAssumptions
+- `interface DiscountedCashFlowCommonResult`: DiscountedCashFlowCommonResult
+- `interface DiscountedCashFlowDiagnostics`: DiscountedCashFlowDiagnostics
+- `interface DiscountedCashFlowFromStatementsInput`: DiscountedCashFlowFromStatementsInput
+- `interface DiscountedCashFlowFromStatementsResult`: DiscountedCashFlowFromStatementsResult
+- `interface DiscountedCashFlowInput`: DiscountedCashFlowInput
+- `interface DiscountedCashFlowRow`: DiscountedCashFlowRow
+- `interface DiscountedCashFlowScenario`: DiscountedCashFlowScenario
+- `interface DiscountedPaybackInput`: DiscountedPaybackInput
+- `interface DiscountedProjectedCashFlowRow`: DiscountedProjectedCashFlowRow
+- `interface DividendDiscountInput`: DividendDiscountInput
+- `interface DividendDiscountResult`: DividendDiscountResult
+- `interface EffectiveAnnualRateInput`: EffectiveAnnualRateInput
+- `interface EnterpriseToEquityBridge`: EnterpriseToEquityBridge
+- `interface EnterpriseToEquityValueInput`: EnterpriseToEquityValueInput
+- `interface EquivalentAnnualAnnuityInput`: EquivalentAnnualAnnuityInput
+- `interface EquivalentInterestRateInput`: EquivalentInterestRateInput
+- `interface FinancingSideEffect`: FinancingSideEffect
+- `interface FinancingSideEffectValue`: FinancingSideEffectValue
+- `interface FreeCashFlowToEquityInput`: FreeCashFlowToEquityInput
+- `interface FreeCashFlowToFirmInput`: FreeCashFlowToFirmInput
+- `interface FutureValueInput`: FutureValueInput
+- `interface InternalRateOfReturnInput`: InternalRateOfReturnInput
+- `interface InternalRateOfReturnReport`: InternalRateOfReturnReport
+- `interface InternalRateRoot`: InternalRateRoot
+- `interface LeveragedBuyoutAnalysisInput`: LeveragedBuyoutAnalysisInput
+- `interface LeveragedBuyoutAnalysisResult`: LeveragedBuyoutAnalysisResult
+- `interface LeveragedBuyoutAnnualScheduleRow`: LeveragedBuyoutAnnualScheduleRow
+- `interface LeveragedBuyoutDebtScheduleRow`: LeveragedBuyoutDebtScheduleRow
+- `interface LeveragedBuyoutDebtTrancheInput`: LeveragedBuyoutDebtTrancheInput
+- `interface LeveragedBuyoutExitBridge`: LeveragedBuyoutExitBridge
+- `interface LeveragedBuyoutExitInput`: LeveragedBuyoutExitInput
+- `interface LeveragedBuyoutOperatingYearInput`: LeveragedBuyoutOperatingYearInput
+- `interface LeveragedBuyoutSourcesAndUses`: LeveragedBuyoutSourcesAndUses
+- `interface LeveragedBuyoutSourcesInput`: LeveragedBuyoutSourcesInput
+- `interface LeveragedBuyoutTransactionInput`: LeveragedBuyoutTransactionInput
+- `interface LoanNumberOfPeriodsInput`: LoanNumberOfPeriodsInput
+- `interface LoanPeriodicInterestRateInput`: LoanPeriodicInterestRateInput
+- `interface LoanPeriodInput`: LoanPeriodInput
+- `interface LoanRangeInput`: LoanRangeInput
+- `interface LoanTermsInput`: LoanTermsInput
+- `interface ModifiedInternalRateOfReturnInput`: ModifiedInternalRateOfReturnInput
+- `interface NetPresentValueInput`: NetPresentValueInput
+- `interface NominalAnnualRateInput`: NominalAnnualRateInput
+- `interface OperatingForecastInput`: OperatingForecastInput
+- `interface OperatingForecastPeriod`: OperatingForecastPeriod
+- `interface OperatingForecastResult`: OperatingForecastResult
+- `interface OperatingForecastRow`: OperatingForecastRow
+- `interface PaybackInput`: PaybackInput
+- `interface PresentValueInput`: PresentValueInput
+- `interface ProbabilisticDiscountedCashFlowInput`: ProbabilisticDiscountedCashFlowInput
+- `interface ProbabilisticDiscountedCashFlowResult`: ProbabilisticDiscountedCashFlowResult
+- `interface ProfitabilityIndexInput`: ProfitabilityIndexInput
+- `interface ProjectedStatements`: ProjectedStatements
+- `interface ProjectStatementsInput`: ProjectStatementsInput
+- `interface ProjectStatementsResult`: ProjectStatementsResult
+- `interface RandomizedVariable`: RandomizedVariable
+- `interface ResidualIncomeInput`: ResidualIncomeInput
+- `interface ResidualIncomeProjection`: ResidualIncomeProjection
+- `interface ResidualIncomeResult`: ResidualIncomeResult
+- `interface ReverseDiscountedCashFlowInput`: ReverseDiscountedCashFlowInput
+- `interface ReverseDiscountedCashFlowResult`: ReverseDiscountedCashFlowResult
+- `interface ScenarioAnalysisInput`: ScenarioAnalysisInput
+- `interface ScenarioAnalysisResult`: ScenarioAnalysisResult
+- `interface SensitivityAxis`: SensitivityAxis
+- `interface SensitivityTableInput`: SensitivityTableInput
+- `interface SensitivityTableResult`: SensitivityTableResult
+- `interface StatementProjectionPeriod`: StatementProjectionPeriod
+- `interface TerminalValueInput`: TerminalValueInput
+- `interface TimedCashFlow`: TimedCashFlow
+- `interface ValuationProvenance`: ValuationProvenance
+- `interface WeightedAverageCostOfCapitalInput`: WeightedAverageCostOfCapitalInput
+- `interface WeightedAverageCostOfCapitalResult`: WeightedAverageCostOfCapitalResult
+- `type AmountDriver`: AmountDriver
+- `type ComparableAggregation`: ComparableAggregation
+- `type ComparableOutlierPolicy`: ComparableOutlierPolicy
+- `type ComparableValuationBasis`: ComparableValuationBasis
+- `type CostOfEquityInput`: CostOfEquityInput
+- `type DiscountedCashFlowResult`: DiscountedCashFlowResult
+- `type MarginalDistribution`: MarginalDistribution
+- `type PaymentTiming`: PaymentTiming
+- `type ProjectedCashFlow`: ProjectedCashFlow
+- `type ProjectedCashFlowSchedule`: ProjectedCashFlowSchedule
+- `type RevenueDriver`: RevenueDriver
+- `type ReverseDiscountedCashFlowTarget`: ReverseDiscountedCashFlowTarget
+- `type TerminalValueMethod`: TerminalValueMethod

package/modules/valuation/src/adjusted-present-value.ts

@@ -0,0 +1,181 @@
+/**
+ * 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,
+  type InterestCompounding,
+  discountFactor,
+  ensureKnownKeys,
+  requireArgumentArray,
+  requireArgumentObject,
+  requireFiniteFields,
+} from '@totalfinance/core';
+import { type TimedCashFlow, requireTimedCashFlows } from './flows.js';
+import { requireCompoundingWhenPresent } from './discounting.js';
+
+/** One financing side effect: a labeled stream discounted at ITS OWN rate. */
+export interface FinancingSideEffect {
+  /** What this side effect IS (e.g. `'interest tax shield'`, `'issuance costs'`). */
+  label: string;
+  cashFlows: readonly TimedCashFlow[];
+  /** Annual rate (decimal) reflecting THIS side effect's risk — never inherited silently. */
+  annualDiscountRate: number;
+}
+
+/** Input for {@link adjustedPresentValue}. */
+export interface AdjustedPresentValueInput {
+  /** The unlevered (all-equity) operating cash flows, `timeYears: 0` being the valuation instant. */
+  unleveredCashFlows: readonly TimedCashFlow[];
+  /** Annual rate (decimal, > −1) for the UNLEVERED operating flows. */
+  unleveredCostOfCapital: number;
+  /** May be empty — "no side effects" is an explicit statement, not an omission. */
+  financingSideEffects: readonly FinancingSideEffect[];
+  /** Default `'annual'` — documented and echoed in `assumptions.compounding`. */
+  compounding?: InterestCompounding;
+}
+
+/** One side effect echoed with its present value — the decomposition the method exists for. */
+export interface FinancingSideEffectValue {
+  label: string;
+  presentValue: number;
+  annualDiscountRate: number;
+}
+
+/** Result of {@link adjustedPresentValue}: the decomposition plus the echoed assumptions. */
+export interface AdjustedPresentValueResult {
+  diagnostics: { warnings: string[] };
+  /** `unleveredValue + Σ side-effect present values`. */
+  adjustedPresentValue: number;
+  /** Present value of the unlevered operating flows at `unleveredCostOfCapital`. */
+  unleveredValue: number;
+  /** Each side effect's present value at ITS OWN rate, in input order. */
+  financingSideEffects: FinancingSideEffectValue[];
+  assumptions: {
+    unleveredCostOfCapital: number;
+    /** The one compounding convention every leg was discounted under. */
+    compounding: InterestCompounding;
+    sideEffectCount: number;
+  };
+}
+
+const INPUT_KEYS = [
+  'unleveredCashFlows',
+  'unleveredCostOfCapital',
+  'financingSideEffects',
+  'compounding',
+] as const;
+
+const SIDE_EFFECT_KEYS = ['label', 'cashFlows', 'annualDiscountRate'] as const;
+
+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: string, field: string, rate: number): void {
+  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: readonly TimedCashFlow[],
+  annualRate: number,
+  compounding: InterestCompounding,
+): number {
+  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: AdjustedPresentValueInput): AdjustedPresentValueResult {
+  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: FinancingSideEffectValue[] = 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,
+    },
+  });
+}

package/modules/valuation/src/capital-budgeting.ts

@@ -0,0 +1,329 @@
+/**
+ * FC1 — capital budgeting and depreciation. Depreciation helpers require cost, salvage value,
+ * useful life, and period; they never infer tax rules.
+ */
+
+import {
+  requireRepresentableResult,
+  ErrorCode,
+  InputError,
+  type InterestCompounding,
+  assertFiniteValue,
+  discountFactor,
+  ensureKnownKeys,
+  requireArgumentObject,
+  requireFiniteFields,
+} from '@totalfinance/core';
+import { type TimedCashFlow, requireTimedCashFlows } from './flows.js';
+import { requireCompoundingWhenPresent } from './discounting.js';
+import { netPresentValue } from './discounting.js';
+
+// ---------------------------------------------------------------------------------------------------
+// Payback and project comparison
+// ---------------------------------------------------------------------------------------------------
+
+/** 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;
+}
+
+function paybackYears(
+  functionName: string,
+  flows: readonly { amount: number; timeYears: number }[],
+): number | null {
+  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: PaybackInput): number | null {
+  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: DiscountedPaybackInput): number | null {
+  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);
+}
+
+/** 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 function profitabilityIndex(input: ProfitabilityIndexInput): number {
+  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);
+}
+
+/** 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 function equivalentAnnualAnnuity(input: EquivalentAnnualAnnuityInput): number {
+  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;
+}
+
+// ---------------------------------------------------------------------------------------------------
+// Depreciation — cost, salvage, life, period; never inferred tax rules
+// ---------------------------------------------------------------------------------------------------
+
+/** 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;
+}
+
+const DEPRECIATION_KEYS = ['cost', 'salvageValue', 'usefulLifePeriods', 'period'] as const;
+
+/** 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;
+}
+
+function validateDepreciation(
+  functionName: string,
+  input: DepreciationInput,
+  extraKeys: readonly string[] = [],
+): void {
+  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: DepreciationInput): number {
+  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: DecliningBalanceInput): number {
+  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: DepreciationInput): number {
+  validateDepreciation('doubleDecliningBalanceDepreciation', input);
+  return decliningBalanceDepreciation({ ...input, factor: 2 });
+}
+
+/** Sum-of-years'-digits charge in `period`: `(cost − salvage) · remainingLife / Σ digits`. */
+export function sumOfYearsDigitsDepreciation(input: DepreciationInput): number {
+  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);
+}