capstack-lbo 0.1.0__py3-none-any.whl

capstack/sensitivity.py

@@ -0,0 +1,940 @@
+"""The same deal, run again under a different assumption.
+
+Every layer below this one reports one case. A deal team does not argue about
+one case. It argues about the boundary between the cases that work and the cases
+that do not, and that boundary is a surface rather than a point: the return
+holds at eleven times and a five-year hold, and does not hold at eleven times
+and four years, and the interesting question is where in between it stops.
+
+*Why the whole engine runs per cell.* The cheap way to build a grid is to
+differentiate the base case once and step along the gradient. It is also wrong,
+and wrong asymmetrically. Raising the entry multiple raises the purchase price,
+which the funding table absorbs into the sponsor cheque, which changes the
+capital every multiple in the column is measured against — and, because the debt
+did not move, changes opening leverage and therefore the sweep step and
+therefore the debt outstanding at exit. Lowering the *exit* multiple does none of
+that: it touches the last period and nothing upstream. A linearisation reports
+those two as mirror images. They are not, and the deals that get done live in
+exactly that asymmetry.
+
+So a cell is a deal rebuilt from its assumptions and run end to end. It costs
+more and it is the only way the table means what it says.
+
+*Why a cell can fail without the table failing.* Flex far enough and the engine
+runs out of deal: the equity is wiped out, the fixed point will not converge, the
+structure raises more than the purchase needs. Those cells are worth seeing —
+they are the edge of the surface, which is the thing being looked for — so a cell
+holds either a number or the reason there is not one, and the rest of the grid
+prints either way.
+
+*Why every cell carries a covenant flag.* A cell that clears the return
+threshold and trips a maintenance test in year three is not a cell that works.
+The lenders can accelerate from that date and everything after it is
+hypothetical. The metric answers the question that was asked; the flag says
+whether the answer was reachable.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from enum import Enum
+
+from .covenants import CovenantReport
+from .debt import CircularityError, DebtSchedule
+from .drivers import Driver
+from .money import ONE, ZERO, Money, money, quantize, rescale, safe_div
+from .operating import OperatingAssumptions, OperatingModel
+from .outcome import Outcome
+from .periods import PeriodGrid
+from .spec import Deal
+from .tax import EarningsBase, InterestLimit, LeveredSolution
+
+__all__ = [
+    "Axis",
+    "Breakeven",
+    "Case",
+    "Cell",
+    "Dimension",
+    "Grid",
+    "Metric",
+    "SensitivityError",
+    "Unit",
+    "format_value",
+    "solve",
+]
+
+
+class SensitivityError(ValueError):
+    """The grid cannot be built as described."""
+
+
+#: Failures that mean *this cell has no answer* rather than *the request was
+#: malformed*. ``ArithmeticError`` covers both a division by zero and a decimal
+#: operation that overflows, which a far enough flex will eventually produce.
+CELL_FAILURES = (ValueError, ArithmeticError, CircularityError)
+
+
+class Unit(Enum):
+    """How a number on an axis or in a cell should be read."""
+
+    RATE = "rate"
+    MULTIPLE = "multiple"
+    TURNS = "turns"
+    AMOUNT = "amount"
+    SHARE = "share"
+    YEARS = "years"
+    POINTS = "points"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+def _round(value: Money, places: int) -> Money:
+    """Round for display, without carrying a sign onto a zero.
+
+    A rate of minus four thousandths of a percent rounds to nought, and
+    printing that as ``-0.0%`` reads as a defect in the model rather than as a
+    small number. The sign is dropped only once the magnitude has already gone.
+    """
+    rounded = quantize(value, places)
+    # ``abs`` rather than ZERO, so a zero keeps the scale of its neighbours and
+    # the column still reads 0.0% beside 17.1% rather than a bare 0%.
+    return abs(rounded) if rounded == 0 else rounded
+
+
+def format_value(unit: Unit, value: Money) -> str:
+    """Render ``value`` the way its unit is spoken.
+
+    Shared between the grid and whatever prints it, because an axis header and
+    the cells beneath it disagreeing about how many decimal places a turn of
+    leverage has is the kind of thing that gets noticed in a committee.
+    """
+    if unit is Unit.RATE or unit is Unit.SHARE:
+        return f"{_round(value * money(100), 1)}%"
+    if unit is Unit.MULTIPLE or unit is Unit.TURNS:
+        return f"{_round(value, 2)}x"
+    if unit is Unit.YEARS:
+        return f"{_round(value, 0)}y"
+    if unit is Unit.POINTS:
+        points = _round(value * money(100), 2)
+        # Trailing zeros are stripped by hand rather than by ``normalize``,
+        # which turns fifty into 5E+1 and makes a committee pack look broken.
+        digits = f"{points:f}".rstrip("0").rstrip(".") or "0"
+        sign = "+" if points > 0 else ""
+        return f"{sign}{digits}pp"
+    return f"{_round(value, 1):,}"
+
+
+# -- Dimensions ----------------------------------------------------------
+
+
+def _shift(driver: Driver, by: Money) -> Driver:
+    """Move every period of an assumption by the same amount.
+
+    A parallel shift rather than a scaling. "Margin 150bp lower throughout" is
+    the sentence an investment committee says; "margin 8% lower than plan"
+    means something different in year one than in year five and is almost never
+    what was meant.
+    """
+    return Driver(values=tuple(v + by for v in driver.values))
+
+
+def _with_entry_multiple(deal: Deal, value: Money) -> Deal:
+    valuation = dataclasses.replace(deal.transaction.valuation, entry_multiple=value)
+    return dataclasses.replace(
+        deal, transaction=dataclasses.replace(deal.transaction, valuation=valuation)
+    )
+
+
+def _with_exit_multiple(deal: Deal, value: Money) -> Deal:
+    return dataclasses.replace(deal, exit_multiple=value)
+
+
+def _with_interest_limit(deal: Deal, rate: Money) -> Deal:
+    """Cap the interest deduction at ``rate`` of earnings.
+
+    Applied to a deal whose file caps nothing, this *creates* the cap, which is
+    deliberate: "what would a cap cost this deal" is the question most worth
+    asking of a structure that was underwritten without one. The earnings base
+    comes from the file where it has one and defaults otherwise, because the
+    axis moves the rate and the base is a different question.
+    """
+    if rate < 0:
+        raise SensitivityError("a deduction cap is a share of earnings, so not below zero")
+    base = deal.interest_limit.base if deal.interest_limit is not None else EarningsBase.EBITDA
+    return dataclasses.replace(deal, interest_limit=InterestLimit(rate=rate, base=base))
+
+
+def _with_leverage(deal: Deal, turns: Money) -> Deal:
+    """Resize the funded debt to ``turns`` of LTM EBITDA.
+
+    Every tranche is scaled by the same factor, which holds the shape of the
+    structure — the split between term loan, notes and mezzanine — while moving
+    its size. Revolver commitments are left alone: a commitment is negotiated
+    against the working-capital swing of the business, not against how much term
+    debt sits above it, and scaling it would quietly change how much liquidity
+    the case assumes at the same time as the leverage.
+
+    The sponsor cheque absorbs the difference, because it is the plug.
+    """
+    if turns < 0:
+        raise SensitivityError("leverage is measured in turns of EBITDA, so not below zero")
+    if deal.transaction.total_debt <= 0:
+        raise SensitivityError(
+            "this deal funds no debt, so there is no leverage to flex; the "
+            "structure would have to be described before it can be resized"
+        )
+    target = deal.transaction.valuation.ltm_ebitda * turns
+    faces = rescale(target, [t.face for t in deal.transaction.debt])
+    sized = dict(zip((t.name for t in deal.transaction.debt), faces, strict=True))
+    transaction = dataclasses.replace(
+        deal.transaction,
+        debt=tuple(
+            dataclasses.replace(t, face=sized[t.name]) for t in deal.transaction.debt
+        ),
+    )
+    structure = deal.structure
+    if structure is not None:
+        # The funding table and the schedule hold the same tranche twice, in two
+        # shapes. Resizing one and not the other would produce a deal that funds
+        # one amount of debt and services another, which balances nowhere.
+        structure = dataclasses.replace(
+            structure,
+            tranches=tuple(
+                dataclasses.replace(t, face=sized.get(t.name, t.face))
+                for t in structure.tranches
+            ),
+        )
+    return dataclasses.replace(deal, transaction=transaction, structure=structure)
+
+
+def _with_revenue_growth(deal: Deal, shift: Money) -> Deal:
+    operating = _operating(deal)
+    return dataclasses.replace(
+        deal,
+        operating=dataclasses.replace(
+            operating, revenue_growth=_shift(operating.revenue_growth, shift)
+        ),
+    )
+
+
+def _with_ebitda_margin(deal: Deal, shift: Money) -> Deal:
+    operating = _operating(deal)
+    return dataclasses.replace(
+        deal,
+        operating=dataclasses.replace(
+            operating, ebitda_margin=_shift(operating.ebitda_margin, shift)
+        ),
+    )
+
+
+def _with_exit_year(deal: Deal, years: Money) -> Deal:
+    """Hold the case and move the exit.
+
+    The grid is rebuilt from close rather than sliced, so this works in both
+    directions: an assumption series shorter than the new grid holds its final
+    value, which is what extending a case means, and one longer than it is
+    simply not reached.
+    """
+    if deal.grid is None:
+        raise SensitivityError(
+            "this deal has no projection, so there is no exit year to move"
+        )
+    if years != years.to_integral_value():
+        raise SensitivityError(
+            f"the exit year is a whole number of years, so {years} is not one"
+        )
+    count = int(years)
+    if count <= 0:
+        raise SensitivityError("a hold has to be at least one year long")
+    return dataclasses.replace(
+        deal, grid=PeriodGrid.build(deal.grid.start, count, deal.grid.frequency)
+    )
+
+
+def _with_base_rate(deal: Deal, shift: Money) -> Deal:
+    structure = deal.structure
+    if structure is None or structure.base_rate is None:
+        raise SensitivityError(
+            "this structure prices off no floating base rate, so there is "
+            "nothing to shift; the tranches are fixed-rate"
+        )
+    return dataclasses.replace(
+        deal,
+        structure=dataclasses.replace(
+            structure, base_rate=_shift(structure.base_rate, shift)
+        ),
+    )
+
+
+def _operating(deal: Deal) -> OperatingAssumptions:
+    if deal.operating is None:
+        raise SensitivityError(
+            "this deal has no operating case, so there are no drivers to flex"
+        )
+    return deal.operating
+
+
+class Dimension(Enum):
+    """An assumption the grid can move, and what moving it means.
+
+    Two kinds live here and the distinction matters when reading an axis. A
+    *level* dimension is set to the value given — an entry multiple of 11.5 is
+    11.5. A *shift* dimension is added to whatever the file says, across every
+    period, so its base case sits at zero and its axis reads as a departure.
+    """
+
+    ENTRY_MULTIPLE = "entry-multiple"
+    EXIT_MULTIPLE = "exit-multiple"
+    LEVERAGE = "leverage"
+    REVENUE_GROWTH = "revenue-growth"
+    EBITDA_MARGIN = "ebitda-margin"
+    EXIT_YEAR = "exit-year"
+    BASE_RATE = "base-rate"
+    INTEREST_LIMIT = "interest-limit"
+
+    def __str__(self) -> str:
+        return self.value
+
+    @property
+    def label(self) -> str:
+        return {
+            Dimension.ENTRY_MULTIPLE: "Entry multiple",
+            Dimension.EXIT_MULTIPLE: "Exit multiple",
+            Dimension.LEVERAGE: "Opening leverage",
+            Dimension.REVENUE_GROWTH: "Revenue growth",
+            Dimension.EBITDA_MARGIN: "EBITDA margin",
+            Dimension.EXIT_YEAR: "Exit year",
+            Dimension.BASE_RATE: "Base rate",
+            Dimension.INTEREST_LIMIT: "Interest deduction cap",
+        }[self]
+
+    @property
+    def unit(self) -> Unit:
+        return {
+            Dimension.ENTRY_MULTIPLE: Unit.MULTIPLE,
+            Dimension.EXIT_MULTIPLE: Unit.MULTIPLE,
+            Dimension.LEVERAGE: Unit.TURNS,
+            Dimension.REVENUE_GROWTH: Unit.POINTS,
+            Dimension.EBITDA_MARGIN: Unit.POINTS,
+            Dimension.EXIT_YEAR: Unit.YEARS,
+            # A level and not a shift: a cap of 30% is 30% of earnings, and an
+            # axis reading "two points off whatever the file says" would be
+            # meaningless on a file that caps nothing.
+            Dimension.INTEREST_LIMIT: Unit.RATE,
+            Dimension.BASE_RATE: Unit.POINTS,
+        }[self]
+
+    @property
+    def is_shift(self) -> bool:
+        """Whether the value is added to the file's assumption or replaces it."""
+        return self.unit is Unit.POINTS
+
+    @property
+    def is_continuous(self) -> bool:
+        """Whether values between two points on this dimension mean anything.
+
+        The exit year does not qualify. A hold of four and a half periods is
+        not a deal that could be done, and halving the interval towards one
+        would report a break-even nobody can act on.
+        """
+        return self is not Dimension.EXIT_YEAR
+
+    def apply(self, deal: Deal, value: Money) -> Deal:
+        """``deal`` as it would be with this dimension set to ``value``."""
+        return _APPLY[self](deal, value)
+
+    def read(self, deal: Deal) -> Money:
+        """Where ``deal`` already sits on this dimension.
+
+        A shift dimension always reads zero: the file is its own base case, and
+        the axis measures distance from it.
+        """
+        if self.is_shift:
+            return ZERO
+        if self is Dimension.ENTRY_MULTIPLE:
+            return deal.transaction.valuation.entry_multiple
+        if self is Dimension.EXIT_MULTIPLE:
+            return (
+                deal.exit_multiple
+                if deal.exit_multiple is not None
+                else deal.transaction.valuation.entry_multiple
+            )
+        if self is Dimension.LEVERAGE:
+            return safe_div(
+                deal.transaction.total_debt,
+                deal.transaction.valuation.ltm_ebitda,
+                default=ZERO,
+            )
+        if self is Dimension.INTEREST_LIMIT:
+            if deal.interest_limit is None:
+                raise SensitivityError(
+                    "this deal's file caps nothing, so there is no cap to centre an "
+                    'axis on; add an "interest_limit" to the operating block, or '
+                    "state the rates for the axis outright"
+                )
+            return deal.interest_limit.rate
+        if deal.grid is None:
+            raise SensitivityError(
+                "this deal has no projection, so there is no exit year to read"
+            )
+        return money(len(deal.grid)) / money(deal.grid.frequency.periods_per_year)
+
+
+_APPLY = {
+    Dimension.ENTRY_MULTIPLE: _with_entry_multiple,
+    Dimension.EXIT_MULTIPLE: _with_exit_multiple,
+    Dimension.LEVERAGE: _with_leverage,
+    Dimension.REVENUE_GROWTH: _with_revenue_growth,
+    Dimension.EBITDA_MARGIN: _with_ebitda_margin,
+    Dimension.EXIT_YEAR: _with_exit_year,
+    Dimension.BASE_RATE: _with_base_rate,
+    Dimension.INTEREST_LIMIT: _with_interest_limit,
+}
+
+
+# -- Metrics -------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Case:
+    """One deal, run end to end, with everything a metric might ask of it."""
+
+    deal: Deal
+    model: OperatingModel
+    schedule: DebtSchedule
+    outcome: Outcome
+    covenants: CovenantReport | None
+    #: The settled solve, where the case was run on a levered tax basis.
+    #: ``None`` on the default basis, where there is nothing to settle.
+    levered: LeveredSolution | None = None
+
+    @classmethod
+    def run(cls, deal: Deal, *, levered: bool = False) -> Case:
+        """Run every layer once.
+
+        The case and the schedule are computed here and handed down rather than
+        recomputed by each caller. The schedule solves a fixed point, and a grid
+        that solved it twice per cell would take twice as long to say the same
+        thing.
+
+        ``levered`` chooses which tax basis the structure is serviced out of.
+        The default taxes EBIT and services the debt out of unlevered free cash
+        flow, which is the convention the engine has always used and the one
+        every figure in the repository is struck on. Asking for the other
+        settles the interest deduction against the debt it is charged on, which
+        on the shipped deals is worth between 90 and 189 basis points of return
+        — so this is a choice about what the model means, not a refinement, and
+        it is made explicitly rather than by default.
+        """
+        model = deal.project()
+        solution = deal.levered(model) if levered else None
+        schedule = deal.schedule(model) if solution is None else solution.schedule
+        outcome = deal.realise(model, schedule)
+        covenants = (
+            deal.test_covenants(model, schedule) if deal.has_covenants else None
+        )
+        return cls(
+            deal=deal,
+            model=model,
+            schedule=schedule,
+            outcome=outcome,
+            covenants=covenants,
+            levered=solution,
+        )
+
+    @property
+    def breached(self) -> bool:
+        return self.covenants is not None and not self.covenants.passes
+
+
+class Metric(Enum):
+    """What a cell reports."""
+
+    IRR = "irr"
+    MOIC = "moic"
+    EQUITY_VALUE = "equity-value"
+    SPONSOR_EQUITY = "sponsor-equity"
+    ENTRY_LEVERAGE = "entry-leverage"
+    EXIT_LEVERAGE = "exit-leverage"
+    CUSHION = "cushion"
+    CASH_TAX = "cash-tax"
+    TAX_SAVING = "tax-saving"
+
+    def __str__(self) -> str:
+        return self.value
+
+    @property
+    def label(self) -> str:
+        return {
+            Metric.IRR: "IRR",
+            Metric.MOIC: "MoIC",
+            Metric.EQUITY_VALUE: "Equity value at exit",
+            Metric.SPONSOR_EQUITY: "Sponsor equity at close",
+            Metric.ENTRY_LEVERAGE: "Net leverage at close",
+            Metric.EXIT_LEVERAGE: "Net leverage at exit",
+            Metric.CUSHION: "Tightest covenant cushion",
+            Metric.CASH_TAX: "Cash tax over the hold",
+            Metric.TAX_SAVING: "Cash tax saved by the deduction",
+        }[self]
+
+    @property
+    def unit(self) -> Unit:
+        return {
+            Metric.IRR: Unit.RATE,
+            Metric.MOIC: Unit.MULTIPLE,
+            Metric.EQUITY_VALUE: Unit.AMOUNT,
+            Metric.SPONSOR_EQUITY: Unit.AMOUNT,
+            Metric.ENTRY_LEVERAGE: Unit.TURNS,
+            Metric.EXIT_LEVERAGE: Unit.TURNS,
+            Metric.CUSHION: Unit.SHARE,
+            Metric.CASH_TAX: Unit.AMOUNT,
+            Metric.TAX_SAVING: Unit.AMOUNT,
+        }[self]
+
+    @property
+    def needs_covenants(self) -> bool:
+        return self is Metric.CUSHION
+
+    @property
+    def needs_levered(self) -> bool:
+        """Whether this metric can only be read off a settled solve.
+
+        There is nothing to report for either of these on the unlevered basis:
+        the structure's cash tax is the operating case's own tax line, and the
+        saving is zero by construction. Refusing the grid up front is better
+        than filling it with the same excuse in every cell.
+        """
+        return self in (Metric.CASH_TAX, Metric.TAX_SAVING)
+
+    def read(self, case: Case) -> tuple[Money | None, str]:
+        """The figure, or the reason there is not one.
+
+        The reason travels with the missing number. A blank cell in a committee
+        pack gets read as a zero unless something says otherwise.
+        """
+        outcome = case.outcome
+        if self is Metric.IRR:
+            if outcome.irr is None:
+                return None, _no_rate(case)
+            return money(repr(outcome.irr)), ""
+        if self is Metric.MOIC:
+            if outcome.moic is None:
+                return None, "no capital was invested"
+            return outcome.moic, ""
+        if self is Metric.EQUITY_VALUE:
+            return outcome.valuation.equity_value, ""
+        if self is Metric.SPONSOR_EQUITY:
+            return case.deal.transaction.sponsor_equity, ""
+        if self is Metric.ENTRY_LEVERAGE:
+            net_debt = case.deal.transaction.total_debt - case.schedule.opening_cash
+            return (
+                safe_div(
+                    net_debt, case.deal.transaction.valuation.ltm_ebitda, default=ZERO
+                ),
+                "",
+            )
+        if self is Metric.EXIT_LEVERAGE:
+            return outcome.valuation.exit_leverage, ""
+        if self in (Metric.CASH_TAX, Metric.TAX_SAVING):
+            if case.levered is None:
+                return None, "this case was not run on a levered tax basis"
+            if self is Metric.CASH_TAX:
+                return case.levered.tax.total_cash_tax, ""
+            return case.levered.total_shield, ""
+        if case.covenants is None:
+            return None, "this deal describes no covenants"
+        cushion = case.covenants.minimum_cushion
+        if cushion is None:
+            return None, "no covenant is testable on this case"
+        return cushion, ""
+
+
+def _no_rate(case: Case) -> str:
+    if case.outcome.valuation.is_wiped_out:
+        return "the equity is wiped out"
+    return "there is no rate on these flows"
+
+
+# -- The grid ------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Axis:
+    """One side of the table: a dimension and the values stepped along it."""
+
+    dimension: Dimension
+    values: tuple[Money, ...]
+
+    def __post_init__(self) -> None:
+        if not self.values:
+            raise SensitivityError(
+                f"{self.dimension}: an axis needs at least one value on it"
+            )
+        if len(set(self.values)) != len(self.values):
+            raise SensitivityError(f"{self.dimension}: an axis repeats a value")
+
+    def __len__(self) -> int:
+        return len(self.values)
+
+    def __iter__(self) -> Iterator[Money]:
+        return iter(self.values)
+
+    @classmethod
+    def of(cls, dimension: Dimension, values: Sequence[Money | str | int]) -> Axis:
+        return cls(dimension=dimension, values=tuple(money(v) for v in values))
+
+    @classmethod
+    def parse(cls, text: str) -> Axis:
+        """Read ``dimension:v1,v2,v3``.
+
+        Percentage-point axes are written the way they are said — ``-1.5`` for a
+        hundred and fifty basis points off — and divided by a hundred here. An
+        axis of raw decimals for a shift would be ``-0.015``, which is easy to
+        mistype by a factor of ten and hard to spot once it is in the table.
+        """
+        name, _, values_text = text.partition(":")
+        name = name.strip().lower()
+        try:
+            dimension = Dimension(name)
+        except ValueError:
+            known = ", ".join(d.value for d in Dimension)
+            raise SensitivityError(
+                f"unknown dimension {name!r}; expected one of {known}"
+            ) from None
+        if not values_text.strip():
+            raise SensitivityError(
+                f"{name}: say which values to step along, as {name}:1,2,3"
+            )
+        values = []
+        for token in values_text.split(","):
+            token = token.strip()
+            if not token:
+                continue
+            try:
+                value = Decimal(token)
+            except InvalidOperation:
+                raise SensitivityError(f"{name}: not a number: {token!r}") from None
+            values.append(value / money(100) if dimension.is_shift else value)
+        return cls(dimension=dimension, values=tuple(values))
+
+    def format(self, value: Money) -> str:
+        return format_value(self.dimension.unit, value)
+
+    def is_base(self, value: Money, deal: Deal) -> bool:
+        """Whether ``value`` is where the file already sits on this dimension."""
+        try:
+            return self.dimension.read(deal) == value
+        except SensitivityError:
+            return False
+
+
+@dataclass(frozen=True, slots=True)
+class Cell:
+    """One cell: the coordinates, the figure, and whether it was reachable."""
+
+    row: Money
+    column: Money
+    value: Money | None
+    note: str = ""
+    breached: bool = False
+    breach_note: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.value is not None
+
+
+@dataclass(frozen=True, slots=True)
+class Grid:
+    """A metric read across two axes, plus the base case it moves around."""
+
+    rows: Axis
+    columns: Axis
+    metric: Metric
+    cells: tuple[tuple[Cell, ...], ...]
+    base: Money | None
+    base_note: str = ""
+
+    def __len__(self) -> int:
+        return len(self.cells)
+
+    def __iter__(self) -> Iterator[tuple[Cell, ...]]:
+        return iter(self.cells)
+
+    def at(self, row: int, column: int) -> Cell:
+        return self.cells[row][column]
+
+    @property
+    def populated(self) -> tuple[Cell, ...]:
+        return tuple(c for line in self.cells for c in line if c.ok)
+
+    @property
+    def failures(self) -> tuple[Cell, ...]:
+        return tuple(c for line in self.cells for c in line if not c.ok)
+
+    @property
+    def breaches(self) -> tuple[Cell, ...]:
+        return tuple(c for line in self.cells for c in line if c.breached)
+
+    @classmethod
+    def run(
+        cls,
+        deal: Deal,
+        rows: Axis,
+        columns: Axis,
+        metric: Metric,
+        *,
+        levered: bool = False,
+    ) -> Grid:
+        """Rebuild and run ``deal`` at every intersection of the two axes.
+
+        ``levered`` passes the tax basis down to every cell. It costs real time
+        — a settled cell solves the schedule several times over rather than
+        once — and it moves the answer by 90 to 189 basis points on the shipped
+        deals, which is more than the width of most of the bands a grid like
+        this is read for.
+        """
+        if rows.dimension is columns.dimension:
+            raise SensitivityError(
+                f"both axes move the {rows.dimension.label.lower()}; a grid needs "
+                f"two different assumptions to be a grid"
+            )
+        if metric.needs_covenants and not deal.has_covenants:
+            raise SensitivityError(
+                f"{metric.label.lower()} is measured against maintenance tests, "
+                f'and this deal describes none; add a "covenants" block'
+            )
+        if metric.needs_levered and not levered:
+            raise SensitivityError(
+                f"{metric.label.lower()} is a figure only a levered tax basis "
+                "produces; on the default basis the structure's cash tax is the "
+                "operating case's own and the saving is zero by construction. "
+                "Run the grid with levered=True, or from the command line with "
+                "--levered"
+            )
+        # The base case is run before anything is flexed, so a grid built on a
+        # deal that does not run at all fails outright instead of printing a
+        # table of identical excuses.
+        base_case = Case.run(deal, levered=levered)
+        base, base_note = metric.read(base_case)
+
+        lines = []
+        for row in rows:
+            line = []
+            for column in columns:
+                line.append(_cell(deal, rows, row, columns, column, metric, levered=levered))
+            lines.append(tuple(line))
+        return cls(
+            rows=rows,
+            columns=columns,
+            metric=metric,
+            cells=tuple(lines),
+            base=base,
+            base_note=base_note,
+        )
+
+
+def _cell(
+    deal: Deal,
+    rows: Axis,
+    row: Money,
+    columns: Axis,
+    column: Money,
+    metric: Metric,
+    *,
+    levered: bool = False,
+) -> Cell:
+    """Rebuild the deal at one intersection and read the metric off it."""
+    try:
+        flexed = columns.dimension.apply(rows.dimension.apply(deal, row), column)
+        case = Case.run(flexed, levered=levered)
+    except CELL_FAILURES as exc:
+        return Cell(row=row, column=column, value=None, note=str(exc))
+    value, note = metric.read(case)
+    breach = case.covenants.first_breach if case.covenants is not None else None
+    return Cell(
+        row=row,
+        column=column,
+        value=value,
+        note=note,
+        breached=breach is not None,
+        breach_note=(
+            "" if breach is None else f"{breach.covenant} in period {breach.index}"
+        ),
+    )
+
+
+
+# -- Break-evens ---------------------------------------------------------
+
+
+#: Halvings of the bracket. Twenty-four takes a ten-turn bracket below a
+#: millionth, which is far past what any of these dimensions is quoted to, and
+#: costs a hundred-odd engine runs rather than the thousands an open-ended
+#: search could.
+BISECTION_STEPS = 24
+
+
+@dataclass(frozen=True, slots=True)
+class Breakeven:
+    """Where a metric crosses a level, along one dimension.
+
+    ``value`` is ``None`` when there is no crossing inside the bracket, and the
+    note says which of the several reasons applied. A break-even that does not
+    exist and a break-even that was not looked for hard enough are different
+    facts about a deal, and a reader is entitled to know which one they have.
+    """
+
+    dimension: Dimension
+    metric: Metric
+    target: Money
+    low: Money
+    high: Money
+    value: Money | None
+    note: str = ""
+
+    @property
+    def found(self) -> bool:
+        return self.value is not None
+
+    def format(self) -> str:
+        if self.value is None:
+            return "none"
+        return format_value(self.dimension.unit, self.value)
+
+
+def solve(
+    deal: Deal,
+    dimension: Dimension,
+    metric: Metric,
+    *,
+    target: Money = ZERO,
+    low: Money,
+    high: Money,
+    steps: int = BISECTION_STEPS,
+) -> Breakeven:
+    """Find where ``metric`` crosses ``target`` as ``dimension`` moves.
+
+    Bisection rather than a secant or a Brent step, and deliberately. Each
+    evaluation rebuilds and re-runs the whole engine, so the function is
+    expensive; more to the point it is not smooth. A cash sweep that steps at a
+    leverage rung and a covenant that starts testing in period two put real
+    discontinuities in these curves, and a method that assumes local linearity
+    will happily extrapolate across one and return a crossing that is not
+    there. Halving an interval assumes nothing but a sign change.
+
+    The bracket is required rather than guessed. An open-ended search over an
+    entry multiple would eventually wander into prices at which the deal does
+    not describe a transaction at all, and a break-even reported from out there
+    is worse than no break-even.
+    """
+    if not dimension.is_continuous:
+        raise SensitivityError(
+            f"{dimension.label.lower()} takes whole values, so a crossing "
+            f"between two of them is not a case anyone could do"
+        )
+    if low >= high:
+        raise SensitivityError(
+            f"the bracket runs from {low} to {high}, which is not a bracket"
+        )
+    if steps < 1:
+        raise SensitivityError("a bisection needs at least one step")
+    if metric.needs_covenants and not deal.has_covenants:
+        raise SensitivityError(
+            f"{metric.label.lower()} is measured against maintenance tests, "
+            f'and this deal describes none; add a "covenants" block'
+        )
+
+    def at(value: Money) -> tuple[Money | None, str]:
+        try:
+            case = Case.run(dimension.apply(deal, value))
+        except CELL_FAILURES as exc:
+            return None, str(exc)
+        reading, note = metric.read(case)
+        return (None, note) if reading is None else (reading - target, "")
+
+    def absent(note: str) -> Breakeven:
+        return Breakeven(
+            dimension=dimension,
+            metric=metric,
+            target=target,
+            low=low,
+            high=high,
+            value=None,
+            note=note,
+        )
+
+    at_low, low_note = at(low)
+    if at_low is None:
+        return absent(
+            f"the case cannot be valued at {format_value(dimension.unit, low)}: "
+            f"{low_note}"
+        )
+    at_high, high_note = at(high)
+    if at_high is None:
+        return absent(
+            f"the case cannot be valued at {format_value(dimension.unit, high)}: "
+            f"{high_note}"
+        )
+    if at_low == 0:
+        return _found(dimension, metric, target, low, high, low)
+    if at_high == 0:
+        return _found(dimension, metric, target, low, high, high)
+    if (at_low > 0) == (at_high > 0):
+        return absent(
+            f"{metric.label.lower()} does not cross "
+            f"{format_value(metric.unit, target)} between "
+            f"{format_value(dimension.unit, low)} and "
+            f"{format_value(dimension.unit, high)}"
+        )
+
+    lo, hi, sign_low = low, high, at_low > 0
+    two = money(2)
+    for _ in range(steps):
+        mid = (lo + hi) / two
+        value, note = at(mid)
+        if value is None:
+            # The engine stopped answering partway into the bracket, which
+            # means the crossing is somewhere in a region the model does not
+            # describe. Reporting the last iterate would dress that up as an
+            # answer.
+            return absent(
+                f"the case cannot be valued at "
+                f"{format_value(dimension.unit, mid)}, inside the bracket: {note}"
+            )
+        if value == 0:
+            return _found(dimension, metric, target, low, high, mid)
+        if (value > 0) == sign_low:
+            lo = mid
+        else:
+            hi = mid
+    return _found(dimension, metric, target, low, high, (lo + hi) / two)
+
+
+def _found(
+    dimension: Dimension,
+    metric: Metric,
+    target: Money,
+    low: Money,
+    high: Money,
+    value: Money,
+) -> Breakeven:
+    return Breakeven(
+        dimension=dimension,
+        metric=metric,
+        target=target,
+        low=low,
+        high=high,
+        value=value,
+    )
+
+
+#: A neutral shift, named because ``money(0)`` at a call site reads as an amount.
+NO_SHIFT: Money = ZERO
+
+#: A multiple of one, for the same reason.
+UNCHANGED: Money = ONE