Skip to content

"Vibe-Trading: Your Personal Trading Agent"

91.4 KB
Raw Blame
"""Private-markets fund mathematics on irregular cash flows.

This module is the analytics half of the asset spine: :mod:`src.entities.cashflow`
carries dated, signed, single-currency movements, and everything here turns such
a series into the numbers an LP or a fund controller actually reports.

Three things are deliberate.

**Nothing takes a bare list of floats.** Every public entry point takes a
:class:`~src.entities.cashflow.CashFlowSeries`. A list of floats loses the dates
(so an IRR silently becomes an equal-period IRR), loses the currency (so two
books get summed), and loses the kind (so a NAV mark gets added to realised
cash). All three were real defects; requiring the series makes them unstatable.

**A valuation is not cash.** Terminal NAV belongs in a fund IRR and in TVPI, and
must stay out of DPI. The ``valuations`` policy on :func:`xirr` and the separate
:func:`residual_value` keep that boundary explicit instead of leaving it to the
caller's filtering.

**No garbage roots.** :func:`xirr` refuses a series with no sign change rather
than returning whatever a Newton iteration wandered into, verifies the root it
does return, and exposes :func:`xirr_all` because a fund with recallable
distributions genuinely can have several. See :class:`XIRRError`.

Sign convention is inherited unchanged from the spine: ``amount > 0`` is cash
into the holder, so contributions are negative and distributions positive.
Functions that report a magnitude (``paid_in_capital``, ``distributed_capital``)
return a positive number and say so.
"""

from __future__ import annotations

import datetime as _dt
import math
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from types import MappingProxyType

import numpy as np
import pandas as pd
from scipy.optimize import brentq, newton

from src.entities.cashflow import CashFlow, CashFlowSeries
from src.entities.models import normalize_date

__all__ = [
    "CONTRIBUTION_KINDS",
    "DISTRIBUTION_KINDS",
    "VALUATION_POLICIES",
    "DEFAULT_VALUATION_POLICY",
    "DEFAULT_DAYS_PER_YEAR",
    "DEFAULT_RATE_BOUNDS",
    "DEFAULT_GRID_POINTS",
    "PREFERRED_COMPOUNDING",
    "DEFAULT_PREFERRED_COMPOUNDING",
    "TIER_RETURN_OF_CAPITAL",
    "TIER_PREFERRED_RETURN",
    "TIER_CATCH_UP",
    "TIER_CARRY_SPLIT",
    "XIRRError",
    "NoSignChangeError",
    "XIRRConvergenceError",
    "FundMultiples",
    "WaterfallTier",
    "WaterfallResult",
    "npv",
    "xirr",
    "xirr_all",
    "paid_in_capital",
    "distributed_capital",
    "residual_value",
    "dpi",
    "rvpi",
    "tvpi",
    "moic",
    "fund_multiples",
    "preferred_return_amount",
    "waterfall_split",
    "european_waterfall",
    "PMEPlusResult",
    "ks_pme",
    "pme_plus",
    "direct_alpha",
    "AmericanWaterfallResult",
    "american_waterfall",
    "ClawbackResult",
    "gp_clawback",
]

#: Kinds treated as capital going into the fund. A parameter everywhere it is
#: used -- a fund that charges management fees outside the commitment should
#: pass ``contribution_kinds=(*CONTRIBUTION_KINDS, "fee")``.
CONTRIBUTION_KINDS: tuple[str, ...] = ("contribution", "capital_call", "subscription")

#: Kinds treated as capital coming back out of the fund.
DISTRIBUTION_KINDS: tuple[str, ...] = (
    "distribution",
    "dividend",
    "redemption",
    "proceeds",
)

#: How :func:`npv` / :func:`xirr` treat valuation marks. ``"terminal"`` keeps
#: only the latest mark (the standard fund-IRR treatment: residual value is
#: assumed liquidated at the measurement date), ``"all"`` keeps every mark
#: (wrong for an IRR unless the series holds exactly one), ``"exclude"`` drops
#: them (a realised-cash-only IRR).
VALUATION_POLICIES: tuple[str, ...] = ("terminal", "all", "exclude")

#: Policy used when the caller does not name one.
DEFAULT_VALUATION_POLICY: str = "terminal"

#: Day basis for converting a date difference into years. 365 is the Excel
#: ``XIRR`` convention and the private-markets norm.
DEFAULT_DAYS_PER_YEAR: float = 365.0

#: Rate window scanned for roots, as ``(low, high)``. The low bound must stay
#: above ``-1``: a rate of ``-100%`` makes every discount factor undefined.
DEFAULT_RATE_BOUNDS: tuple[float, float] = (-0.9999, 1.0e6)

#: Number of samples in the log-spaced bracket scan.
DEFAULT_GRID_POINTS: int = 512

#: Accrual conventions for a preferred return.
PREFERRED_COMPOUNDING: tuple[str, ...] = ("compound", "simple")

#: Preferred-return accrual assumed when the caller does not name one.
DEFAULT_PREFERRED_COMPOUNDING: str = "compound"

#: Waterfall tier labels, in the order they are paid.
TIER_RETURN_OF_CAPITAL: str = "return_of_capital"
TIER_PREFERRED_RETURN: str = "preferred_return"
TIER_CATCH_UP: str = "gp_catch_up"
TIER_CARRY_SPLIT: str = "carry_split"

#: Relative/absolute slack allowed when asserting that a waterfall's tiers sum
#: to the distributable amount. Anything looser would hide a real leak.
_ALLOCATION_TOLERANCE: float = 1e-9

#: NPV residual accepted as "this is a root", scaled by the gross flow size.
_DEFAULT_RESIDUAL_TOLERANCE: float = 1e-10

#: Two roots closer than this in rate space are the same root.
_ROOT_DEDUPE_TOLERANCE: float = 1e-9


class XIRRError(ValueError):
    """Base class for every reason an irregular-date IRR has no usable answer."""


class NoSignChangeError(XIRRError):
    """Raised when the flows never change sign, so no finite IRR exists.

    An all-negative or all-positive schedule has no rate at which its present
    value is zero (other than the degenerate limits). Returning a number here
    would be a fabricated result, so this is an error rather than a NaN.
    """


class XIRRConvergenceError(XIRRError):
    """Raised when the flows do change sign but no root could be verified.

    Both the bracketed scan and the Newton fallback failed to produce a rate
    whose net present value is zero to tolerance.
    """


# ---------------------------------------------------------------------------
# Series plumbing
# ---------------------------------------------------------------------------


def _require_series(series: CashFlowSeries, *, name: str = "series") -> CashFlowSeries:
    """Reject anything that is not a ``CashFlowSeries``.

    Args:
        series: Candidate value supplied by the caller.
        name: Parameter name to quote in the error message.

    Returns:
        The same series, unchanged.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``. A bare list of
            floats is refused on purpose -- it carries no dates, no currency and
            no kinds, and every one of those is load-bearing here.
    """
    if not isinstance(series, CashFlowSeries):
        raise TypeError(
            f"{name} must be a CashFlowSeries, got {type(series).__name__}; a bare "
            "sequence of amounts loses the dates, the currency and the flow kinds"
        )
    return series


def _select_flows(
    series: CashFlowSeries, valuations: str
) -> tuple[CashFlow, ...]:
    """Apply a valuation policy to a series' flows.

    Args:
        series: Source series, already date-ordered by its own constructor.
        valuations: One of :data:`VALUATION_POLICIES`.

    Returns:
        Date-ordered flows after the policy has been applied.

    Raises:
        ValueError: If ``valuations`` is not a recognised policy.
    """
    if valuations not in VALUATION_POLICIES:
        raise ValueError(
            f"valuations={valuations!r} is not one of {VALUATION_POLICIES}"
        )
    flows = tuple(series)
    if valuations == "all":
        return flows
    cash = [flow for flow in flows if not flow.is_valuation]
    if valuations == "exclude":
        return tuple(cash)
    marks = [flow for flow in flows if flow.is_valuation]
    if not marks:
        return tuple(cash)
    # ``flows`` is date-ordered, so the last mark is the terminal one.
    return tuple(sorted([*cash, marks[-1]], key=lambda flow: flow.date))


def _times_and_amounts(
    flows: Sequence[CashFlow], days_per_year: float
) -> tuple[np.ndarray, np.ndarray]:
    """Convert flows into year offsets from the first date, plus amounts.

    Args:
        flows: Date-ordered flows.
        days_per_year: Day basis, e.g. :data:`DEFAULT_DAYS_PER_YEAR`.

    Returns:
        Tuple ``(times, amounts)`` of float arrays; ``times[0]`` is ``0.0``.

    Raises:
        ValueError: If fewer than two flows are present, if every date is the
            same (no time span, so no rate is identifiable), or if
            ``days_per_year`` is not positive.
    """
    if days_per_year <= 0:
        raise ValueError(f"days_per_year must be positive, got {days_per_year!r}")
    if len(flows) < 2:
        raise ValueError(
            f"an irregular-date IRR needs at least two flows, got {len(flows)}"
        )
    dates = [flow.date for flow in flows]
    start = min(dates)
    if max(dates) == start:
        raise ValueError(
            f"all {len(flows)} flows fall on {start}; a rate of return is not "
            "identifiable without a time span"
        )
    times = np.array([(day - start).days / days_per_year for day in dates], dtype=float)
    amounts = np.array([flow.amount for flow in flows], dtype=float)
    return times, amounts


def _npv(rate: float, times: np.ndarray, amounts: np.ndarray) -> float:
    """Net present value of dated amounts at one rate.

    Discounting is done in log space (``exp(-t * log1p(r))``) so a large rate
    over a long horizon underflows to zero instead of overflowing a power.

    Args:
        rate: Annual rate as a decimal, strictly greater than ``-1``.
        times: Year offsets from the first flow.
        amounts: Signed amounts aligned with ``times``.

    Returns:
        The net present value, or a non-finite value when the rate is so close
        to ``-1`` that the discount factors overflow. Callers must check.
    """
    if rate <= -1.0:
        return math.nan
    with np.errstate(over="ignore", invalid="ignore", divide="ignore"):
        factors = np.exp(-times * np.log1p(rate))
        total = float(np.sum(amounts * factors))
    return total


def _npv_derivative(rate: float, times: np.ndarray, amounts: np.ndarray) -> float:
    """First derivative of :func:`_npv` with respect to the rate.

    Args:
        rate: Annual rate as a decimal, strictly greater than ``-1``.
        times: Year offsets from the first flow.
        amounts: Signed amounts aligned with ``times``.

    Returns:
        ``d(NPV)/d(rate)``, or a non-finite value on overflow.
    """
    if rate <= -1.0:
        return math.nan
    with np.errstate(over="ignore", invalid="ignore", divide="ignore"):
        factors = np.exp(-(times + 1.0) * np.log1p(rate))
        total = float(np.sum(-times * amounts * factors))
    return total


def npv(
    series: CashFlowSeries,
    rate: float,
    *,
    valuations: str = DEFAULT_VALUATION_POLICY,
    days_per_year: float = DEFAULT_DAYS_PER_YEAR,
) -> float:
    """Net present value of a dated cash-flow series at a given annual rate.

    Discounting is from the series' earliest date, so ``npv(series, 0.0)`` is
    just the sum of the selected amounts.

    Args:
        series: The cash flows. Must be a ``CashFlowSeries``.
        rate: Annual rate as a decimal (``0.08`` is 8%), strictly above ``-1``.
        valuations: One of :data:`VALUATION_POLICIES`; see that constant for
            what each policy does with NAV marks.
        days_per_year: Day basis for the year fraction.

    Returns:
        Present value at the series' first date, in the series' currency.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: If the rate is at or below ``-1``, if the policy is
            unknown, if fewer than two flows survive the policy, or if all
            surviving flows share one date.
    """
    _require_series(series)
    if rate <= -1.0:
        raise ValueError(
            f"rate must be greater than -1 (a -100% rate makes every discount "
            f"factor undefined), got {rate!r}"
        )
    flows = _select_flows(series, valuations)
    times, amounts = _times_and_amounts(flows, days_per_year)
    value = _npv(rate, times, amounts)
    if not math.isfinite(value):
        raise ValueError(
            f"net present value overflowed at rate={rate!r}; the rate is too "
            "close to -1 for this horizon"
        )
    return value


# ---------------------------------------------------------------------------
# XIRR
# ---------------------------------------------------------------------------


def _scan_roots(
    times: np.ndarray,
    amounts: np.ndarray,
    rate_bounds: tuple[float, float],
    grid_points: int,
    residual_tolerance: float,
) -> list[float]:
    """Find every rate in a window where the NPV crosses or touches zero.

    The window is sampled on a grid that is uniform in ``log(1 + r)``, so the
    same number of points resolves rates near ``-100%`` and rates in the
    thousands of percent. Each sign change is then closed with Brent's method,
    which cannot leave its bracket and therefore cannot report a root that is
    not there.

    Args:
        times: Year offsets from the first flow.
        amounts: Signed amounts aligned with ``times``.
        rate_bounds: ``(low, high)`` rate window; ``low`` must exceed ``-1``.
        grid_points: Number of samples across the window.
        residual_tolerance: Absolute NPV magnitude counted as zero.

    Returns:
        Ascending, de-duplicated roots. Empty when the grid found no crossing.

    Raises:
        ValueError: If the bounds are not ``-1 < low < high``, or if
            ``grid_points`` is below 3.
    """
    low, high = rate_bounds
    if low <= -1.0:
        raise ValueError(f"rate_bounds lower bound must exceed -1, got {low!r}")
    if high <= low:
        raise ValueError(f"rate_bounds must be increasing, got {rate_bounds!r}")
    if grid_points < 3:
        raise ValueError(f"grid_points must be at least 3, got {grid_points!r}")

    rates = np.expm1(np.linspace(math.log1p(low), math.log1p(high), grid_points))
    values = np.array([_npv(float(rate), times, amounts) for rate in rates])

    def objective(rate: float) -> float:
        return _npv(rate, times, amounts)

    roots: list[float] = []
    previous: int | None = None
    for index, value in enumerate(values):
        if not math.isfinite(value):
            continue
        if abs(value) <= residual_tolerance:
            roots.append(float(rates[index]))
            previous = index
            continue
        if (
            previous is not None
            and abs(values[previous]) > residual_tolerance
            and (values[previous] > 0) != (value > 0)
        ):
            roots.append(
                float(brentq(objective, float(rates[previous]), float(rates[index])))
            )
        previous = index

    unique: list[float] = []
    for root in sorted(roots):
        if not unique or abs(root - unique[-1]) > _ROOT_DEDUPE_TOLERANCE:
            unique.append(root)
    return unique


def xirr_all(
    series: CashFlowSeries,
    *,
    valuations: str = DEFAULT_VALUATION_POLICY,
    days_per_year: float = DEFAULT_DAYS_PER_YEAR,
    rate_bounds: tuple[float, float] = DEFAULT_RATE_BOUNDS,
    grid_points: int = DEFAULT_GRID_POINTS,
    residual_tolerance: float = _DEFAULT_RESIDUAL_TOLERANCE,
) -> tuple[float, ...]:
    """Every irregular-date IRR of a series inside the scanned rate window.

    A schedule whose signs change more than once (recallable distributions, a
    rescue financing) can have several mathematically valid IRRs. Reporting one
    of them as *the* IRR is a judgement call, so this function hands back all of
    them and :func:`xirr` documents which one it picks.

    Args:
        series: The cash flows.
        valuations: One of :data:`VALUATION_POLICIES`.
        days_per_year: Day basis for the year fraction.
        rate_bounds: ``(low, high)`` rate window to scan; ``low`` must exceed
            ``-1``.
        grid_points: Samples across the window; raise it if a pair of roots sit
            unusually close together.
        residual_tolerance: Relative NPV magnitude counted as zero, scaled by
            the sum of absolute flow amounts.

    Returns:
        Ascending roots. Empty only when the sign check passed but the scan
        found nothing, which :func:`xirr` turns into an error.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        NoSignChangeError: If the surviving amounts are all non-negative or all
            non-positive, or are all zero.
        ValueError: For an unknown policy, a bad rate window, or fewer than two
            dated flows.
    """
    _require_series(series)
    flows = _select_flows(series, valuations)
    times, amounts = _times_and_amounts(flows, days_per_year)

    gross = float(np.sum(np.abs(amounts)))
    if gross == 0.0:
        raise NoSignChangeError(
            "every amount is zero, so no rate of return is defined"
        )
    if not (amounts > 0).any() or not (amounts < 0).any():
        direction = "positive" if (amounts > 0).any() else "negative"
        raise NoSignChangeError(
            f"all {len(amounts)} amounts are {direction}, so the net present "
            "value never crosses zero and no IRR exists. Check the sign "
            "convention: contributions must be negative and distributions "
            "positive. If a terminal NAV is missing, add it as a valuation flow."
        )

    return tuple(
        _scan_roots(
            times,
            amounts,
            rate_bounds,
            grid_points,
            residual_tolerance * gross,
        )
    )


def xirr(
    series: CashFlowSeries,
    *,
    valuations: str = DEFAULT_VALUATION_POLICY,
    days_per_year: float = DEFAULT_DAYS_PER_YEAR,
    guess: float = 0.1,
    rate_bounds: tuple[float, float] = DEFAULT_RATE_BOUNDS,
    grid_points: int = DEFAULT_GRID_POINTS,
    residual_tolerance: float = _DEFAULT_RESIDUAL_TOLERANCE,
) -> float:
    """Money-weighted return of an irregularly dated cash-flow series.

    Solves ``sum(amount_i / (1 + r) ** t_i) == 0`` where ``t_i`` is the year
    offset of flow ``i`` from the earliest flow.

    Method, and its fallback. The primary solver is a bracketed one: the rate
    window is sampled on a log-spaced grid, and each sign change is closed with
    Brent's method, which is confined to its bracket and so cannot invent a
    root. Only if that scan finds nothing -- which can happen when two roots sit
    inside one grid cell -- does a Newton iteration from ``guess`` run as a
    fallback, and its answer is accepted only after the net present value there
    is checked against ``residual_tolerance``. An unverifiable answer raises
    :class:`XIRRConvergenceError` rather than being returned.

    When several roots exist the smallest is returned, because the alternatives
    are usually artefacts of a sign pattern rather than economics. Call
    :func:`xirr_all` to see them all before trusting the number.

    Args:
        series: The cash flows. Terminal NAV should be present as a valuation
            flow; under the default policy it is included and intermediate
            marks are dropped.
        valuations: One of :data:`VALUATION_POLICIES`.
        days_per_year: Day basis for the year fraction; 365 matches Excel's
            ``XIRR``.
        guess: Starting rate for the Newton fallback only. It has no effect on
            the bracketed path, so a bad guess cannot move the answer.
        rate_bounds: ``(low, high)`` rate window to scan.
        grid_points: Samples across the window.
        residual_tolerance: Relative NPV magnitude counted as zero, scaled by
            the sum of absolute flow amounts.

    Returns:
        The annual rate as a decimal (``0.184`` is 18.4%).

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        NoSignChangeError: If the flows never change sign, so no IRR exists.
        XIRRConvergenceError: If the flows do change sign but no root could be
            found and verified inside ``rate_bounds``.
        ValueError: For an unknown policy, a bad rate window, fewer than two
            dated flows, or flows that all share one date.
    """
    roots = xirr_all(
        series,
        valuations=valuations,
        days_per_year=days_per_year,
        rate_bounds=rate_bounds,
        grid_points=grid_points,
        residual_tolerance=residual_tolerance,
    )
    if roots:
        return roots[0]

    # Documented fallback: the scan is finite, so two roots inside one grid cell
    # leave it empty. Newton can still find one -- but only a verified one is
    # allowed out.
    flows = _select_flows(series, valuations)
    times, amounts = _times_and_amounts(flows, days_per_year)
    gross = float(np.sum(np.abs(amounts)))
    tolerance = residual_tolerance * gross
    low, high = rate_bounds
    try:
        candidate = float(
            newton(
                lambda rate: _npv(rate, times, amounts),
                guess,
                fprime=lambda rate: _npv_derivative(rate, times, amounts),
            )
        )
    except (RuntimeError, OverflowError, ValueError, FloatingPointError) as exc:
        raise XIRRConvergenceError(
            f"no IRR found in ({low}, {high}] by bracketed scan, and the Newton "
            f"fallback from guess={guess!r} failed: {exc}"
        ) from exc

    residual = _npv(candidate, times, amounts)
    if (
        not math.isfinite(candidate)
        or not math.isfinite(residual)
        or candidate <= low
        or candidate > high
        or abs(residual) > tolerance
    ):
        raise XIRRConvergenceError(
            f"no IRR found in ({low}, {high}] by bracketed scan; the Newton "
            f"fallback returned {candidate!r} with a net present value of "
            f"{residual!r}, which is not a root to tolerance {tolerance!r}"
        )
    return candidate


# ---------------------------------------------------------------------------
# Fund multiples
# ---------------------------------------------------------------------------


def paid_in_capital(
    series: CashFlowSeries,
    *,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
) -> float:
    """Total capital drawn into the fund, as a positive magnitude.

    Args:
        series: The cash flows.
        contribution_kinds: Kind labels counted as capital in. Defaults to
            :data:`CONTRIBUTION_KINDS`; add ``"fee"`` if the fund's management
            fees are charged outside the commitment and you want them in the
            denominator of the multiples.

    Returns:
        Positive paid-in capital; ``0.0`` when no contributions are present.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: If the matched flows net to an inflow, which means their
            signs contradict the holder-perspective convention.
    """
    _require_series(series)
    total = -series.filter(kind=contribution_kinds).total(include_valuations=True)
    if total < 0.0:
        raise ValueError(
            f"contributions net to an inflow of {-total!r}; under the "
            "holder-perspective sign convention capital going into a fund is "
            "negative. Check the contribution_kinds you passed."
        )
    return total


def distributed_capital(
    series: CashFlowSeries,
    *,
    distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,
) -> float:
    """Total capital returned by the fund, as a positive magnitude.

    Args:
        series: The cash flows.
        distribution_kinds: Kind labels counted as capital out. Defaults to
            :data:`DISTRIBUTION_KINDS`.

    Returns:
        Positive distributed capital; ``0.0`` when no distributions are present.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: If the matched flows net to an outflow.
    """
    _require_series(series)
    total = series.filter(kind=distribution_kinds).total(include_valuations=True)
    if total < 0.0:
        raise ValueError(
            f"distributions net to an outflow of {-total!r}; under the "
            "holder-perspective sign convention capital coming out of a fund is "
            "positive. Check the distribution_kinds you passed."
        )
    return total


def residual_value(series: CashFlowSeries) -> float:
    """Unrealised NAV of the fund at its most recent mark.

    Only the latest valuation record counts. Earlier marks are stale by
    definition, and summing them would report a fund's NAV several times over.

    Args:
        series: The cash flows, including any valuation records (``nav``,
            ``residual_value``, ``valuation``).

    Returns:
        The latest mark's amount, or ``0.0`` when the series holds no mark --
        which is the right answer for a fully liquidated fund.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: If the latest mark is negative. A negative NAV is possible
            in a levered vehicle but is never what a mis-signed file means, so
            it must be stated as a custom kind rather than inferred here.
    """
    _require_series(series)
    marks = [flow for flow in series if flow.is_valuation]
    if not marks:
        return 0.0
    value = marks[-1].amount
    if value < 0.0:
        raise ValueError(
            f"latest valuation on {marks[-1].date} is {value!r}; a residual "
            "value must be non-negative. If the vehicle really carries negative "
            "equity, record it under a custom kind and compute the multiple "
            "explicitly."
        )
    return value


def _require_paid_in(paid_in: float) -> float:
    """Reject a zero or negative denominator for a capital multiple.

    Args:
        paid_in: Paid-in capital as a positive magnitude.

    Returns:
        The same value.

    Raises:
        ValueError: If it is not strictly positive -- a multiple of nothing is
            undefined, and returning ``inf`` or ``0`` would both be wrong.
    """
    if paid_in <= 0.0:
        raise ValueError(
            f"paid-in capital is {paid_in!r}; a capital multiple is undefined "
            "with no capital drawn. Confirm the contribution kinds match the file."
        )
    return paid_in


def dpi(
    series: CashFlowSeries,
    *,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
    distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,
) -> float:
    """Distributions to paid-in: realised cash returned per unit drawn.

    Args:
        series: The cash flows.
        contribution_kinds: Kind labels counted as capital in.
        distribution_kinds: Kind labels counted as capital out.

    Returns:
        ``distributed / paid_in``. ``1.0`` is the point where the fund has
        returned the cash it drew.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: If no capital was drawn, or if a sign convention is violated.
    """
    paid_in = _require_paid_in(
        paid_in_capital(series, contribution_kinds=contribution_kinds)
    )
    return (
        distributed_capital(series, distribution_kinds=distribution_kinds) / paid_in
    )


def rvpi(
    series: CashFlowSeries,
    *,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
) -> float:
    """Residual value to paid-in: unrealised NAV per unit drawn.

    Args:
        series: The cash flows, including the latest valuation mark.
        contribution_kinds: Kind labels counted as capital in.

    Returns:
        ``residual_value / paid_in``; ``0.0`` for a fully liquidated fund.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: If no capital was drawn, or the latest mark is negative.
    """
    paid_in = _require_paid_in(
        paid_in_capital(series, contribution_kinds=contribution_kinds)
    )
    return residual_value(series) / paid_in


def tvpi(
    series: CashFlowSeries,
    *,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
    distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,
) -> float:
    """Total value to paid-in: realised plus unrealised value per unit drawn.

    By construction this is ``dpi + rvpi``; the identity is asserted in the
    tests so the three cannot drift apart.

    Args:
        series: The cash flows.
        contribution_kinds: Kind labels counted as capital in.
        distribution_kinds: Kind labels counted as capital out.

    Returns:
        ``(distributed + residual_value) / paid_in``.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: If no capital was drawn, or a sign convention is violated.
    """
    paid_in = _require_paid_in(
        paid_in_capital(series, contribution_kinds=contribution_kinds)
    )
    distributed = distributed_capital(
        series, distribution_kinds=distribution_kinds
    )
    return (distributed + residual_value(series)) / paid_in


def moic(
    series: CashFlowSeries,
    *,
    invested_capital: float | None = None,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
    distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,
) -> float:
    """Multiple on invested capital: total value over the capital put to work.

    At fund level with paid-in as the denominator this equals :func:`tvpi`. The
    two diverge only when the denominator differs -- a deal-level MOIC usually
    excludes fees and undeployed capital -- so that denominator is an explicit
    argument rather than a hidden convention.

    Args:
        series: The cash flows.
        invested_capital: Denominator to use, as a positive magnitude. ``None``
            uses paid-in capital, making the result identical to TVPI.
        contribution_kinds: Kind labels counted as capital in, used only when
            ``invested_capital`` is ``None``.
        distribution_kinds: Kind labels counted as capital out.

    Returns:
        ``(distributed + residual_value) / invested_capital``.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: If the denominator is not strictly positive, or a sign
            convention is violated.
    """
    if invested_capital is None:
        denominator = paid_in_capital(series, contribution_kinds=contribution_kinds)
    else:
        denominator = float(invested_capital)
    _require_paid_in(denominator)
    distributed = distributed_capital(
        series, distribution_kinds=distribution_kinds
    )
    return (distributed + residual_value(series)) / denominator


@dataclass(frozen=True)
class FundMultiples:
    """The standard LP reporting multiples, computed from one series.

    Attributes:
        paid_in: Capital drawn, positive magnitude.
        distributed: Capital returned, positive magnitude.
        residual_value: Latest NAV mark, ``0.0`` when fully liquidated.
        dpi: ``distributed / paid_in``.
        rvpi: ``residual_value / paid_in``.
        tvpi: ``dpi + rvpi``.
        moic: Total value over the invested-capital denominator, equal to
            ``tvpi`` when that denominator is paid-in capital.
        invested_capital: The denominator actually used for ``moic``.
    """

    paid_in: float
    distributed: float
    residual_value: float
    dpi: float
    rvpi: float
    tvpi: float
    moic: float
    invested_capital: float


def fund_multiples(
    series: CashFlowSeries,
    *,
    invested_capital: float | None = None,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
    distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,
) -> FundMultiples:
    """Compute DPI, RVPI, TVPI and MOIC in one pass over a series.

    Args:
        series: The cash flows.
        invested_capital: Denominator for MOIC; ``None`` uses paid-in capital.
        contribution_kinds: Kind labels counted as capital in.
        distribution_kinds: Kind labels counted as capital out.

    Returns:
        A :class:`FundMultiples` whose ``tvpi`` is exactly ``dpi + rvpi``.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: If no capital was drawn, if the MOIC denominator is not
            positive, or if a sign convention is violated.
    """
    paid_in = _require_paid_in(
        paid_in_capital(series, contribution_kinds=contribution_kinds)
    )
    distributed = distributed_capital(
        series, distribution_kinds=distribution_kinds
    )
    residual = residual_value(series)
    denominator = paid_in if invested_capital is None else float(invested_capital)
    _require_paid_in(denominator)

    distributed_to_paid_in = distributed / paid_in
    residual_to_paid_in = residual / paid_in
    return FundMultiples(
        paid_in=paid_in,
        distributed=distributed,
        residual_value=residual,
        dpi=distributed_to_paid_in,
        rvpi=residual_to_paid_in,
        # Written as the sum, not recomputed, so the identity holds bit-for-bit.
        tvpi=distributed_to_paid_in + residual_to_paid_in,
        moic=(distributed + residual) / denominator,
        invested_capital=denominator,
    )


# ---------------------------------------------------------------------------
# European (whole-of-fund) waterfall
# ---------------------------------------------------------------------------


def preferred_return_amount(
    series: CashFlowSeries,
    *,
    rate: float,
    as_of: _dt.date | _dt.datetime | str | None = None,
    compounding: str = DEFAULT_PREFERRED_COMPOUNDING,
    days_per_year: float = DEFAULT_DAYS_PER_YEAR,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
) -> float:
    """Preferred return owed to LPs, accrued per contribution from its own date.

    Accruing each draw separately matters: a fund that called half its capital
    three years after the first close owes materially less hurdle than one that
    called everything on day one, and a single fund-level ``years`` figure
    cannot express that.

    Args:
        series: The cash flows.
        rate: Annual preferred rate as a decimal (``0.08`` is an 8% hurdle).
            Must be non-negative.
        as_of: Measurement date. ``None`` uses the series' latest flow date.
        compounding: One of :data:`PREFERRED_COMPOUNDING`. ``"compound"``
            accrues ``(1 + rate) ** years - 1``; ``"simple"`` accrues
            ``rate * years``.
        days_per_year: Day basis for the year fraction.
        contribution_kinds: Kind labels counted as capital in.

    Returns:
        The preferred return owed, as a positive magnitude excluding the return
        of capital itself. ``0.0`` when nothing has been drawn.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: If the rate is negative or non-finite, the compounding convention is
            unknown, ``as_of`` precedes a contribution, or ``as_of`` is omitted
            for an empty series.
    """
    _require_series(series)
    if not math.isfinite(rate) or rate < 0.0:
        raise ValueError(f"preferred rate must be finite and non-negative, got {rate!r}")
    if compounding not in PREFERRED_COMPOUNDING:
        raise ValueError(
            f"compounding={compounding!r} is not one of {PREFERRED_COMPOUNDING}"
        )
    if not math.isfinite(days_per_year) or days_per_year <= 0:
        raise ValueError(f"days_per_year must be finite and positive, got {days_per_year!r}")

    contributions = tuple(series.filter(kind=contribution_kinds))
    if not contributions:
        return 0.0

    if as_of is None:
        if series.is_empty:
            raise ValueError("as_of is required for an empty series")
        measurement = max(series.dates())
    else:
        measurement = normalize_date(as_of, field_name="as_of")

    total = 0.0
    for flow in contributions:
        years = (measurement - flow.date).days / days_per_year
        if years < 0.0:
            raise ValueError(
                f"contribution on {flow.date} is after as_of={measurement}; a "
                "preferred return cannot accrue backwards"
            )
        principal = -flow.amount
        if compounding == "compound":
            total += principal * ((1.0 + rate) ** years - 1.0)
        else:
            total += principal * rate * years
    return total


@dataclass(frozen=True)
class WaterfallTier:
    """One tier of a distribution waterfall and how it split.

    Attributes:
        name: Tier label, one of the ``TIER_*`` constants.
        amount: Dollars that flowed through this tier.
        lp_amount: Portion allocated to the limited partners.
        gp_amount: Portion allocated to the general partner.
    """

    name: str
    amount: float
    lp_amount: float
    gp_amount: float

    def __post_init__(self) -> None:
        """Check that the tier's two shares account for the whole tier.

        Raises:
            ValueError: If ``lp_amount + gp_amount`` differs from ``amount``, or
                if any figure is negative. A waterfall that does not conserve
                cash is a bug, never a rounding artefact worth tolerating.
        """
        for label, value in (
            ("amount", self.amount),
            ("lp_amount", self.lp_amount),
            ("gp_amount", self.gp_amount),
        ):
            if value < -_ALLOCATION_TOLERANCE:
                raise ValueError(
                    f"tier {self.name!r} has a negative {label} of {value!r}"
                )
        if not math.isclose(
            self.lp_amount + self.gp_amount,
            self.amount,
            rel_tol=_ALLOCATION_TOLERANCE,
            abs_tol=_ALLOCATION_TOLERANCE,
        ):
            raise ValueError(
                f"tier {self.name!r} does not conserve cash: lp {self.lp_amount!r} "
                f"+ gp {self.gp_amount!r} != {self.amount!r}"
            )


@dataclass(frozen=True)
class WaterfallResult:
    """Outcome of a European whole-of-fund distribution waterfall.

    Attributes:
        distributable: Cash entering the waterfall.
        contributed_capital: LP capital that must be returned first.
        preferred_amount: Preferred return owed before the GP earns anything.
        tiers: The tiers in payment order.
        lp_total: Everything allocated to the limited partners.
        gp_total: Everything allocated to the general partner.
        unreturned_capital: Contributed capital still outstanding, positive when
            the distributable amount did not cover the return of capital.
        unpaid_preferred: Preferred return still owed, positive when the
            distributable amount did not clear the hurdle.
    """

    distributable: float
    contributed_capital: float
    preferred_amount: float
    tiers: tuple[WaterfallTier, ...]
    lp_total: float
    gp_total: float
    unreturned_capital: float
    unpaid_preferred: float

    def __post_init__(self) -> None:
        """Check that the tiers reconcile to the distributable amount.

        Raises:
            ValueError: If the tier amounts do not sum to ``distributable``, or
                if the per-side totals do not match the tier splits.
        """
        checks = (
            ("distributable", sum(tier.amount for tier in self.tiers), self.distributable),
            ("lp_total", sum(tier.lp_amount for tier in self.tiers), self.lp_total),
            ("gp_total", sum(tier.gp_amount for tier in self.tiers), self.gp_total),
            ("lp+gp", self.lp_total + self.gp_total, self.distributable),
        )
        for label, computed, expected in checks:
            if not math.isclose(
                computed,
                expected,
                rel_tol=_ALLOCATION_TOLERANCE,
                abs_tol=_ALLOCATION_TOLERANCE,
            ):
                raise ValueError(
                    f"waterfall does not reconcile on {label}: tiers give "
                    f"{computed!r}, expected {expected!r}"
                )

    def tier_amount(self, name: str) -> float:
        """Dollars that flowed through a named tier.

        Args:
            name: One of the ``TIER_*`` constants.

        Returns:
            The tier's ``amount``, or ``0.0`` if that tier is absent.
        """
        for tier in self.tiers:
            if tier.name == name:
                return tier.amount
        return 0.0

    @property
    def gp_profit_share(self) -> float:
        """Fraction of distributed profit that the GP received.

        Profit is everything distributed beyond the return of capital, so this
        is the realised carry percentage. It reaches the nominal carry rate only
        once the catch-up has completed.

        Returns:
            GP total over distributed profit, or ``0.0`` when no profit was
            distributed.
        """
        profit = self.distributable - self.tier_amount(TIER_RETURN_OF_CAPITAL)
        if profit <= 0.0:
            return 0.0
        return self.gp_total / profit


def waterfall_split(
    distributable: float,
    contributed_capital: float,
    preferred_amount: float,
    *,
    carry_rate: float,
    catch_up_rate: float = 1.0,
) -> WaterfallResult:
    """Split a distributable amount through the four European waterfall tiers.

    The tiers, paid strictly in order and only from what remains:

    1. **Return of capital** -- 100% to LPs until ``contributed_capital`` is back.
    2. **Preferred return** -- 100% to LPs until ``preferred_amount`` is paid.
    3. **GP catch-up** -- ``catch_up_rate`` to the GP, the rest to LPs, until the
       GP holds ``carry_rate`` of all profit distributed so far. Solving
       ``catch_up_rate * C == carry_rate * (preferred_paid + C)`` gives the tier
       size ``C = carry_rate * preferred_paid / (catch_up_rate - carry_rate)``.
       With a 100% catch-up and 20% carry that is ``0.25 * preferred_paid``, and
       the GP then holds exactly 20% of the ``1.25 * preferred_paid`` of profit
       distributed.
    4. **Carry split** -- the remainder splits ``carry_rate`` to the GP.

    Every rate is a parameter; nothing about 8% / 20% / 100% is baked in.

    Args:
        distributable: Cash to distribute, non-negative.
        contributed_capital: LP capital to return first, non-negative.
        preferred_amount: Preferred return owed, non-negative. See
            :func:`preferred_return_amount` to derive it from a series.
        carry_rate: GP share of profit above the hurdle, in ``[0, 1)``.
        catch_up_rate: GP share of each catch-up dollar, in ``[0, 1]``. Pass
            ``0.0`` for a fund with no catch-up tier; any other value must
            exceed ``carry_rate``, or the tier could never complete.

    Returns:
        A :class:`WaterfallResult` whose tiers sum exactly to ``distributable``.

    Raises:
        ValueError: If any amount is negative or non-finite, if ``carry_rate`` is outside
            ``[0, 1)``, if ``catch_up_rate`` is outside ``[0, 1]``, or if a
            non-zero ``catch_up_rate`` does not exceed ``carry_rate``.
    """
    for label, value in (
        ("distributable", distributable),
        ("contributed_capital", contributed_capital),
        ("preferred_amount", preferred_amount),
    ):
        if not math.isfinite(value) or value < 0.0:
            raise ValueError(f"{label} must be finite and non-negative, got {value!r}")
    if not 0.0 <= carry_rate < 1.0:
        raise ValueError(f"carry_rate must be in [0, 1), got {carry_rate!r}")
    if not 0.0 <= catch_up_rate <= 1.0:
        raise ValueError(f"catch_up_rate must be in [0, 1], got {catch_up_rate!r}")
    if catch_up_rate > 0.0 and catch_up_rate <= carry_rate:
        raise ValueError(
            f"catch_up_rate={catch_up_rate!r} must exceed carry_rate="
            f"{carry_rate!r}, otherwise the catch-up tier can never complete. "
            "Pass catch_up_rate=0.0 for a fund with no catch-up."
        )

    remaining = float(distributable)

    return_of_capital = min(remaining, float(contributed_capital))
    remaining -= return_of_capital

    preferred_paid = min(remaining, float(preferred_amount))
    remaining -= preferred_paid

    if catch_up_rate > 0.0 and carry_rate > 0.0:
        catch_up_target = carry_rate * preferred_paid / (catch_up_rate - carry_rate)
    else:
        catch_up_target = 0.0
    catch_up = min(remaining, catch_up_target)
    remaining -= catch_up

    residual = remaining
    gp_residual = carry_rate * residual

    tiers = (
        WaterfallTier(
            name=TIER_RETURN_OF_CAPITAL,
            amount=return_of_capital,
            lp_amount=return_of_capital,
            gp_amount=0.0,
        ),
        WaterfallTier(
            name=TIER_PREFERRED_RETURN,
            amount=preferred_paid,
            lp_amount=preferred_paid,
            gp_amount=0.0,
        ),
        WaterfallTier(
            name=TIER_CATCH_UP,
            amount=catch_up,
            lp_amount=catch_up * (1.0 - catch_up_rate),
            gp_amount=catch_up * catch_up_rate,
        ),
        WaterfallTier(
            name=TIER_CARRY_SPLIT,
            amount=residual,
            lp_amount=residual - gp_residual,
            gp_amount=gp_residual,
        ),
    )
    return WaterfallResult(
        distributable=float(distributable),
        contributed_capital=float(contributed_capital),
        preferred_amount=float(preferred_amount),
        tiers=tiers,
        lp_total=sum(tier.lp_amount for tier in tiers),
        gp_total=sum(tier.gp_amount for tier in tiers),
        unreturned_capital=float(contributed_capital) - return_of_capital,
        unpaid_preferred=float(preferred_amount) - preferred_paid,
    )


def european_waterfall(
    series: CashFlowSeries,
    *,
    preferred_rate: float,
    carry_rate: float,
    catch_up_rate: float = 1.0,
    as_of: _dt.date | _dt.datetime | str | None = None,
    compounding: str = DEFAULT_PREFERRED_COMPOUNDING,
    days_per_year: float = DEFAULT_DAYS_PER_YEAR,
    include_residual: bool = False,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
    distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,
) -> WaterfallResult:
    """Run a European whole-of-fund waterfall over an actual cash-flow series.

    Contributed capital and the distributable amount are read off the series,
    and the preferred return is accrued per contribution by
    :func:`preferred_return_amount`. The split itself is
    :func:`waterfall_split`.

    Args:
        series: The fund's cash flows.
        preferred_rate: Annual hurdle rate as a decimal.
        carry_rate: GP share of profit above the hurdle, in ``[0, 1)``.
        catch_up_rate: GP share of each catch-up dollar; ``0.0`` for no catch-up.
        as_of: Measurement date for the preferred accrual. ``None`` uses the
            series' latest flow date.
        compounding: One of :data:`PREFERRED_COMPOUNDING`.
        days_per_year: Day basis for the preferred accrual.
        include_residual: ``False`` (default) distributes only realised cash,
            which is what a European waterfall actually does. ``True`` adds the
            latest NAV mark for an "if the fund liquidated today" view -- a
            projection, not a settled split.
        contribution_kinds: Kind labels counted as capital in.
        distribution_kinds: Kind labels counted as capital out.

    Returns:
        A :class:`WaterfallResult` whose tiers sum exactly to the distributable
        amount.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``.
        ValueError: For a negative rate, an unknown compounding convention, a
            carry or catch-up rate outside its allowed range, a contribution
            dated after ``as_of``, or a sign-convention violation.
    """
    _require_series(series)
    contributed = paid_in_capital(series, contribution_kinds=contribution_kinds)
    distributable = distributed_capital(
        series, distribution_kinds=distribution_kinds
    )
    if include_residual:
        distributable += residual_value(series)
    preferred = preferred_return_amount(
        series,
        rate=preferred_rate,
        as_of=as_of,
        compounding=compounding,
        days_per_year=days_per_year,
        contribution_kinds=contribution_kinds,
    )
    return waterfall_split(
        distributable,
        contributed,
        preferred,
        carry_rate=carry_rate,
        catch_up_rate=catch_up_rate,
    )


# ---------------------------------------------------------------------------
# Public market equivalent (PME)
# ---------------------------------------------------------------------------
#
# All three functions below answer the same question -- "did this fund beat a
# public index?" -- from the same two inputs (a CashFlowSeries and a public
# index level series), but they are not interchangeable and answer it in
# different units:
#
#   ks_pme        a multiple. >1 means the fund beat the index; the number
#                 itself is not a rate and cannot be annualized.
#   pme_plus      an IRR, but one that is only meaningful *relative to the
#                 fund's own realised IRR* -- it is the rate an index-tracking
#                 portfolio would have posted had it been forced to end at the
#                 fund's actual NAV. Comparing it to another fund's PME+ IRR
#                 is not valid; comparing it to *this fund's own* xirr() is.
#   direct_alpha  an annualized excess return, directly interpretable on its
#                 own: positive means the fund beat the index by that many
#                 points a year, negative means it lagged. This is the only
#                 one of the three that is a standalone number.
#
# All three require the public index to have a level on every date they touch
# and refuse to forward-fill a gap, because a cash flow landing inside a
# missing stretch would otherwise be discounted against a silently wrong
# price. Terminal NAV is handled the same way fund_multiples() already
# handles it -- via residual_value(), i.e. only the single latest valuation
# mark counts, per the existing VALUATION_POLICIES convention. direct_alpha is
# the one exception: it hands every flow to xirr() unchanged and lets the
# caller's own valuations= policy decide, exactly like npv()/xirr() already
# do, so it is the most flexible of the three but also the one that needs the
# index to cover every mark in the series, not only the terminal one.


def _index_levels_by_date(index_levels: pd.Series) -> dict[_dt.date, float]:
    """Build a date -> level lookup table from a public index series.

    Args:
        index_levels: Public-market index levels, a ``pandas.Series`` whose
            index is date-like (``DatetimeIndex``, or labels accepted by
            :func:`~src.entities.models.normalize_date`) and whose values are
            the index's level on each date (a price or a total-return index
            value, not a return).

    Returns:
        Mapping from ``datetime.date`` to the index level on that date.

    Raises:
        TypeError: If ``index_levels`` is not a ``pandas.Series``.
        ValueError: If it is empty, a level is not finite and positive, or two
            entries normalize to the same date (an ambiguous lookup, refused
            rather than guessed at by taking the first or last).
    """
    if not isinstance(index_levels, pd.Series):
        raise TypeError(
            "index_levels must be a pandas Series of index levels indexed by "
            f"date, got {type(index_levels).__name__}"
        )
    if index_levels.empty:
        raise ValueError(
            "index_levels is empty; a public market equivalent needs a "
            "benchmark to compare against"
        )
    lookup: dict[_dt.date, float] = {}
    for raw_date, raw_level in index_levels.items():
        day = normalize_date(raw_date, field_name="index_levels date")
        if day in lookup:
            raise ValueError(
                f"index_levels has more than one entry for {day}; resolve the "
                "duplicate before calling, rather than have this function "
                "guess which one is authoritative"
            )
        level = float(raw_level)
        if not math.isfinite(level) or level <= 0.0:
            raise ValueError(
                f"index level on {day} is {raw_level!r}; index levels must be "
                "finite and positive to serve as a growth-factor denominator"
            )
        lookup[day] = level
    return lookup


def _index_level_at(
    lookup: Mapping[_dt.date, float], day: _dt.date, *, flow_description: str
) -> float:
    """Look up one date in an index lookup table, or fail loudly.

    Args:
        lookup: Table built by :func:`_index_levels_by_date`.
        day: Date to look up.
        flow_description: Human-readable description of what needed this
            date, quoted in the error message.

    Returns:
        The index level on ``day``.

    Raises:
        ValueError: If ``day`` has no entry. Forward-filling across the gap
            is deliberately not attempted: a flow that lands inside a missing
            stretch would then be discounted against a price that was never
            actually observed on that date.
    """
    try:
        return lookup[day]
    except KeyError as exc:
        raise ValueError(
            f"index_levels has no entry for {day} (needed for {flow_description}); "
            "forward-filling across the gap is not done automatically, because "
            "it would price a flow that lands inside a missing stretch against "
            "a level that was never actually observed on that date. Supply an "
            "index level for every cash-flow date this calculation touches."
        ) from exc


def _terminal_mark(series: CashFlowSeries) -> CashFlow | None:
    """The most recent valuation record in a series, if any.

    Selects the same record :func:`residual_value` would report the amount
    of, but also returns the record itself so its date is available -- which
    :func:`residual_value` has no reason to expose, but the PME functions
    need in order to look up an index level for it.

    Args:
        series: The cash flows.

    Returns:
        The latest ``CashFlow`` with ``is_valuation`` True, date-ordered same
        as the series; ``None`` if the series carries no valuation record.
    """
    marks = [flow for flow in series if flow.is_valuation]
    return marks[-1] if marks else None


def _default_as_of(series: CashFlowSeries) -> _dt.date:
    """Default measurement date for a PME calculation.

    Uses the terminal valuation mark's own date when the series carries one,
    because that mark is already "as of" some date, and growing it further
    with the index would assume the market kept the index's pace past the
    point somebody actually priced the fund. Falls back to the latest flow
    date when there is no mark at all -- the same rule
    :func:`preferred_return_amount` already uses for its own ``as_of=None``.

    Args:
        series: The cash flows.

    Returns:
        The date to measure at when the caller does not name one explicitly.

    Raises:
        ValueError: If the series is empty.
    """
    if series.is_empty:
        raise ValueError("as_of is required for an empty series")
    mark = _terminal_mark(series)
    return mark.date if mark is not None else max(series.dates())


def ks_pme(
    series: CashFlowSeries,
    index_levels: pd.Series,
    *,
    as_of: _dt.date | _dt.datetime | str | None = None,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
    distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,
) -> float:
    """Kaplan-Schoar public market equivalent.

    Every contribution and distribution is grown to a single common date
    (``as_of``) using the *public index's* realised growth between the flow's
    own date and ``as_of`` -- i.e. each flow is asking "what would this dollar
    be worth today if it had instead been invested in the index on this
    date". Terminal NAV, via :func:`residual_value` (only the latest mark
    counts, matching how :func:`fund_multiples` already treats it), is added
    to the distributions side unchanged in kind but likewise grown from its
    own mark date to ``as_of``::

        KS-PME = (FV(distributions) + FV(NAV)) / FV(contributions)

    A result above 1 means the fund returned more than the index would have
    over the same capital deployment schedule; below 1 means it returned
    less. KS-PME is a multiple, not a rate -- it says nothing about *how
    fast* the outperformance happened, which is what :func:`direct_alpha`
    is for.

    Args:
        series: The fund's cash flows.
        index_levels: Public index levels. Must have an entry for every
            contribution date, every distribution date, the terminal
            valuation's date (if any), and ``as_of`` itself.
        as_of: Common date to grow every flow to. ``None`` uses
            :func:`_default_as_of` (the terminal mark's date, or the latest
            flow date).
        contribution_kinds: Kind labels counted as capital in.
        distribution_kinds: Kind labels counted as capital out.

    Returns:
        The KS-PME multiple.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``, or
            ``index_levels`` is not a ``pandas.Series``.
        ValueError: If ``index_levels`` is empty or has a non-positive level,
            if it lacks an entry for a date this calculation needs, if no
            contributions were found (or their future value is zero -- KS-PME
            has nothing to divide by), or if a contribution/distribution's
            sign contradicts the holder-perspective convention.
    """
    _require_series(series)
    lookup = _index_levels_by_date(index_levels)
    measurement = (
        normalize_date(as_of, field_name="as_of")
        if as_of is not None
        else _default_as_of(series)
    )
    index_as_of = _index_level_at(lookup, measurement, flow_description="as_of")

    contributions = tuple(series.filter(kind=contribution_kinds))
    fv_contributions = 0.0
    for flow in contributions:
        if flow.amount > 0.0:
            raise ValueError(
                f"contribution on {flow.date} has a positive amount "
                f"{flow.amount!r}; under the holder-perspective sign "
                "convention capital going into a fund is negative"
            )
        index_then = _index_level_at(
            lookup, flow.date, flow_description=f"contribution on {flow.date}"
        )
        fv_contributions += (-flow.amount) * (index_as_of / index_then)
    if fv_contributions <= 0.0:
        raise ValueError(
            "no contributions were found (or their future value at as_of is "
            "zero); KS-PME is undefined with nothing paid in"
        )

    distributions = tuple(series.filter(kind=distribution_kinds))
    fv_distributions = 0.0
    for flow in distributions:
        if flow.amount < 0.0:
            raise ValueError(
                f"distribution on {flow.date} has a negative amount "
                f"{flow.amount!r}; under the holder-perspective sign "
                "convention capital coming out of a fund is positive"
            )
        index_then = _index_level_at(
            lookup, flow.date, flow_description=f"distribution on {flow.date}"
        )
        fv_distributions += flow.amount * (index_as_of / index_then)

    nav_amount = residual_value(series)
    fv_nav = 0.0
    if nav_amount > 0.0:
        terminal_mark = _terminal_mark(series)
        assert terminal_mark is not None  # residual_value > 0 implies a mark exists
        index_then = _index_level_at(
            lookup, terminal_mark.date, flow_description="terminal valuation"
        )
        fv_nav = nav_amount * (index_as_of / index_then)

    return (fv_distributions + fv_nav) / fv_contributions


@dataclass(frozen=True)
class PMEPlusResult:
    """Outcome of a Kaplan-Schoar PME+ (Rouvinez) benchmark.

    Attributes:
        scaling_factor: The multiplier applied to every actual distribution
            so that an index-tracking portfolio -- built from the fund's
            actual, unscaled contributions and these scaled distributions --
            ends at exactly the fund's actual terminal NAV. Below 1 means the
            fund's real distributions were larger than an index-tracking
            portfolio would have needed to reach the same ending NAV (the
            fund outran the index); above 1 means the opposite.
        irr: The money-weighted return of the fund's actual contributions,
            the *scaled* distributions, and the actual terminal NAV. This
            rate is only meaningful next to the fund's own realised
            :func:`xirr` -- a lower PME+ IRR than the fund's own IRR means
            the fund beat the index; a higher one means it lagged. It is not
            comparable across two different funds.
    """

    scaling_factor: float
    irr: float


def pme_plus(
    series: CashFlowSeries,
    index_levels: pd.Series,
    *,
    as_of: _dt.date | _dt.datetime | str | None = None,
    days_per_year: float = DEFAULT_DAYS_PER_YEAR,
    guess: float = 0.1,
    rate_bounds: tuple[float, float] = DEFAULT_RATE_BOUNDS,
    grid_points: int = DEFAULT_GRID_POINTS,
    residual_tolerance: float = _DEFAULT_RESIDUAL_TOLERANCE,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
    distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,
) -> PMEPlusResult:
    """Kaplan-Schoar "PME+" (Rouvinez) -- a comparable IRR, not a multiple.

    KS-PME reports a multiple, which cannot be annualized and cannot be
    compared to the fund's own IRR. PME+ instead solves for a single scaling
    factor ``lambda`` applied to every actual distribution such that an
    index-replicating portfolio -- fed the fund's real, unscaled
    contributions and the scaled distributions -- ends up with exactly the
    fund's real terminal NAV::

        FV(contributions) = lambda * FV(distributions) + FV(NAV)
        lambda = (FV(contributions) - FV(NAV)) / FV(distributions)

    where every FV(...) grows a flow from its own date to ``as_of`` using the
    public index, the same growth :func:`ks_pme` uses (and NAV is read via
    :func:`residual_value`, so only the latest mark counts). The scaled
    distributions, unchanged contributions and unchanged terminal NAV are
    then handed to :func:`xirr` to solve a rate directly comparable to the
    fund's own realised IRR -- see :class:`PMEPlusResult`.

    Only flows matching ``contribution_kinds`` or ``distribution_kinds``
    participate, plus the terminal valuation mark; a flow of some other kind
    (an out-of-band fee, say) is invisible to this calculation exactly as it
    already is to :func:`dpi`/:func:`tvpi` unless the caller widens the kind
    set.

    Args:
        series: The fund's cash flows.
        index_levels: Public index levels. Must have an entry for every
            contribution date, every distribution date, the terminal
            valuation's date (if any), and ``as_of`` itself.
        as_of: Common date to grow every flow to. ``None`` uses
            :func:`_default_as_of`.
        days_per_year: Day basis passed to the final :func:`xirr` call.
        guess: Newton fallback starting rate passed to :func:`xirr`.
        rate_bounds: Rate window passed to :func:`xirr`.
        grid_points: Grid resolution passed to :func:`xirr`.
        residual_tolerance: Root tolerance passed to :func:`xirr`.
        contribution_kinds: Kind labels counted as capital in.
        distribution_kinds: Kind labels counted as capital out.

    Returns:
        A :class:`PMEPlusResult` with the scaling factor and the comparable
        IRR.

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``, or
            ``index_levels`` is not a ``pandas.Series``.
        ValueError: If ``index_levels`` lacks a needed date, if there are no
            contributions or their future value is zero, if there are no
            distributions or their future value is zero (the scaling factor
            would divide by zero), if a sign contradicts the
            holder-perspective convention, or if the resulting scaled series
            has no usable IRR (see :func:`xirr`).
    """
    _require_series(series)
    lookup = _index_levels_by_date(index_levels)
    measurement = (
        normalize_date(as_of, field_name="as_of")
        if as_of is not None
        else _default_as_of(series)
    )
    index_as_of = _index_level_at(lookup, measurement, flow_description="as_of")

    contributions = tuple(series.filter(kind=contribution_kinds))
    if not contributions:
        raise ValueError(
            "no contributions were found; PME+ is undefined with nothing "
            "paid in"
        )
    fv_contributions = 0.0
    for flow in contributions:
        if flow.amount > 0.0:
            raise ValueError(
                f"contribution on {flow.date} has a positive amount "
                f"{flow.amount!r}; under the holder-perspective sign "
                "convention capital going into a fund is negative"
            )
        index_then = _index_level_at(
            lookup, flow.date, flow_description=f"contribution on {flow.date}"
        )
        fv_contributions += (-flow.amount) * (index_as_of / index_then)
    if fv_contributions <= 0.0:
        raise ValueError(
            "contributions have zero future value at as_of; PME+ is "
            "undefined with nothing paid in"
        )

    distributions = tuple(series.filter(kind=distribution_kinds))
    if not distributions:
        raise ValueError(
            "no distributions were found; PME+ solves a scaling factor for "
            "the distributions, and there is nothing to scale"
        )
    fv_distributions = 0.0
    for flow in distributions:
        if flow.amount < 0.0:
            raise ValueError(
                f"distribution on {flow.date} has a negative amount "
                f"{flow.amount!r}; under the holder-perspective sign "
                "convention capital coming out of a fund is positive"
            )
        index_then = _index_level_at(
            lookup, flow.date, flow_description=f"distribution on {flow.date}"
        )
        fv_distributions += flow.amount * (index_as_of / index_then)
    if fv_distributions <= 0.0:
        raise ValueError(
            "distributions have zero future value at as_of; PME+ cannot "
            "solve a scaling factor by dividing by zero"
        )

    nav_amount = residual_value(series)
    terminal_mark = _terminal_mark(series)
    fv_nav = 0.0
    if nav_amount > 0.0:
        assert terminal_mark is not None
        index_then = _index_level_at(
            lookup, terminal_mark.date, flow_description="terminal valuation"
        )
        fv_nav = nav_amount * (index_as_of / index_then)

    scaling_factor = (fv_contributions - fv_nav) / fv_distributions

    scaled_flows: list[CashFlow] = [
        CashFlow(
            date=flow.date,
            amount=flow.amount,
            kind=flow.kind,
            currency=flow.currency,
            metadata=flow.metadata,
        )
        for flow in contributions
    ]
    scaled_flows.extend(
        CashFlow(
            date=flow.date,
            amount=flow.amount * scaling_factor,
            kind=flow.kind,
            currency=flow.currency,
            metadata=flow.metadata,
        )
        for flow in distributions
    )
    if terminal_mark is not None:
        scaled_flows.append(terminal_mark)
    scaled_series = CashFlowSeries(
        tuple(scaled_flows), currency=series.currency, pre_translated=series.pre_translated
    )
    irr = xirr(
        scaled_series,
        days_per_year=days_per_year,
        guess=guess,
        rate_bounds=rate_bounds,
        grid_points=grid_points,
        residual_tolerance=residual_tolerance,
    )
    return PMEPlusResult(scaling_factor=scaling_factor, irr=irr)


def direct_alpha(
    series: CashFlowSeries,
    index_levels: pd.Series,
    *,
    valuations: str = DEFAULT_VALUATION_POLICY,
    days_per_year: float = DEFAULT_DAYS_PER_YEAR,
    guess: float = 0.1,
    rate_bounds: tuple[float, float] = DEFAULT_RATE_BOUNDS,
    grid_points: int = DEFAULT_GRID_POINTS,
    residual_tolerance: float = _DEFAULT_RESIDUAL_TOLERANCE,
) -> float:
    """Direct Alpha -- an annualized excess return over a public index.

    Every flow, of every kind (contribution, distribution or valuation
    mark), is deflated by the public index level on its own date and left at
    its own date::

        CF'_i = CF_i / I(t_i)

    and :func:`xirr` is then run on the deflated series unchanged, valuation
    policy and all. Direct Alpha is the rate that solves this.

    Why this is "alpha" and not just a rescaled IRR: write the index level as
    ``I(t) = I(t0) * (1+g)**years`` for a constant realised index CAGR ``g``
    between two flow dates. Substituting into the NPV equation the deflated
    series satisfies shows the deflator and the discount rate combine
    multiplicatively -- solving ``sum CF_i / I(t_i) / (1+alpha)**t_i == 0`` is
    algebraically the same as solving ``sum CF_i / (1+alpha)**t_i / (1+g)**t_i
    == 0``, i.e. ``sum CF_i / ((1+alpha)(1+g))**t_i == 0``. The rate that
    zeroes *that* equation is, by definition, the fund's own plain
    :func:`xirr`, call it ``rho``. So ``(1+alpha)(1+g) = (1+rho)``, i.e.
    ``alpha = (1+rho)/(1+g) - 1`` -- the geometric excess of the fund's own
    realised IRR over the index's realised CAGR. Using actual index *levels*
    rather than one flat CAGR is what lets this hold even when the index's
    growth rate varies over the fund's life, and it is also why, unlike
    :func:`ks_pme` and :func:`pme_plus`, this function takes no ``as_of`` --
    the reference date cancels out of the equation algebraically, so the
    result cannot depend on one.

    Positive means the fund beat the index by that many annualized points;
    negative means it lagged. Unlike PME+'s IRR, this number needs no
    companion fund IRR to be interpreted -- it already is the excess.

    Args:
        series: The fund's cash flows.
        index_levels: Public index levels. Must have an entry for every flow
            in ``series``, including every intermediate valuation mark --
            not only the one ``valuations`` ultimately keeps, because the
            deflation happens before the policy is applied.
        valuations: One of :data:`VALUATION_POLICIES`, passed through to the
            final :func:`xirr` call unchanged.
        days_per_year: Day basis passed to :func:`xirr`.
        guess: Newton fallback starting rate passed to :func:`xirr`.
        rate_bounds: Rate window passed to :func:`xirr`.
        grid_points: Grid resolution passed to :func:`xirr`.
        residual_tolerance: Root tolerance passed to :func:`xirr`.

    Returns:
        The annualized excess return as a decimal (``0.05`` is 5 points of
        annual alpha over the index).

    Raises:
        TypeError: If ``series`` is not a ``CashFlowSeries``, or
            ``index_levels`` is not a ``pandas.Series``.
        ValueError: If ``index_levels`` lacks an entry for any flow's date,
            or if the deflated series has no usable IRR -- see :func:`xirr`
            for the full list (no sign change, too few flows, an unknown
            policy, and so on).
    """
    _require_series(series)
    lookup = _index_levels_by_date(index_levels)
    scaled_flows = []
    for flow in series:
        index_then = _index_level_at(
            lookup, flow.date, flow_description=f"{flow.kind} on {flow.date}"
        )
        scaled_flows.append(
            CashFlow(
                date=flow.date,
                amount=flow.amount / index_then,
                kind=flow.kind,
                currency=flow.currency,
                metadata=flow.metadata,
            )
        )
    scaled_series = CashFlowSeries(
        tuple(scaled_flows), currency=series.currency, pre_translated=series.pre_translated
    )
    return xirr(
        scaled_series,
        valuations=valuations,
        days_per_year=days_per_year,
        guess=guess,
        rate_bounds=rate_bounds,
        grid_points=grid_points,
        residual_tolerance=residual_tolerance,
    )


# ---------------------------------------------------------------------------
# American (deal-by-deal) waterfall + GP clawback
# ---------------------------------------------------------------------------
#
# european_waterfall() above is whole-of-fund: every dollar of contributed
# capital and the whole preferred return must be paid back before the GP sees
# any carry. That structurally protects LPs from the failure mode below,
# which is exactly why a European fund essentially never triggers a
# clawback -- see gp_clawback()'s docstring for the one-line reason it is
# still not literally impossible.
#
# An American (deal-by-deal) waterfall pays carry per investment as it exits,
# without waiting for the rest of the fund. That is what makes "distribute
# early, lose money later" representable: the GP can collect carry on a
# profitable exit in year 2 while a different investment in the same fund
# loses money in year 5, and there is no mechanism inside the deal-by-deal
# structure itself that hands that carry back. A clawback provision is the
# LPA's fix -- a true-up at fund termination that compares carry actually
# received against what a whole-of-fund calculation says the GP earned once
# every deal is counted, and requires the GP to return the difference.


def _validate_deals(deals: Mapping[str, CashFlowSeries]) -> Mapping[str, CashFlowSeries]:
    """Check a deal-by-deal input before any arithmetic touches it.

    Args:
        deals: Deal-id -> that deal's own cash flows.

    Returns:
        The same mapping, unchanged.

    Raises:
        TypeError: If ``deals`` is not a mapping, or a value is not a
            ``CashFlowSeries``.
        ValueError: If ``deals`` is empty, or the deals span more than one
            currency.
    """
    if not isinstance(deals, Mapping):
        raise TypeError(
            f"deals must be a mapping of deal_id -> CashFlowSeries, got "
            f"{type(deals).__name__}"
        )
    if not deals:
        raise ValueError(
            "deals is empty; a deal-by-deal waterfall needs at least one deal"
        )
    currencies: set[str] = set()
    for deal_id, series in deals.items():
        _require_series(series, name=f"deals[{deal_id!r}]")
        if series.currency is not None:
            currencies.add(series.currency)
    if len(currencies) > 1:
        raise ValueError(
            f"deals span multiple currencies ({', '.join(sorted(currencies))}); "
            "convert them to one reporting currency before pooling -- the same "
            "discipline CashFlowSeries itself enforces within a single series"
        )
    return deals


def _pool_deals(deals: Mapping[str, CashFlowSeries]) -> CashFlowSeries:
    """Combine every deal's flows into one whole-of-fund series.

    Args:
        deals: Deal-id -> that deal's cash flows. Assumed already validated
            by :func:`_validate_deals` (non-empty, one currency).

    Returns:
        A single ``CashFlowSeries`` holding every flow from every deal.
    """
    all_flows: list[CashFlow] = []
    for series in deals.values():
        all_flows.extend(series)
    currency = next(iter(deals.values())).currency
    return CashFlowSeries(tuple(all_flows), currency=currency)


@dataclass(frozen=True)
class AmericanWaterfallResult:
    """Deal-by-deal waterfall outcome, aggregated across every investment.

    Attributes:
        deals: Each deal's own :class:`WaterfallResult`, keyed by the same
            deal id the caller supplied to :func:`american_waterfall`.
        lp_total: Sum of every deal's ``lp_total``.
        gp_total: Sum of every deal's ``gp_total`` -- the GP's total carry
            actually paid out across every deal, i.e. carry *received*.
        distributable: Sum of every deal's ``distributable`` amount.
    """

    deals: Mapping[str, WaterfallResult]
    lp_total: float
    gp_total: float
    distributable: float

    def __post_init__(self) -> None:
        """Check that the per-deal results sum to the reported totals.

        Raises:
            ValueError: If ``deals`` is empty, or a reported total does not
                match the sum of the per-deal results.
        """
        if not self.deals:
            raise ValueError(
                "an American waterfall result must hold at least one deal"
            )
        checks = (
            ("lp_total", sum(r.lp_total for r in self.deals.values()), self.lp_total),
            ("gp_total", sum(r.gp_total for r in self.deals.values()), self.gp_total),
            (
                "distributable",
                sum(r.distributable for r in self.deals.values()),
                self.distributable,
            ),
        )
        for label, computed, expected in checks:
            if not math.isclose(
                computed, expected, rel_tol=_ALLOCATION_TOLERANCE, abs_tol=_ALLOCATION_TOLERANCE
            ):
                raise ValueError(
                    f"American waterfall result does not reconcile on {label}: "
                    f"deals give {computed!r}, expected {expected!r}"
                )


def american_waterfall(
    deals: Mapping[str, CashFlowSeries],
    *,
    preferred_rate: float,
    carry_rate: float,
    catch_up_rate: float = 1.0,
    as_of: Mapping[str, _dt.date | _dt.datetime | str] | None = None,
    compounding: str = DEFAULT_PREFERRED_COMPOUNDING,
    days_per_year: float = DEFAULT_DAYS_PER_YEAR,
    include_residual: bool = False,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
    distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,
) -> AmericanWaterfallResult:
    """Run a deal-by-deal (American) waterfall.

    Each deal is its own miniature fund: its own contributed capital, its own
    preferred return accrued from its own contribution dates, and its own
    return-of-capital / preferred / catch-up / carry-split tiers, computed by
    calling :func:`european_waterfall` once per deal with that deal's own
    series. Nothing about the tier mechanics is reimplemented here -- a
    single-deal call to this function reproduces :func:`european_waterfall`
    on that same series exactly. What makes the result "American" is that
    carry crystallizes independently on each deal, at that deal's own exit,
    with no visibility into how the fund's other deals are doing -- which is
    also exactly the property that makes a clawback representable at all; see
    :func:`gp_clawback`.

    The GP catch-up tier is unchanged from :func:`waterfall_split`: it lets
    the GP catch up *to* its target carry percentage on that deal's own
    profit, not an extra bonus on top of it.

    Args:
        deals: Deal-id -> that deal's own cash flows. Every deal must share
            one currency.
        preferred_rate: Annual hurdle rate as a decimal, applied identically
            to every deal.
        carry_rate: GP share of profit above the hurdle, in ``[0, 1)``,
            applied identically to every deal.
        catch_up_rate: GP share of each catch-up dollar; ``0.0`` for no
            catch-up.
        as_of: Per-deal override for the preferred-return measurement date,
            as a mapping from deal id to a date. A deal absent from the
            mapping (or ``as_of=None`` entirely) uses that deal's own latest
            flow date -- the natural exit-date accrual for a deal that has
            actually closed.
        compounding: One of :data:`PREFERRED_COMPOUNDING`, applied to every
            deal.
        days_per_year: Day basis for the preferred accrual.
        include_residual: Passed through to each deal's
            :func:`european_waterfall` call; see that function.
        contribution_kinds: Kind labels counted as capital in.
        distribution_kinds: Kind labels counted as capital out.

    Returns:
        An :class:`AmericanWaterfallResult` aggregating every deal.

    Raises:
        TypeError: If ``deals`` is not a mapping, a value is not a
            ``CashFlowSeries``, or ``as_of`` is neither a mapping nor None.
        ValueError: If ``deals`` is empty, spans more than one currency, or
            any deal raises the errors :func:`european_waterfall` already
            documents (bad rate, contribution after ``as_of``, sign-
            convention violation, and so on).
    """
    deals = _validate_deals(deals)
    if as_of is not None and not isinstance(as_of, Mapping):
        # A bare date silently fell back to per-deal latest-flow accrual here,
        # which reads like an honored override. Refuse it like a bad `deals`.
        raise TypeError(
            "as_of must be a mapping of deal_id -> date, or None; got "
            f"{type(as_of).__name__}. Pass a single date per deal as "
            "{deal_id: date}, or None to accrue to each deal's latest flow date."
        )
    per_deal: dict[str, WaterfallResult] = {}
    for deal_id, series in deals.items():
        deal_as_of = as_of.get(deal_id) if as_of is not None else None
        per_deal[deal_id] = european_waterfall(
            series,
            preferred_rate=preferred_rate,
            carry_rate=carry_rate,
            catch_up_rate=catch_up_rate,
            as_of=deal_as_of,
            compounding=compounding,
            days_per_year=days_per_year,
            include_residual=include_residual,
            contribution_kinds=contribution_kinds,
            distribution_kinds=distribution_kinds,
        )
    return AmericanWaterfallResult(
        deals=MappingProxyType(dict(per_deal)),
        lp_total=sum(result.lp_total for result in per_deal.values()),
        gp_total=sum(result.gp_total for result in per_deal.values()),
        distributable=sum(result.distributable for result in per_deal.values()),
    )


def _pooled_entitlement(
    deals: Mapping[str, CashFlowSeries],
    *,
    preferred_rate: float,
    carry_rate: float,
    catch_up_rate: float,
    as_of: _dt.date | _dt.datetime | str | None,
    compounding: str,
    days_per_year: float,
    include_residual: bool,
    contribution_kinds: Iterable[str],
    distribution_kinds: Iterable[str],
) -> WaterfallResult:
    """The whole-of-fund (European) split every deal's cash would have earned.

    This is the entitlement side of a clawback test: pool every deal's
    contributions and distributions, accrue one preferred return over the
    pooled contribution schedule, and run one :func:`waterfall_split`.

    Residual value is summed *per deal* -- via :func:`residual_value` called
    once on each deal's own series -- rather than read off the pooled series
    directly. :func:`residual_value` keeps only the single latest valuation
    mark in a series, which is correct for one fund's own evolving NAV but
    wrong for a pool of several deals' independent marks: reading it off the
    pooled series would keep whichever deal happens to carry the latest-dated
    mark and silently drop every other still-open deal's NAV.

    Args:
        deals: Deal-id -> that deal's cash flows. Assumed already validated.
        preferred_rate: Annual hurdle rate as a decimal.
        carry_rate: GP share of profit above the hurdle.
        catch_up_rate: GP share of each catch-up dollar.
        as_of: Measurement date for the pooled preferred accrual. ``None``
            uses the latest date anywhere across every deal.
        compounding: One of :data:`PREFERRED_COMPOUNDING`.
        days_per_year: Day basis for the preferred accrual.
        include_residual: Whether to add each still-open deal's own residual
            value to the pooled distributable amount.
        contribution_kinds: Kind labels counted as capital in.
        distribution_kinds: Kind labels counted as capital out.

    Returns:
        The pooled :class:`WaterfallResult`.
    """
    pooled = _pool_deals(deals)
    contributed = paid_in_capital(pooled, contribution_kinds=contribution_kinds)
    distributed = distributed_capital(pooled, distribution_kinds=distribution_kinds)
    residual = (
        sum(residual_value(series) for series in deals.values())
        if include_residual
        else 0.0
    )
    preferred = preferred_return_amount(
        pooled,
        rate=preferred_rate,
        as_of=as_of,
        compounding=compounding,
        days_per_year=days_per_year,
        contribution_kinds=contribution_kinds,
    )
    return waterfall_split(
        distributed + residual,
        contributed,
        preferred,
        carry_rate=carry_rate,
        catch_up_rate=catch_up_rate,
    )


@dataclass(frozen=True)
class ClawbackResult:
    """Outcome of a GP clawback test at fund termination.

    Attributes:
        carry_received: Carry the GP actually collected -- the sum of every
            deal's own realised carry under the deal-by-deal structure
            (:func:`american_waterfall`'s ``gp_total``, with
            ``include_residual=False`` always, because unrealised NAV is not
            carry anyone has been paid).
        carry_entitled: Carry the GP is entitled to once every deal's cash
            flows are pooled and run through one whole-of-fund waterfall --
            the number a European structure would actually have paid; see
            :func:`_pooled_entitlement`.
        clawback_amount: ``max(0, carry_received - carry_entitled)``, scaled
            down for tax already paid when ``tax_adjusted`` is True.
        tax_adjusted: Whether ``clawback_amount`` reflects a net-of-tax cap.
        gp_tax_rate: The rate used when ``tax_adjusted`` is True, else
            ``None``.
    """

    carry_received: float
    carry_entitled: float
    clawback_amount: float
    tax_adjusted: bool
    gp_tax_rate: float | None

    def __post_init__(self) -> None:
        """Check the reported figures are internally consistent.

        Raises:
            ValueError: If any dollar figure is negative, or if
                ``tax_adjusted`` and ``gp_tax_rate`` disagree about whether a
                tax adjustment was applied.
        """
        for label, value in (
            ("carry_received", self.carry_received),
            ("carry_entitled", self.carry_entitled),
            ("clawback_amount", self.clawback_amount),
        ):
            if value < -_ALLOCATION_TOLERANCE:
                raise ValueError(f"{label} cannot be negative, got {value!r}")
        if self.tax_adjusted and self.gp_tax_rate is None:
            raise ValueError("tax_adjusted is True but gp_tax_rate is None")
        if not self.tax_adjusted and self.gp_tax_rate is not None:
            raise ValueError(
                f"gp_tax_rate={self.gp_tax_rate!r} is set but tax_adjusted is False"
            )


def gp_clawback(
    deals: Mapping[str, CashFlowSeries],
    *,
    preferred_rate: float,
    carry_rate: float,
    catch_up_rate: float = 1.0,
    termination_date: _dt.date | _dt.datetime | str | None = None,
    compounding: str = DEFAULT_PREFERRED_COMPOUNDING,
    days_per_year: float = DEFAULT_DAYS_PER_YEAR,
    include_unrealized_in_entitlement: bool = False,
    contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,
    distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,
    gp_tax_rate: float | None = None,
) -> ClawbackResult:
    """Test whether a deal-by-deal GP owes money back at fund termination.

    Compares carry actually received (summed deal by deal, each deal's carry
    crystallized at that deal's own exit -- see :func:`american_waterfall`)
    against carry the GP is entitled to once every deal is pooled into one
    whole-of-fund waterfall (see :func:`_pooled_entitlement`). The GP owes
    back the positive difference, if any.

    This is a genuinely different number from zero specifically *because*
    the two sides are computed two different ways: "received" is a sum of
    independent per-deal waterfalls, each blind to how the fund's other
    deals perform, while "entitled" is one waterfall over the pooled total.
    A European (whole-of-fund) structure never has this gap in the first
    place, because there carry is only ever paid once, off the same pooled
    totals used here as "entitled" -- so "received" and "entitled" are the
    same computation by construction and a clawback is structurally
    (near-)impossible. Running :func:`european_waterfall` once on the pooled
    series and comparing its ``gp_total`` to itself demonstrates this
    directly; see the test suite.

    Tax treatment of the clawback amount is deliberately not defaulted to a
    net-of-tax figure, even though many LPAs contractually cap the GP's
    payback obligation at what remains after the tax already paid on the
    excess carry. Computing that net figure needs the GP's actual effective
    tax rate on the carry, which this module has no way to know -- assuming
    one (a US corporate rate, a "typical" GP rate, anything) would be exactly
    the kind of invented number this codebase's evidence-first standard
    forbids. The default is therefore the gross, pre-tax clawback; passing
    ``gp_tax_rate`` opts into the net-of-tax figure the LPA actually specifies
    for this fund.

    Args:
        deals: Deal-id -> that deal's own cash flows. Every deal must share
            one currency.
        preferred_rate: Annual hurdle rate as a decimal, applied identically
            to every deal and to the pooled entitlement calculation.
        carry_rate: GP share of profit above the hurdle, in ``[0, 1)``.
        catch_up_rate: GP share of each catch-up dollar; ``0.0`` for no
            catch-up.
        termination_date: Measurement date for the pooled entitlement's
            preferred accrual. ``None`` uses the latest date anywhere across
            every deal -- the natural "fund winds up now" default. This does
            not affect the "received" side, which always uses each deal's own
            historical exit date, because carry already paid is a fact, not a
            modelling choice.
        compounding: One of :data:`PREFERRED_COMPOUNDING`.
        days_per_year: Day basis for the preferred accrual.
        include_unrealized_in_entitlement: Whether the pooled entitlement
            calculation adds each still-open deal's current NAV to the
            distributable amount -- an "if the fund wound up today" stress
            test. The "received" side never includes unrealised NAV, because
            unpaid carry cannot have been received.
        contribution_kinds: Kind labels counted as capital in.
        distribution_kinds: Kind labels counted as capital out.
        gp_tax_rate: If given, scales ``clawback_amount`` down to the
            net-of-tax figure by multiplying the gross clawback by
            ``(1 - gp_tax_rate)``. Must be in ``[0, 1)``. ``None`` (the
            default) reports the gross, pre-tax clawback -- see above for why
            that is the default rather than an assumed tax rate.

    Returns:
        A :class:`ClawbackResult`.

    Raises:
        TypeError: If ``deals`` is not a mapping, or a value is not a
            ``CashFlowSeries``.
        ValueError: If ``deals`` is empty or spans more than one currency, if
            ``gp_tax_rate`` is outside ``[0, 1)``, or if a deal raises any
            error :func:`european_waterfall` already documents.
    """
    deals = _validate_deals(deals)

    received = american_waterfall(
        deals,
        preferred_rate=preferred_rate,
        carry_rate=carry_rate,
        catch_up_rate=catch_up_rate,
        as_of=None,
        compounding=compounding,
        days_per_year=days_per_year,
        include_residual=False,
        contribution_kinds=contribution_kinds,
        distribution_kinds=distribution_kinds,
    )
    carry_received = received.gp_total

    entitled = _pooled_entitlement(
        deals,
        preferred_rate=preferred_rate,
        carry_rate=carry_rate,
        catch_up_rate=catch_up_rate,
        as_of=termination_date,
        compounding=compounding,
        days_per_year=days_per_year,
        include_residual=include_unrealized_in_entitlement,
        contribution_kinds=contribution_kinds,
        distribution_kinds=distribution_kinds,
    )
    carry_entitled = entitled.gp_total

    gross_clawback = max(0.0, carry_received - carry_entitled)
    if gp_tax_rate is None:
        return ClawbackResult(
            carry_received=carry_received,
            carry_entitled=carry_entitled,
            clawback_amount=gross_clawback,
            tax_adjusted=False,
            gp_tax_rate=None,
        )
    if not 0.0 <= gp_tax_rate < 1.0:
        raise ValueError(f"gp_tax_rate must be in [0, 1), got {gp_tax_rate!r}")
    return ClawbackResult(
        carry_received=carry_received,
        carry_entitled=carry_entitled,
        clawback_amount=gross_clawback * (1.0 - gp_tax_rate),
        tax_adjusted=True,
        gp_tax_rate=gp_tax_rate,
    )