Phase 4: Implement DCF model builder

[DecisionNerd]

Summary

Build a DCF model on top of validated financial datasets.

Part of #40.

Scope

• Define required inputs and diagnostics for unlevered free cash flow.
• Support terminal value, discounting, and enterprise-to-equity bridge concepts.
• Produce export-ready model output.

Acceptance Criteria

• DCF builder consumes validated datasets.
• Required missing inputs emit diagnostics.
• Output is testable through shared model-output structures.

[Whatsonyourmind]

A few correctness guards worth baking into the diagnostics — these are the usual ways a DCF silently returns a wrong number:

Terminal value: with Gordon, TV = (next-year FCF) / (WACC − g). If g ≥ WACC the denominator goes non-positive and TV blows up or flips negative, so emit a hard error there, and warn when g exceeds long-run nominal GDP (~3-4%), since nothing outgrows the economy forever.

Discounting: cash arrives through the year, not at year-end, so use mid-period factors 1/(1+WACC)^(t−0.5) on the explicit FCFs to avoid systematic over-discounting.

Equity bridge: equity = EV − net debt − minority interest − preferred + associates/non-operating. Net debt already nets cash; minority interest comes out because EV is 100%-consolidated but equity holders don't own that slice.

Consistency check: discount unlevered FCF at WACC and keep interest out of the cash flows — the tax shield lives in WACC, so including both double-counts it.