@insiderfinance/totalfinance 0.1.0

package/modules/valuation/dist/equity-valuation.js

@@ -0,0 +1,164 @@
+/**
+ * FC2 — equity valuation models: the dividend-discount valuation and the residual-income
+ * valuation (clean-surplus). Both are per-share, explicitly.
+ */
+import { requireRepresentableResult, ErrorCode, InputError, discountFactor, ensureKnownKeys, requireArgumentObject, requireFiniteFields, } from '../../core/dist/index.js';
+import { requireCompoundingWhenPresent } from './discounting.js';
+import { requireTimedCashFlows } from './flows.js';
+import { requireTerminalValueMethod, terminalValue, } from './corporate-primitives.js';
+/**
+ * Present value of explicit projected dividends per share plus a terminal stage. With an EMPTY
+ * projection stage and a perpetual-growth terminal (its `terminalCashFlow` being the CURRENT
+ * annual dividend), this is exactly the Gordon growth model: `D0 × (1 + g) / (r − g)`.
+ */
+export function dividendDiscountValuation(input) {
+    requireArgumentObject('dividendDiscountValuation', 'input', input);
+    ensureKnownKeys('dividendDiscountValuation', 'input', input, [
+        'projectedDividendsPerShare',
+        'annualCostOfEquity',
+        'terminalValueMethod',
+        'compounding',
+    ]);
+    requireFiniteFields('dividendDiscountValuation', input, ['annualCostOfEquity'], {
+        exampleCall: "dividendDiscountValuation({ projectedDividendsPerShare: [], annualCostOfEquity: 0.09, terminalValueMethod: { method: 'perpetual-growth', terminalCashFlow: 2, perpetualGrowthRate: 0.03 } })",
+    });
+    if (!Array.isArray(input.projectedDividendsPerShare)) {
+        throw new InputError(`dividendDiscountValuation: projectedDividendsPerShare must be an array (possibly empty for the single-stage model).`, { code: ErrorCode.InputWrongType, context: { field: 'projectedDividendsPerShare' } });
+    }
+    if (input.projectedDividendsPerShare.length > 0) {
+        requireTimedCashFlows('dividendDiscountValuation', input.projectedDividendsPerShare);
+    }
+    requireCompoundingWhenPresent('dividendDiscountValuation', input.compounding);
+    requireTerminalValueMethod('dividendDiscountValuation', input.terminalValueMethod, input.annualCostOfEquity);
+    const compounding = input.compounding ?? 'annual';
+    const rows = input.projectedDividendsPerShare.map((flow) => {
+        const factor = discountFactor(input.annualCostOfEquity, flow.timeYears, compounding);
+        return {
+            timeYears: flow.timeYears,
+            dividendPerShare: flow.amount,
+            discountFactor: factor,
+            presentValue: flow.amount * factor,
+        };
+    });
+    const projectedDividendPresentValue = rows.reduce((total, row) => total + row.presentValue, 0);
+    const horizonYears = rows.length > 0 ? rows[rows.length - 1].timeYears : 0;
+    const terminal = terminalValue({
+        terminalValueMethod: input.terminalValueMethod,
+        annualDiscountRate: input.annualCostOfEquity,
+    });
+    const terminalValuePresentValue = terminal * discountFactor(input.annualCostOfEquity, horizonYears, compounding);
+    return requireRepresentableResult('dividendDiscountValuation', {
+        diagnostics: { warnings: [] },
+        valuePerShare: projectedDividendPresentValue + terminalValuePresentValue,
+        rows,
+        projectedDividendPresentValue,
+        terminalValue: terminal,
+        terminalValuePresentValue,
+        assumptions: {
+            annualCostOfEquity: input.annualCostOfEquity,
+            compounding,
+            terminalValueMethod: input.terminalValueMethod,
+            terminalCashFlowConvention: 'final-forecast-period-flow',
+        },
+    });
+}
+/**
+ * Clean-surplus residual income: value = beginning book value + Σ PV(EPS_t − r × B_{t−1}) + PV of
+ * the stated terminal stage. Book value rolls forward as `B_t = B_{t−1} + EPS_t − DPS_t`; annual
+ * discrete discounting (the model is annual by construction).
+ */
+export function residualIncomeValuation(input) {
+    requireArgumentObject('residualIncomeValuation', 'input', input);
+    ensureKnownKeys('residualIncomeValuation', 'input', input, [
+        'beginningBookValuePerShare',
+        'annualCostOfEquity',
+        'projections',
+        'terminalResidualIncome',
+    ]);
+    requireFiniteFields('residualIncomeValuation', input, ['beginningBookValuePerShare', 'annualCostOfEquity'], {
+        exampleCall: "residualIncomeValuation({ beginningBookValuePerShare: 20, annualCostOfEquity: 0.1, projections: [{ earningsPerShare: 3, dividendsPerShare: 1 }], terminalResidualIncome: { method: 'none' } })",
+    });
+    if (!Array.isArray(input.projections) || input.projections.length === 0) {
+        throw new InputError(`residualIncomeValuation: projections must be a non-empty array of { earningsPerShare, dividendsPerShare } years.`, { code: ErrorCode.InputOutOfRange, context: { field: 'projections' } });
+    }
+    input.projections.forEach((projection, index) => {
+        requireArgumentObject('residualIncomeValuation', `projections[${index}]`, projection);
+        ensureKnownKeys('residualIncomeValuation', `projections[${index}]`, projection, [
+            'earningsPerShare',
+            'dividendsPerShare',
+        ]);
+        requireFiniteFields('residualIncomeValuation', projection, ['earningsPerShare', 'dividendsPerShare'], {
+            exampleCall: "residualIncomeValuation({ beginningBookValuePerShare: 20, annualCostOfEquity: 0.1, projections: [{ earningsPerShare: 3, dividendsPerShare: 1 }], terminalResidualIncome: { method: 'none' } })",
+        });
+    });
+    const terminal = input.terminalResidualIncome;
+    requireArgumentObject('residualIncomeValuation', 'terminalResidualIncome', terminal);
+    const terminalMethod = terminal.method;
+    if (terminalMethod === 'none') {
+        ensureKnownKeys('residualIncomeValuation', 'terminalResidualIncome', terminal, ['method']);
+    }
+    else if (terminalMethod === 'perpetuity') {
+        ensureKnownKeys('residualIncomeValuation', 'terminalResidualIncome', terminal, [
+            'method',
+            'perpetualGrowthRate',
+        ]);
+        requireFiniteFields('residualIncomeValuation', terminal, ['perpetualGrowthRate'], {
+            exampleCall: "residualIncomeValuation({ beginningBookValuePerShare: 20, annualCostOfEquity: 0.1, projections: [{ earningsPerShare: 3, dividendsPerShare: 1 }], terminalResidualIncome: { method: 'perpetuity', perpetualGrowthRate: 0 } })",
+        });
+        if (input.annualCostOfEquity <= terminal.perpetualGrowthRate) {
+            throw new InputError(`residualIncomeValuation: the terminal perpetuity requires annualCostOfEquity > perpetualGrowthRate — received cost ${input.annualCostOfEquity} against growth ${terminal.perpetualGrowthRate}.`, {
+                code: ErrorCode.InputOutOfRange,
+                context: { field: 'terminalResidualIncome.perpetualGrowthRate' },
+            });
+        }
+    }
+    else {
+        throw new InputError(`residualIncomeValuation: terminalResidualIncome.method must be 'none' | 'perpetuity'. Received ${terminalMethod === null ? 'null' : JSON.stringify(terminalMethod)}.`, { code: ErrorCode.InputInvalidEnum, context: { field: 'terminalResidualIncome.method' } });
+    }
+    const rate = input.annualCostOfEquity;
+    let book = input.beginningBookValuePerShare;
+    let residualIncomePresentValue = 0;
+    const rows = input.projections.map((projection, index) => {
+        const year = index + 1;
+        const equityCharge = rate * book;
+        const residualIncomePerShare = projection.earningsPerShare - equityCharge;
+        const presentValue = residualIncomePerShare / Math.pow(1 + rate, year);
+        const endingBook = book + projection.earningsPerShare - projection.dividendsPerShare;
+        const row = {
+            year,
+            beginningBookValuePerShare: book,
+            earningsPerShare: projection.earningsPerShare,
+            dividendsPerShare: projection.dividendsPerShare,
+            endingBookValuePerShare: endingBook,
+            equityCharge,
+            residualIncomePerShare,
+            presentValue,
+        };
+        residualIncomePresentValue += presentValue;
+        book = endingBook;
+        return row;
+    });
+    let terminalValuePresentValue = 0;
+    if (terminalMethod === 'perpetuity') {
+        const growth = terminal.perpetualGrowthRate;
+        const lastRow = rows[rows.length - 1];
+        const horizon = rows.length;
+        // The perpetuity continues the FINAL residual income, grown one year, from the horizon.
+        const terminalAtHorizon = (lastRow.residualIncomePerShare * (1 + growth)) / (rate - growth);
+        terminalValuePresentValue = terminalAtHorizon / Math.pow(1 + rate, horizon);
+    }
+    return requireRepresentableResult('residualIncomeValuation', {
+        diagnostics: { warnings: [] },
+        valuePerShare: input.beginningBookValuePerShare + residualIncomePresentValue + terminalValuePresentValue,
+        beginningBookValuePerShare: input.beginningBookValuePerShare,
+        rows,
+        residualIncomePresentValue,
+        terminalValuePresentValue,
+        assumptions: {
+            annualCostOfEquity: rate,
+            cleanSurplus: 'ending book = beginning book + earnings - dividends',
+            terminalResidualIncome: input.terminalResidualIncome,
+        },
+    });
+}
+//# sourceMappingURL=equity-valuation.js.map

package/modules/valuation/dist/equity-valuation.js.map

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

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

@@ -0,0 +1,30 @@
+/**
+ * The FROZEN cash-flow contracts (FC0, encoded with FC1 — the owner package's first slice) and
+ * their boundary guards. One monetary unit per collection; general helpers never infer a time-zero
+ * flow; duplicate times/dates aggregate deterministically without mutating input order.
+ */
+/** One cash flow at a year offset from the valuation instant (`timeYears: 0`). */
+export interface TimedCashFlow {
+    /** Positive inflow, negative outflow. */
+    amount: number;
+    /** Years from the valuation instant; `0` IS the valuation instant. */
+    timeYears: number;
+    label?: string;
+}
+/** One cash flow on a strict `YYYY-MM-DD` calendar date. */
+export interface DatedCashFlow {
+    /** Positive inflow, negative outflow. */
+    amount: number;
+    /** Strict `YYYY-MM-DD` calendar date. */
+    cashFlowDate: string;
+    label?: string;
+}
+/** Validate one {@link TimedCashFlow} element, naming its index (Law 12 closed request). */
+export declare function requireTimedCashFlow(functionName: string, flow: TimedCashFlow, index: number): void;
+/** Validate one {@link DatedCashFlow} element, naming its index (Law 12 closed request). */
+export declare function requireDatedCashFlow(functionName: string, flow: DatedCashFlow, index: number): void;
+/** Validate a non-empty timed collection, every element index-named. */
+export declare function requireTimedCashFlows(functionName: string, cashFlows: readonly TimedCashFlow[]): void;
+/** Validate a non-empty dated collection, every element index-named. */
+export declare function requireDatedCashFlows(functionName: string, cashFlows: readonly DatedCashFlow[]): void;
+//# sourceMappingURL=flows.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../src/flows.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAgBD,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,MAAM,GACZ,IAAI,CA6BN;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,MAAM,GACZ,IAAI,CAyBN;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,SAAS,aAAa,EAAE,GAClC,IAAI,CASN;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,SAAS,aAAa,EAAE,GAClC,IAAI,CASN"}

package/modules/valuation/dist/flows.js

@@ -0,0 +1,77 @@
+/**
+ * The FROZEN cash-flow contracts (FC0, encoded with FC1 — the owner package's first slice) and
+ * their boundary guards. One monetary unit per collection; general helpers never infer a time-zero
+ * flow; duplicate times/dates aggregate deterministically without mutating input order.
+ */
+import { ensureKnownKeys, ErrorCode, InputError, isoDateToEpochMs, requireArgumentArray, requireArgumentObject, } from '../../core/dist/index.js';
+const TIMED_KEYS = ['amount', 'timeYears', 'label'];
+const DATED_KEYS = ['amount', 'cashFlowDate', 'label'];
+const STRICT_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Shape via the regex, then the REAL calendar: `2025-02-30` must teach, never normalize. */
+const isCalendarDate = (value) => {
+    try {
+        isoDateToEpochMs(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Validate one {@link TimedCashFlow} element, naming its index (Law 12 closed request). */
+export function requireTimedCashFlow(functionName, flow, index) {
+    requireArgumentObject(functionName, `cashFlows[${index}]`, flow);
+    ensureKnownKeys(functionName, `cashFlows[${index}]`, flow, TIMED_KEYS);
+    if (typeof flow.amount !== 'number' || !Number.isFinite(flow.amount)) {
+        throw new InputError(`${functionName}: cashFlows[${index}].amount must be a finite number (positive inflow, negative outflow). Received ${flow.amount === null ? 'null' : typeof flow.amount}.`, { code: ErrorCode.InputWrongType, context: { field: `cashFlows[${index}].amount` } });
+    }
+    if (typeof flow.timeYears !== 'number' || !Number.isFinite(flow.timeYears)) {
+        throw new InputError(`${functionName}: cashFlows[${index}].timeYears must be a finite number of years (0 is the valuation instant). Received ${flow.timeYears === null ? 'null' : typeof flow.timeYears}.`, { code: ErrorCode.InputWrongType, context: { field: `cashFlows[${index}].timeYears` } });
+    }
+    if (flow.timeYears < 0) {
+        // Ordinary discounting is forward-looking; historical flows use the DATED forms with an
+        // explicit valuation policy — negative times are never smuggled into pricing helpers.
+        throw new InputError(`${functionName}: cashFlows[${index}].timeYears must be ≥ 0 — historical flows belong in the dated form (datedNetPresentValue / datedInternalRateOfReturn) with an explicit asOf. Received ${flow.timeYears}.`, { code: ErrorCode.InputOutOfRange, context: { field: `cashFlows[${index}].timeYears` } });
+    }
+    if (flow.label !== undefined && typeof flow.label !== 'string') {
+        throw new InputError(`${functionName}: cashFlows[${index}].label must be a string when provided. Received ${flow.label === null ? 'null' : typeof flow.label}.`, { code: ErrorCode.InputWrongType, context: { field: `cashFlows[${index}].label` } });
+    }
+}
+/** Validate one {@link DatedCashFlow} element, naming its index (Law 12 closed request). */
+export function requireDatedCashFlow(functionName, flow, index) {
+    requireArgumentObject(functionName, `cashFlows[${index}]`, flow);
+    ensureKnownKeys(functionName, `cashFlows[${index}]`, flow, DATED_KEYS);
+    if (typeof flow.amount !== 'number' || !Number.isFinite(flow.amount)) {
+        throw new InputError(`${functionName}: cashFlows[${index}].amount must be a finite number (positive inflow, negative outflow). Received ${flow.amount === null ? 'null' : typeof flow.amount}.`, { code: ErrorCode.InputWrongType, context: { field: `cashFlows[${index}].amount` } });
+    }
+    if (typeof flow.cashFlowDate !== 'string' ||
+        !STRICT_DATE.test(flow.cashFlowDate) ||
+        !isCalendarDate(flow.cashFlowDate)) {
+        throw new InputError(`${functionName}: cashFlows[${index}].cashFlowDate must be a strict YYYY-MM-DD calendar date. Received ${flow.cashFlowDate === null ? 'null' : JSON.stringify(flow.cashFlowDate)}.`, { code: ErrorCode.InputWrongType, context: { field: `cashFlows[${index}].cashFlowDate` } });
+    }
+    if (flow.label !== undefined && typeof flow.label !== 'string') {
+        throw new InputError(`${functionName}: cashFlows[${index}].label must be a string when provided. Received ${flow.label === null ? 'null' : typeof flow.label}.`, { code: ErrorCode.InputWrongType, context: { field: `cashFlows[${index}].label` } });
+    }
+}
+/** Validate a non-empty timed collection, every element index-named. */
+export function requireTimedCashFlows(functionName, cashFlows) {
+    requireArgumentArray(functionName, 'cashFlows', cashFlows);
+    if (cashFlows.length === 0) {
+        throw new InputError(`${functionName}: cashFlows must not be empty.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { field: 'cashFlows' },
+        });
+    }
+    cashFlows.forEach((flow, index) => requireTimedCashFlow(functionName, flow, index));
+}
+/** Validate a non-empty dated collection, every element index-named. */
+export function requireDatedCashFlows(functionName, cashFlows) {
+    requireArgumentArray(functionName, 'cashFlows', cashFlows);
+    if (cashFlows.length === 0) {
+        throw new InputError(`${functionName}: cashFlows must not be empty.`, {
+            code: ErrorCode.InputOutOfRange,
+            context: { field: 'cashFlows' },
+        });
+    }
+    cashFlows.forEach((flow, index) => requireDatedCashFlow(functionName, flow, index));
+}
+//# sourceMappingURL=flows.js.map

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

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

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

@@ -0,0 +1,205 @@
+/**
+ * FC2 — forecasting compositions. No forecast extrapolates history by default: every driver is
+ * explicit, can vary by period, and is echoed back. The three-statement projection reconciles by
+ * CONSTRUCTION (the algebra is written out at the balance roll below), and the balancing item is
+ * named — cash — never a plug hidden inside cash or debt.
+ */
+import type { FinancialStatements } from '../../fundamentals/dist/index.js';
+import { type DiscountedCashFlowInput, type DiscountedCashFlowResult } from './discounted-cash-flow.js';
+/** An explicit per-period amount, or an explicit fraction of that period's revenue. */
+export type AmountDriver = {
+    amount: number;
+} | {
+    fractionOfRevenue: number;
+};
+/** Revenue is stated directly or grown EXPLICITLY from the prior period — never extrapolated. */
+export type RevenueDriver = {
+    amount: number;
+} | {
+    growthRate: number;
+};
+/** One forecast period's explicit drivers. */
+export interface OperatingForecastPeriod {
+    periodLabel: string;
+    revenue: RevenueDriver;
+    /** Operating income as a fraction of revenue. */
+    operatingMargin: number;
+    taxRate: number;
+    depreciationAndAmortization: AmountDriver;
+    capitalExpenditure: AmountDriver;
+    increaseInNetWorkingCapital: AmountDriver;
+    /** Enables the FCFE column (with interestExpense). */
+    netBorrowing?: number;
+    /** Enables net income and (with netBorrowing) FCFE. */
+    interestExpense?: number;
+}
+/** Input for {@link operatingForecast}. */
+export interface OperatingForecastInput {
+    /** The revenue base the first growth-driven period grows FROM (the last historical revenue). */
+    baseRevenue: number;
+    periods: readonly OperatingForecastPeriod[];
+}
+/** One forecast row — every derived figure alongside the drivers that produced it. */
+export interface OperatingForecastRow {
+    periodLabel: string;
+    revenue: number;
+    operatingIncome: number;
+    taxes: number;
+    interestExpense?: number;
+    netIncome?: number;
+    netIncomeAbsentReason?: string;
+    depreciationAndAmortization: number;
+    capitalExpenditure: number;
+    increaseInNetWorkingCapital: number;
+    freeCashFlowToFirm: number;
+    freeCashFlowToEquity?: number;
+    freeCashFlowToEquityAbsentReason?: string;
+}
+/** Result of {@link operatingForecast}. */
+export interface OperatingForecastResult {
+    diagnostics: {
+        /** One warning per row output disabled by an absent driver. */
+        warnings: string[];
+    };
+    rows: OperatingForecastRow[];
+    /** The drivers, echoed verbatim per period. */
+    assumptions: {
+        baseRevenue: number;
+        periods: readonly OperatingForecastPeriod[];
+    };
+}
+/**
+ * Revenue, margins, taxes, working capital, capital expenditure, depreciation, and the resulting
+ * FCFF (and FCFE where the financing drivers are supplied) — from EXPLICIT per-period drivers.
+ * FCFF taxes operating income at the period's rate (the {@link freeCashFlowToFirm} primitive);
+ * net income and FCFE additionally need the period's interest expense, stated, never assumed zero.
+ */
+export declare function operatingForecast(input: OperatingForecastInput): OperatingForecastResult;
+/** One projected period's explicit drivers — operating AND balance-sheet. */
+export interface StatementProjectionPeriod {
+    periodLabel: string;
+    revenue: RevenueDriver;
+    operatingMargin: number;
+    taxRate: number;
+    /** Explicit financing cost for the period. */
+    interestExpense: number;
+    depreciationAndAmortization: AmountDriver;
+    capitalExpenditure: AmountDriver;
+    /** Operating working-capital balances (cash is NOT working capital here — it is the balancer). */
+    accountsReceivable: AmountDriver;
+    inventory: AmountDriver;
+    accountsPayable: AmountDriver;
+    /** New borrowing minus repayments. */
+    netBorrowing: number;
+    dividendsPaid: number;
+}
+/** One projected period's three articulated statements (a closed forecast contract). */
+export interface ProjectedStatements {
+    periodLabel: string;
+    income: {
+        revenue: number;
+        operatingIncome: number;
+        interestExpense: number;
+        pretaxIncome: number;
+        incomeTaxExpense: number;
+        netIncome: number;
+    };
+    balance: {
+        cashAndCashEquivalents: number;
+        accountsReceivable: number;
+        inventory: number;
+        propertyPlantEquipmentNet: number;
+        otherAssets: number;
+        totalAssets: number;
+        accountsPayable: number;
+        totalDebt: number;
+        otherLiabilities: number;
+        totalLiabilities: number;
+        totalEquity: number;
+    };
+    cashFlow: {
+        netIncome: number;
+        depreciationAndAmortization: number;
+        increaseInNetWorkingCapital: number;
+        operatingCashFlow: number;
+        capitalExpenditure: number;
+        investingCashFlow: number;
+        netBorrowing: number;
+        dividendsPaid: number;
+        financingCashFlow: number;
+        netChangeInCash: number;
+    };
+    freeCashFlowToFirm: number;
+    freeCashFlowToEquity: number;
+}
+/** Input for {@link projectFinancialStatements}. */
+export interface ProjectStatementsInput {
+    /** The typed historical anchor — beginning balances come from HERE, not from an assumption. */
+    baseStatements: FinancialStatements;
+    periods: readonly StatementProjectionPeriod[];
+}
+/** Result of {@link projectFinancialStatements}. */
+export interface ProjectStatementsResult {
+    diagnostics: {
+        /** Any period whose identity residual exceeds floating-point dust. */
+        warnings: string[];
+    };
+    statements: ProjectedStatements[];
+    /**
+     * The named balancing item. CASH absorbs the residual of the articulated statements — the
+     * identity `assets = liabilities + equity` then holds by construction, and the proof is the
+     * per-period `identityDifference` (floating-point dust, gated in tests).
+     */
+    balancingItem: 'cash';
+    reconciliation: Array<{
+        periodLabel: string;
+        identityDifference: number;
+    }>;
+    assumptions: {
+        periods: readonly StatementProjectionPeriod[];
+    };
+}
+/**
+ * A three-statement projection from a typed historical base and explicit per-period drivers.
+ *
+ * The articulation, written out (Δ = period change):
+ *
+ *     ΔtotalAssets = Δcash + ΔAR + Δinventory + ΔPPE
+ *                  = (CFO + CFI + CFF) + ΔAR + Δinventory + (capex − D&A)
+ *                  = netIncome + ΔAP + netBorrowing − dividends
+ *     ΔtotalLiabilities + Δequity = ΔAP + netBorrowing + netIncome − dividends
+ *
+ * — identical, so the balance sheet ties EXACTLY with cash as the named balancer. Other assets and
+ * other liabilities are carried CONSTANT from the base (disclosed), never grown silently.
+ */
+export declare function projectFinancialStatements(input: ProjectStatementsInput): ProjectStatementsResult;
+/** Input for {@link discountedCashFlowFromStatements}. */
+export interface DiscountedCashFlowFromStatementsInput {
+    /** The statement projection (see {@link projectFinancialStatements}). */
+    projection: ProjectStatementsInput;
+    /** Everything the direct DCF needs EXCEPT the flows — those come from the projection. */
+    valuation: Omit<DiscountedCashFlowInput, 'projectedCashFlows'>;
+}
+/** Result of {@link discountedCashFlowFromStatements}. */
+export interface DiscountedCashFlowFromStatementsResult {
+    assumptions: {
+        /** Which flow column fed the valuation, decided by the basis — never relabeled. */
+        cashFlowsUsed: 'freeCashFlowToFirm' | 'freeCashFlowToEquity';
+        projectedPeriodCount: number;
+    };
+    diagnostics: {
+        warnings: string[];
+    };
+    projection: ProjectStatementsResult;
+    /** Which flow column fed the valuation, decided by the valuation basis — never relabeled. */
+    cashFlowsUsed: 'freeCashFlowToFirm' | 'freeCashFlowToEquity';
+    valuation: DiscountedCashFlowResult;
+}
+/**
+ * The composition the acceptance law names: project the statements, take the emitted FCFF (firm
+ * basis) or FCFE (equity basis) at whole-year offsets, and hand them to the direct
+ * {@link discountedCashFlow} — so the composed valuation IS a direct valuation of the projected
+ * flows, reproducible by construction.
+ */
+export declare function discountedCashFlowFromStatements(input: DiscountedCashFlowFromStatementsInput): DiscountedCashFlowFromStatementsResult;
+//# sourceMappingURL=forecasting.d.ts.map

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

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